BobbyTables.js
BobbyTables.js is a Javascript ORM library for the Dropbox datastore API. It handles serializing and deserializing objects to and from the remote Dropbox datastore as well as handling pushing/pulling updates
Usage
- Inserting data
- Using transactions
- Saving and loading snapshots
- Detecting changes
- Details on object serialization
- Advanced handling of object id's
API
Usage
Inserting data
var BobbyTables = ; var manager = 'token'; // NOTE: errors not handled for the sake of brevitymanager;
Using transactions
// every operation inside the transation will try to be pushed to Dropbox in a single// commit. If anything fails, all changes are reverted, the latest changes are pulled,// and the transaction will be re-applied until the commit succeeds or the number of// retries is exceededstore;
Saving and loading snapshots
// the local state of a datastore can be saved to a json objectvar json = store; // and can then be reloaded again laterdatastoreManager;
Detecting changes
{ store;} // waits continuously for remote changes;
Details on object serialization
The dropbox datastore API only has support for the following datatypes so any objects that have fields with an unsupported datastype will not be able to be serialized correctly (Arrays of any of the below data types are also supported)
Dropbox datatype | Javascript datatype |
---|---|
str | string |
number | number |
int | number |
timestamp | Date |
blob | Buffer |
Advanced handling of object id's
While BobbyTables will automatically look for an 'id' field on your objects when inserting and updating, it is possible to have more finegrained control over exactly which fields are used as the id for record objects. This can be useful in cases where you have domain objects that you cannot/do not wish to change in order to persist them to a datastore.
The way around this is to provide an id getter function which will return the value that should be used as the id for the object.
var table = store;table;
Similarly, you can provide an id setter function when deserializing/enumerating objects if the object you are dealing with does not have a public 'id' field
var table = store;var banana = table;
API
DatastoreManager
This object is used for retrieving Datastore objects from dropbox. To create a DatastoreManager you will need a Dropbox OAuth 2.0 bearer token (You can get this by completing an OAuth 2.0 handshake - see https://www.dropbox.com/developers/core/docs#oa2-authorize for more details)
var BobbyTables = ; // A dropbox OAuth bearer tokenvar dropboxOAuthToken = 'xyzzy'; var datastoreManager = dropboxOAuthToken;
get(id, [opts,] callback)
Retrieves a Datastore with the given id, if no matching datastore could be found, then null is returned in the callback.
- opts
- forceRefresh (true/false) If true, calling get will always fetch the latest information from dropbox rather than using any locally cached data (defaults to false)
datastoreManager;
list([opts,] callback)
Retrieves an array of all available Datastores.
- opts
- forceRefresh (true/false) If true, calling get will always fetch the latest information from dropbox rather than using any locally cached data (defaults to false)
datastoreManager;
awaitListChanges(callback)
Waits for dropbox to notify whether the list of available Datastores has changed. The callback will either be called back with a value of true when a change occurs, or false if no changes were detected during the request timeout interval.
datastoreManager;
awaitDatastoreChanges(callback)
Waits for dropbox to notify whether the contents of any Datastore has changed. The callback will return with an array of all Datastore objects that have changed. If no changes were detected during the request timeout interval, then this array will be empty
datastoreManager;
getOrCreate(id, [opts,] callback)
Retrieves a Datastore with the given id or creates it if it doesn't already exist
- opts
- forceRefresh (true/false) If true, calling get will always fetch the latest information from dropbox rather than using any locally cached data (defaults to false)
datastoreManager;
create(key, callback)
Creates a Datastore with a shareable ID. The key parameter is used to generate the shared ID which is returned along with the created datastore on success
datastoreManager;
remove(store,callback)
Deletes the supplied Datastore object. The success callback returns true if the store was deleted
datastoreManager
});
load(json,callback)
Load a serialized datastore in json (as output by Datastore.save) into a Datastore object
datastoreManager;
Datastore
A datastore is an object which contains a number of tables containing dropbox datastore records.
save()
Saves the datastore as a json object
var json = store;
revert()
Reverts all pending local changes
store;
pull(callback)
Pulls in and applys to the datastore any remote changes from dropbox
store;
awaitPull(callback)
Wait for a remote change to occur and applies the changes if detected
store;
push(callback)
Push any local changes to dropbox
store;
transaction(actions)
Creates a transaction object for this datastore
store;
getTable(id)
Gets a Table from the datastore or creates it if it doesn't exist
var table = store;
Table
Represents a set of rows in a datastore. Rows can be added, updated, and removed similar to a traditional database. NOTE: No changes made to the database are sent to dropbox until the datastore push function is called.
insert(object[,opts])
Insert a javascript object into the table.
- opts
- idGetter: A function that returns the id value to be used to store the object in the table. If omitted it is assumed that there will be an 'id' field on the object.
- idSetter: A function that sets the id property of the object (if no id is found via the idGetter). If omitted it is assumed that the id should be set on the objects 'id' field.
var object = id: 'xxxx' description: 'hello world';if table // object inserted! else // object could not be inserted
remove(id)
Remove an object with the matching id from the table
if table // object removed! else //object could not be removed
get(id[, opts])
Get an object stored in the table with the specified id
- opts
- idSetter: A function that sets the id property of the object to the id of the row. If omitted the objects 'id' field will be set to the id value
var object = table;
getAll([opts])
Gets an array of all objects stored in the table
- opts
- idSetter: A function that sets the id property of the object to the id of the row. If omitted the objects 'id' field will be set to the id value
var objects = table;
update(object[, opts])
Updates an existing object in the table. An error will occur if no object with the matching id exists in the table.
- opts
- idGetter: A function that returns the id value to be used to store the object in the table. If omitted it is assumed that there will be an 'id' field on the object.
var object = id: 'xxxx' description: 'hello world'table; objectdescription = 'Hello world!';if table // object updated! else // could not update object
License
BobbyTables.js is licensed under the MIT license.