Initial rewrite of Readme for RC1 release
Project: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/repo Commit: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/commit/05758e08 Tree: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/tree/05758e08 Diff: http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/diff/05758e08 Branch: refs/heads/master Commit: 05758e08541038e617afa9158726cae71a62a557 Parents: 2a6a655 Author: brandon <bran...@behemoth.ca> Authored: Tue Feb 9 19:10:58 2016 -0800 Committer: brandon <bran...@behemoth.ca> Committed: Tue Feb 9 19:10:58 2016 -0800 ---------------------------------------------------------------------- README.md | 340 ++++++++++++++++++++++++++++++++++++++++--- tests/lib/asset.test.js | 8 +- 2 files changed, 322 insertions(+), 26 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/blob/05758e08/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index e88fab0..7a83136 100644 --- a/README.md +++ b/README.md @@ -4,28 +4,26 @@ # usergrid-nodejs Node.js SDK 2.0 for Usergrid -Currently a work in progress; documentation and implementation are subject to change. +Version 2.0 of this SDK is currently a work in progress; documentation and implementation are subject to change. -_**Note:** This Node.js SDK 2.0 for Usergrid is **not** backwards compatible with 0.1X versions of the SDK. If your application is dependent on the 0.1X set of Node.js APIs, you will need to continue using the 0.1X version (see below for installation instructions)._ +**Note:** This Node.js SDK 2.0 for Usergrid is **not** backwards compatible with 0.1X versions of the SDK. If your application is dependent on the 0.1X set of Node.js APIs, you will need to continue using the 0.1X version (see below for installation instructions)._ -### Current release +## Current Release -[Release Candidate 0](https://github.com/r3mus/usergrid-nodejs/releases), available here or on npm +- Pre-release: [Release Candidate 1](https://github.com/r3mus/usergrid-nodejs/releases), available here or on npm +- Stable: [0.10.11](https://github.com/apache/usergrid/tree/master/sdks/nodejs) -### Bugs +## 2.X Bugs Please open an [issue](https://github.com/r3mus/usergrid-nodejs/issues/new) -### Known Issues +## Known Issues -- AuthFallback is incomplete; currently there is no ad-hoc implementation for authentication (e.g. you cannot pass a instance of UsergridAuth, nor can you force a call to be made unauthenticated if there is a stored token) -- Authentication header is missing from certain API calls that don't leverage the UsergridRequest class. Recommend refactoring UsergridRequest to support all types of API calls (including login, logout, reset password) -- Assets are not implemented yet -- Many missing tests around authentication and passing a UsergridClient as a separate instance -- Easy (clean) way to load the UsergridClient module without referencing the full path -- Any other functionality that is missing or expected, please open an issue +- Native support for push notifications is slated for RC2. Workaround is to send a regular POST request to `'devices/<device_ID>/notifications'` +- There is no clean way to require submodules (e.g. `UsergridClient` or `UsergridEntity`) modules without referencing the full path to `../lib/client`. +- Any other functionality that is missing or expected, please open an issue. -### Installation +## Installation To install the latest **stable** 0.1X build: @@ -43,26 +41,324 @@ If you want access to the latest development build (you will need to run `npm in npm install r3mus/usergrid-nodejs -### Usage +## Usage -_Note: This section is left intentionally light. In its current release candidate state, this SDK is only recommended for developers familiar with Usergrid, Node.js, and preferably Mocha tests. For full usage and implementation, have a look in `/tests`._ +_Note: This section is a work in progress. In its current release candidate state, this SDK is only recommended for developers familiar with Usergrid, Node.js, and preferably Mocha tests, and is not recommended for production applications. For more advance and comprehensive usage, see `/tests`._ -There are two fundamental ways to use the new Node SDK: +### Initialization -1. Singleton pattern: +There are two fundamental ways to implement the Usergrid Node.js SDK: + +1. The singleton pattern is both convenient and enables the developer to use a globally available and always-initialized instance of Usergrid. var Usergrid = require('usergrid') Usergrid.init({ - orgId: ..., - appId: ... + orgId: '<org-id>', + appId: '<app-id>' }) - // or from a config file, see config.sample.json + // or you can load from a config file; see config.sample.json var Usergrid = require('usergrid') Usergrid.init() // defaults to use config.json -2. Instance pattern (primarily used when connecting to multiple Usergrid targets): +2. The Instance pattern enables the develper to manage instances of the Usergrid client independently and in an isolated fashion. The primary use-case for this is when an application connects to multiple Usergrid targets: var UsergridClient = require('./node_modules/usergrid/lib/client') - var client = new UsergridClient(config) \ No newline at end of file + var client = new UsergridClient(config) + +_Note: The following examples assume you are using the `Usergrid` shared instance. If you've implemented the instance pattern instead, simply replace `Usergrid` with your client instance variable. See `/tests` for advanced usage._ + +## RESTful operations + +The Usergrid Node.js SDK is built on top of [request](https://github.com/request/request). As such behaves almost as a drop-in replacement. Where you would expect a standard error-first callback from request, the same is true of the Usergrid SDK methods. + +When making any RESTful call, a `type` parameter (or `path`) is always required. Whether you specify this as an argument or in an object as a parameter is up to you. + +### GET requests + +**GET entities in a collection** + + Usergrid.GET('collection', function(err, usergridResponse, entities) { + // entities is an array of UsergridEntity objects + }) + +**GET a specific entity in a collection by uuid or name** + + Usergrid.GET('collection', '<uuid-or-name>', function(err, usergridResponse, entity) { + // entity, if found, is a UsergridEntity object + }) + +**GET specific entities in a collection by passing a UsergridQuery object** + + var query = new UsergridQuery('cats') + .gt('weight', 2.4) + .contains('color', 'bl*') + .not + .eq('color', 'blue') + .or + .eq('color', 'orange') + + // this will build out the following query: + // select * where weight > 2.4 and color contains 'bl*' and not color = 'blue' or color = 'orange' + + Usergrid.GET(query, function(err, usergridResponse) { + // entities is an array of UsergridEntity objects matching the specified query + }) + +### POST and PUT requests + +POST and PUT requests both require a JSON body payload. You can pass either a standard JavaScript object or a `UsergridEntity` instance. While the former works in principle, best practise is to use a `UsergridEntity` wherever practical. When an entity has a uuid or name property and already exists on the server, use a PUT request to update it. If it does not, use POST to create it. + +**POST (create) a new entity in a collection** + + var entity = new UsergridEntity({ + type: 'restaurant', + restaurant: 'Dino's Deep Dish, + cuisine: 'pizza' + }) + + // or + + var entity = { + type: 'restaurant', + restaurant: 'Dino's Deep Dish, + cuisine: 'pizza' + } + + Usergrid.POST(entity, function(err, usergridResponse, entity) { + // entity should now have a uuid property and be created + }) + + // you can also POST an array of entities: + + var entities = [ + new UsergridEntity({ + type: 'restaurant', + restaurant: 'Dino's Deep Dish, + cuisine: 'pizza' + }), + new UsergridEntity({ + type: 'restaurant', + restaurant: 'Pizza da Napoli', + cuisine: 'pizza' + }) + ] + + Usergrid.POST(entities, function(err, usergridResponse, entities) { + // + }) + +**PUT (update) an entity in a collection** + + var entity = new UsergridEntity({ + type: 'restaurant', + restaurant: 'Pizza da Napoli', + cuisine: 'pizza' + }) + + Usergrid.POST(entity, function(err, usergridResponse, entity) { + entity.owner = 'Mia Carrara' + Usergrid.PUT(entity, function(err, usergridResponse, entity) { + // entity now has the property 'owner' + }) + }) + + // or update a set of entities by passing a UsergridQuery object + + var query = new UsergridQuery('restaurants') + .eq('cuisine', 'italian') + + // this will build out the following query: + // select * where cuisine = 'italian' + + Usergrid.PUT(query, { keywords: ['pasta'] }, function(err, usergridResponse) { + /* the first 10 entities matching this query criteria will be updated: + e.g.: + [ + { + "type": "restaurant", + "restaurant": "Il Tarazzo", + "cuisine": "italian", + "keywords": [ + "pasta" + ] + }, + { + "type": "restaurant", + "restaurant": "Cono Sur Pizza & Pasta", + "cuisine": "italian", + "keywords": [ + "pasta" + ] + } + ] + /* + }) + +### DELETE requests + +DELETE requests require either a specific entity or a `UsergridQuery` object to be passed as an argument. + +**DELETE a specific entity in a collection by uuid or name** + + Usergrid.DELETE('collection', '<uuid-or-name>', function(err, usergridResponse) { + // if successful, entity will now be deleted + }) + +**DELETE specific entities in a collection by passing a UsergridQuery object** + + var query = new UsergridQuery('cats') + .eq('color', 'black') + .or + .eq('color', 'white') + + // this will build out the following query: + // select * where color = 'black' or color = 'white' + + Usergrid.DELETE(query, function(err, usergridResponse) { + // the first 10 entities matching this query criteria will be deleted + }) + +## Entity operations and convenience methods + +`UsergridEntity` has a number of helper/convenience methods to make working with entities more convenient. + +### reload + + entity.reload(function(err, usergridResponse) { + // entity is now reloaded from the server + }) + +### save + + entity.aNewProperty = 'A new value' + entity.save(function(err, usergridResponse) { + // entity is now updated on the server + }) + +### remove + + entity.remove(function(err, usergridResponse) { + // entity is now deleted on the server and the local instance should be destroyed + }) + +## UsergridResponse + +`UsergridResponse` implements several Usergrid-specific enhancements to [request](https://github.com/request/request). Notably: + +### ok + +You can check `usergridResponse.ok`, a `bool` value, to see if the response was successful. Any status code < 400 returns true. + + Usergrid.GET('collection', function(err, usergridResponse, entities) { + if (usergridResponse.ok) { + // woo! + } + }) + +### entity, entities, user, users, first, last + +Depending on the call you make, you will receive either an array of UsergridEntity objects, or a single entity as the third parameter in the callback. If you're querying the `users` collection, these will also be `UsergridUser` objects, a subclass of `UsergridEntity`. + +- `.first` returns the first entity in an array of entities; `.entity` is an alias to `.first`. If there are no entities, both of these will be undefined. +- `.last` returns the last entity in an array of entities; if there is only one entity in the array, this will be the same as `.first` _and_ `.entity`, and will be undefined if there are no entities in the response. +- `.entities` will either be an array of entities in the response, or an empty array. +- `.user` is a special alias for `.entity` for when querying the `users` collection. Instead of being a `UsergridEntity`, it will be its subclass, `UsergridUser`. +- `.users` is the same as `.user`, though behaves as `.entities` does by returning either an array of UsergridUser objects or an empty array. + +Examples: + + Usergrid.GET('collection', function(err, usergridResponse, entities) { + // third param is an array of entities because no specific entity was referenced + // you can also access: + // usergridResponse.entities + // usergridResponse.first + // usergridResponse.entity (the first entity) + // usergridResponse.last + }) + + Usergrid.GET('collection', '<uuid or name>', function(err, usergridResponse, entity) { + // third param is a single entity object + // you can also access: + // usergridResponse.entity + // usergridResponse.first + // usergridResponse.last + }) + + Usergrid.GET('users', function(err, usergridResponse, users) { + // third param is an array of users because no specific user was referenced + // you can also access: + // usergridResponse.users + // usergridResponse.user (the first user) + // usergridResponse.last + }) + + Usergrid.GET('users', '<uuid, username, or email>', function(err, usergridResponse, user) { + // third param is a single user object + // you can also access: + // usergridResponse.user + }) + +## Assets + +Assets can be uploaded and downloaded either directly using `Usergrid.POST` or `Usergrid.PUT`, or via `UsergridEntity` convenience methods. Before uploading an asset, you will need to initialize a `UsergridAsset` instance. + +### UsergridAsset init + +**Loading a file system image via `fs.readFile()`** + + var asset = new UsergridAsset('myImage') + fs.readFile(_dirname + '/image.jpg', function(err, data) { + asset.data = data + }) + +**Loading a file system image from a read stream (`fs.createReadStream()`)** + + var asset = new UsergridAsset('myImage') + fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + // now contains Buffer stream at asset.data + }) + +You can also access `asset.contentType` and `asset.contentLength` once data has been loaded into a `UsergridAsset`. + +### .POST and .PUT + +**POST binary data to a collection by creating a new entity** + + var asset = new UsergridAsset('myImage') + fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + client.POST('collection', asset, function(err, assetResponse, entityWithAsset) { + // asset is now uploaded to Usergrid + }) + }) + +**PUT binary data to an existing entity via attachAsset()** + + var asset = new UsergridAsset('myImage') + fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + // assume entity already exists; attach it to the entity: + entity.attachAsset(asset) + client.PUT(entity, asset, function(err, assetResponse, entityWithAsset) { + // asset is now uploaded to Usergrid + }) + }) + +### UsergridEntity convenience methods + +**entity.uploadAsset() is a much simpler means of uploading an asset** + + var asset = new UsergridAsset('myImage') + fs.createReadStream(_dirname + '/image.jpg').pipe(asset).on('finish', function() { + // assume entity already exists; attach it to the entity: + entity.attachAsset(asset) + entity.uploadAsset(function(err, assetResponse, entityWithAsset) { + // asset is now uploaded to Usergrid + }) + }) + +**entity.downloadAsset() allows you to download a binary asset** + + entity.uploadAsset(function(err, assetResponse, entityWithAsset) { + // access the asset via entityWithAsset.asset + }) http://git-wip-us.apache.org/repos/asf/usergrid-nodejs/blob/05758e08/tests/lib/asset.test.js ---------------------------------------------------------------------- diff --git a/tests/lib/asset.test.js b/tests/lib/asset.test.js index 0911ea8..a25c494 100644 --- a/tests/lib/asset.test.js +++ b/tests/lib/asset.test.js @@ -75,14 +75,14 @@ describe('init from piped writable stream', function() { }) describe('upload via client.POST to a specific entity', function() { - + this.slow(_slow) this.timeout(_timeout) var client = new UsergridClient() it('should upload a binary asset and create a new entity', function(done) { var asset = new UsergridAsset(filename, file) - fs.createReadStream(file).pipe(asset).on('finish', function() { + fs.createReadStream(file).pipe(asset).on('finish', function() { client.POST(config.test.collection, asset, function(err, assetResponse, entityWithAsset) { assetResponse.statusCode.should.equal(200) entityWithAsset.should.have.property('file-metadata') @@ -91,7 +91,7 @@ describe('upload via client.POST to a specific entity', function() { entityWithAsset.remove(client) done() }) - }) + }) }) }) @@ -117,6 +117,6 @@ describe('upload via client.PUT to a specific entity', function() { done() }) }) - }) + }) }) }) \ No newline at end of file
