ansble-client
This is the npm client for ansble, a hosted schemaless queryable datastore. We are currently in alpha and if you want to try out our service email Daniel
USAGE
Setup
You are going to need a few of things to get up and running, one is this client, the others are your application key and token. These can be obtained by joining the alpha as mentioned above. Once you have them you use them like this to setup your client for communication:
var key = '43d8ef2fcdfc7bd9da1807548d43d086259e04ff'
, token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzY29wZXMiOltdLCJhcHAiOiI0M2Q4ZWYyZmNkZmM3YmQ5ZGExODA3NTQ4YzQzZDA4NjI1OWUwNGZmIiwianRpIjoiOTdhZTJmY2ZkYmJjZDExMzBjODU2YjhmYzNjODQxZmNhZTIzZWI3NCIsImlhdCI6MTQyNjg1MzcyM30.LGj8tiIM2REqZmDvma-m_ih8_18AMTOlL0amf3lL1Wa3qUK69S7eKGAhqXKejFuskbK5wvBanSTlCQXUflLQ6ZxWG_Rw7D-mV1YM76-NAPhho7Y6Tr26O3P64Rakl1L-3NVpdRIlfIAoufyv697dszhysqPyaKxNkwxUUQVqVKn71r_DmTYWvHFsOKHZY_ZJfHnfEkSR8d6szX9M3AoqIHeSZzTNz9jauO-IjsYcS_YoePdykCr8XpxK_eN4p7Tsy7v6fLVWaowEXvuC_INAGYrJbJ-OwCipEDn4gyjm2wZY2L2ez9AXR74BM6y9TCZVBbk6I73pxgwP3VhqBvqmKA'
, ansble = require('ansble-client')(key, token);
Add a new document or updating an existing document
The client exposes a single function for dealing with saving documents.
ansble.save({name: 'jane', type: 'computer', speciality: 'financial investing'}, function (doc) {}, function (err) {});
This saves the object passed in augmenting it with a _meta section that includes permissions, a created date, and updated date, and the app key that was used to create it. It looks like this:
{
access: [
{app: '43d8ef2fcdfc7bd9da1807548d43d086259e04ff', read:true, write:true, del:true}
]
, createdDate: 'Mon Mar 30 2015 07:29:35 GMT-0600 (MDT)'
, updatedDate: 'Mon Mar 30 2015 07:29:35 GMT-0600 (MDT)'
, createdBy: '43d8ef2fcdfc7bd9da1807548d43d086259e04ff'
};
Generally you won't need to modify the _meta object. Any changes you make to dates and createdBy will be ignored, but changes to access are allowed. This allows you to share objects between applications (or appication keys) with varying permissions. You can specifiy permissions with the read, write, del attributes set to true or false. Any application key with read permission on an object will see it in it's data store. Only those with del: true may delete an object and write follows the same pattern.
The saved document is also given an _id generated by the database. Alternately you can pass in your own _id for easy access later. This is probably not needed though as the querying detailed below allows for very powerful item retrieval.
The first function is the success handler it recieves the updated doc which in this example would look like:
{
_id: '550dd982c8f68d1100272fbc'
, name: 'jane'
, type: 'computer'
, speciality: 'financial investing'
, _meta: {
access: [
{app: '43d8ef2fcdfc7bd9da1807548d43d086259e04ff', read:true, write:true, del:true}
]
, createdDate: 'Mon Mar 30 2015 07:29:35 GMT-0600 (MDT)'
, updatedDate: 'Mon Mar 30 2015 07:29:35 GMT-0600 (MDT)'
, createdBy: '43d8ef2fcdfc7bd9da1807548d43d086259e04ff'
}
}
The second function is the error handler and it recieves any error that is generted by the system. It is optional and if it does not exist then it is ignored.
To update a document you simply pass the whole thing back into the ansble.save function.
Get all Documents
Once you have created some documents it makes sense that you would want to get them back out for use. The easiest way is to grab all of them:
ansble.get(function(docs) {
// you've got docs!
console.log(docs);
}, function (err) {
//sadness :-( an error occured
console.log(err);
});
This will return every document that your application key has read permissions for in an array.
Get a specific document
This looks much like getting all of your documents, excpet you pass in an ID and get back an object:
ansble.get('550dd982c8f68d1100272fbc', function(doc) {
// you've got the document!
console.log(doc);
}, function (err) {
//sadness :-( an error occured
console.log(err);
});
Delete a Doument
First you need to have the ID of the document that you want to delete, then you pass it to the remove function like this:
ansble.remove('550dd982c8f68d1100272fbc', function (doc) {}, function (err){});
Again success function, error function.
Queries (This is where it get's really cool!)
Now for the really cool part. This API uses the REPORT verb (less interesting to you then if you were writing this from scratch for the bored) to allow you to perform an idempotent request with a body. The body consists of an array of functions (Array.filter, Array.map, Array.reduce) that will be executed against all of the data that your application key has access to. Order is important so order your functions correctly.
Here is what that looks like:
ansble.query([
{
type: 'filter'
, body: function (item){
return typeof item.america === 'undefined';
}
}
, {
type: 'map'
, body: function (item){
return item._meta.createdDate;
}
}
, {
type: 'reduce'
, body: function (prev, current) {
return (new Date(prev).getTime() < new Date(current).getTime()) ? current : prev;
}
}
], function (docs) {
console.log(docs);
}
, function (err) {
console.log(err);
});
This ends up being essentially:
myData.filter(function (item){
return typeof item.america === 'undefined';
}).map(function (item){
return item._meta.createdDate;
}).reduce(function (prev, current) {
return (new Date(prev).getTime() < new Date(current).getTime()) ? current : prev;
});
and the return is the result of this execution. I won't dig into this in more depth here... but if you aren't sure how to use something like this then check out Array.prototype.map, Array.prototype.reduce and Array.prototype.filter. Only filter, map, and reduce functions are allowed at this point.
Offline and local development
Coming soon...
Tests
There are a bunch of tests that allow you to see how things work.