README.md

ShareDB

ShareDB is a realtime database backend based on Operational Transformation (OT) of JSON documents. It is the realtime backend for the DerbyJS web application framework.

For questions, discussion and announcements, join the ShareJS mailing list.

Please report any bugs you find to the issue tracker.

Features

• Realtime synchronization of any JSON document
• Concurrent multi-user collaboration
• Synchronous editing API with asynchronous eventual consistency
• Realtime query subscriptions
• Simple integration with any database - MongoDB
• Horizontally scalable with pub/sub integration - Redis
• Projections to select desired fields from documents and operations
• Middleware for implementing access control and custom extensions
• Ideal for use in browsers or on the server
• Reconnection of document and query subscriptions
• Offline change syncing upon reconnection
• In-memory implementations of database and pub/sub for unit testing

Quick tour

var ShareDB = require('sharedb');
var db = require('sharedb-mongo')('localhost:27017/test');

var backend = ShareDB({db: db});
var connection = backend.connect();

// Subscribe to any database query
var query = connection.createSubscribeQuery('users', {accountId: 'acme'});

query.once('ready', function() {
  // Initially matching documents
  console.log(query.results);
});
query.on('insert', function(docs, index) {
  // Documents that now match the query
  console.log(docs);
});
query.on('remove', function(docs, index) {
  // Documents that no longer match the query
  console.log(docs);
});
query.on('move', function(docs, from, to) {
  // Documents that were moved in the results order for sorted queries
  console.log(docs);
});

// Create and modify documents with synchronously applied operations
var doc = connection.get('users', 'jane');
doc.create({accountId: 'acme', name: 'Jane'});
doc.submitOp({p: ['email'], oi: '[email protected]'});

// Create multiple concurrent connections to the same document for
// collaborative editing by multiple clients
var connection2 = backend.connect();
var doc2 = connection2.get('users', 'jane');

// Subscribe to documents directly as well as through queries
doc2.subscribe(function(err) {
  // Current document data
  console.log(doc2.data);
});
doc2.on('op', function(op, source) {
  // Op that changed the document
  console.log(op);
  // truthy if submitted locally and `false` if from another client
  console.log(source);
});

Data model

In ShareDB's view of the world, every document has 3 properties:

• version - An incrementing number starting at 0
• type - An OT type. OT types are defined in share/ottypes. Documents which don't exist implicitly have a type of null.
• data - The actual data that the document contains. This must be pure acyclic JSON. Its also type-specific. (JSON type uses raw JSON, text documents use a string, etc).

ShareDB implicitly has a record for every document you can access. New documents have version 0, a null type and no data. To use a document, you must first submit a create operation, which will set the document's type and give it initial data. Then you can submit editing operations on the document (using OT). Finally you can delete the document with a delete operation. By default, ShareDB stores all operations forever - nothing is truly deleted.

Operations

See https://github.com/ottypes/json0 for documentation of the supported operations.