README IS WORK IN PROGRESS
Storage is a simple REST-based data model on top of an operational transformation engine. Storage is designed towards developing multi-surface applications, providing persistance and distributed and concurrent editing.
The core technologies used by Storage is CouchDB for persistance and ShareJS as the operational transformation engine.
storage provides a set of server defined typed resources. Resources consists of two parts, a shell and a body.
- shell: is what you traditionally would expect from a REST resource (see additional details under REST API).
- GET to http://www.example.com/MyResource returns a list of resources with type MyResource
- POST to http://www.example.com/MyResource creates a new resources of type MyResource
- POST to http://www.example.com/MyResource/myresource1 allows setting attributes on the MyResource with id myresource1
- body: every shell contains a body intended for realtime mutable data, this means data where notifications of updates are relevant for other concurrent clients.
- GET to http://www.example.com/MyResource/myresource1/body will return a snapshot of the current state of the body
- POST to http://www.example.com/MyResource/myresoirce1/body allows for sending JSON based operational transformations to the body according to the ShareJS documentation.
Besides resources typed with a collection type like MyResource described above, storage provides a singleton resource. A singleton provides a single uniquely named sharejs document that can be accessed with a GET on http://www.example.com/MySingleton
Each collection type has a singleton of e.g. named MyResourceMonitor this singleton is a list of the ids of all resources with type 'MyResource'. This singleton can be used to monitor when new resources of a given type is created.
###Initializing
Add these script tags:
<script src="/storage/channel/bcsocket.js"></script>
<script src="/storage/share/share.js"></script>
<script src="/storage/share/json.js"></script>
<script src="/storage/client.js"></script>
And add this code:
<script>
storage.initializeCache(function() {
//Storage is now initialized
});
</script>
###Get collection
storage.getCollection('MyCollection', function(err, shells) {
//...
});
###Get shell
storage.getShell('MyCollection', 'myshell1', function(err, doc) {
//...
});
###Get body of a shell
shell.getBody(function(err, body) {
//body is sharejs document
body.on('remoteop', function(op) {
//...
});
});
###Get Singleton
storage.getSingleton('MySingleton', function(err, singleton) {
//singleton is a sharejs document
});
###Get Collection monitor singleton
storage.getCollectionMonitor('MyCollection', function(err, monitor) {
//monitor is a sharejs document containing a list of shell IDs with type MyCollection
});
The storage server relies on the express web framework.
###Minimal storage server
cs = require('coffee-script');
express = require('express');
storage = require('storage');
storageServer = new storage.Storage();
app = express();
storageServer.attachServer(app, {'host': 'localhost', 'port': 5984, 'name': 'storage'}, function(app) {
storageServer.registerDocument('MyDocument', function(error) {
//You can now get an empty list of shells at http://localhost:8000/MyDocument
});
});
app.listen(8000);
###Register singleton
storageServer.registerSingleton("MySingleton"); //NB: Syncronous call, no need or callback
TODO
TODO