@evercoder/sharedb
Advanced tools
⚠️ This is a fork of ShareDB published as:
npm -i @evercoder/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 or check the FAQ.
Please report any bugs you find to the issue tracker.
TLDR
const WebSocket = require('reconnecting-websocket');
var socket = new WebSocket('ws://' + window.location.host);
var connection = new sharedb.Connection(socket);
The native Websocket object that you feed to ShareDB's Connection constructor does not handle reconnections.
The easiest way is to give it a WebSocket object that does reconnect. There are plenty of example on the web. The most important thing is that the custom reconnecting websocket, must have the same API as the native rfc6455 version.
In the "textarea" example we show this off using a Reconnecting Websocket implementation from reconnecting-websocket.
Simple app demonstrating realtime sync
Leaderboard app demonstrating live queries
In ShareDB's view of the world, every document has 3 properties:
null.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.
First, create a ShareDB server instance:
var ShareDB = require('sharedb');
var share = new ShareDB(options);
Options
options.db (instance of ShareDB.DB)
Store documents and ops with this database adapter. Defaults to ShareDB.MemoryDB().options.pubsub (instance of ShareDB.PubSub)
Notify other ShareDB processes when data changes
through this pub/sub adapter. Defaults to ShareDB.MemoryPubSub().ShareDB.MemoryDB, backed by a non-persistent database with no queriesShareDBMongo, backed by a real Mongo database
and full query supportShareDBMingoMemory, backed by
a non-persistent database supporting most Mongo queries. Useful for faster
testing of a Mongo-based app.ShareDBPostgres, backed by PostgresQL. No query support.ShareDB.MemoryPubSub can be used with a single processShareDBRedisPubSub can be used
with multiple processes using Redis' pub/sub mechanismCommunity Provided Pub/Sub Adapters
var WebSocketJSONStream = require('websocket-json-stream');
// 'ws' is a websocket server connection, as passed into
// new (require('ws').Server).on('connection', ...)
var stream = new WebSocketJSONStream(ws);
share.listen(stream);
For transports other than WebSockets, expose a duplex
stream that writes and reads JavaScript objects. Then
pass that stream directly into share.listen.
Middlewares let you hook into the ShareDB server pipeline. In middleware code you can read and also modify objects as they flow through ShareDB. For example, sharedb-access uses middlewares to implement access control.
share.use(action, fn)
Register a new middleware.
action (String)
One of:
'connect': A new client connected to the server.'op': An operation was loaded from the database.'readSnapshots': Snapshot(s) were loaded from the database for a fetch or subscribe of a query or document'query': A query is about to be sent to the database'submit': An operation is about to be submitted to the database'apply': An operation is about to be applied to a snapshot
before being committed to the database'commit': An operation was applied to a snapshot; The operation
and new snapshot are about to be written to the database.'afterSubmit': An operation was successfully submitted to
the database.'receive': Received a message from a clientfn (Function(request, callback))
Call this function at the time specified by action.
request contains a subset of the following properties, as relevant for the action:
action: The action this middleware is handingagent: An object corresponding to the server agent handing this clientreq: The HTTP request being handledcollection: The collection name being handledid: The document id being handledsnapshots: The retrieved snapshots for the readSnapshots actionquery: The query object being handledop: The op being handledShareDB supports exposing a projection of a real collection, with a specified (limited) set of allowed fields. Once configured, the projected collection looks just like a real collection - except documents only have the fields you've requested. Operations (gets, queries, sets, etc) on the fake collection work, but you only see a small portion of the data.
addProjection(name, collection, fields)
Configure a projection.
name The name of the projected collection.collection The name of the existing collection.fields A map (object) of the allowed fields in documents.
true.For example, you could make a users_limited projection which lets users view each other's names and profile pictures, but not password hashes. You would configure this by calling:
share.addProjection('users_limited', 'users', { name:true, profileUrl:true });
Note that only the JSON0 OT type is supported for projections.
By default, ShareDB logs to console. This can be overridden if you wish to silence logs, or to log to your own logging driver or alert service.
Methods can be overridden by passing a console-like object to logger.setMethods:
var ShareDB = require('sharedb');
ShareDB.logger.setMethods({
info: () => {}, // Silence info
warn: () => alerts.warn(arguments), // Forward warnings to alerting service
error: () => alerts.critical(arguments) // Remap errors to critical alerts
});
ShareDB only supports the following logger methods:
infowarnerrorshare.close(callback)
Closes connections to the database and pub/sub adapters.
The client API can be used from either Node or a browser. First, get a ShareDB.Connection object by connecting to the ShareDB server instance:
From Node:
// `share` should be a ShareDB server instance
var connection = share.connect();
To use ShareDB from a browser, use a client bundler like Browserify or Webpack. The following code connects to the ShareDB server instance over WebSockets:
var ShareDB = require('sharedb/lib/client');
var socket = new WebSocket('ws://localhost:8080');
var connection = new ShareDB.Connection(socket);
For transports other than WebSockets, create an object implementing
the WebSocket specification and pass it into the ShareDB.Connection constructor.
ShareDB.Connectionconnection.get(collectionName, documentId)
Get a ShareDB.Doc instance on a given collection and document ID.
connection.createFetchQuery(collectionName, query, options, callback)
connection.createSubscribeQuery(collectionName, query, options, callback)
Get query results from the server. createSubscribeQuery also subscribes to
changes. Returns a ShareDB.Query instance.
query (Object)
A descriptor of a database query with structure defined by the database adapter.callback (Function)
Called with (err, results) when server responds, or on error.options.results (Array)
Prior query results if available, such as from server rendering.options.*
All other options are passed through to the database adapter.connection.fetchSnapshot(collection, id, version, callback): void;
Get a read-only snapshot of a document at the requested version.
collection (String)
Collection name of the snapshot
id (String)
ID of the snapshot
version (number) [optional]
The version number of the desired snapshot
callback (Function)
Called with (error, snapshot), where snapshot takes the following form:
{
id: string; // ID of the snapshot
v: number; // version number of the snapshot
type: string; // the OT type of the snapshot, or null if it doesn't exist or is deleted
data: any; // the snapshot
}
ShareDB.Docdoc.type (String)
The OT type of this document
doc.id (String)
Unique document ID
doc.data (Object)
Document contents. Available after document is fetched or subscribed to.
doc.fetch(function(err) {...})
Populate the fields on doc with a snapshot of the document from the server.
doc.subscribe(function(err) {...})
Populate the fields on doc with a snapshot of the document from the server, and
fire events on subsequent changes.
doc.ingestSnapshot(snapshot, callback)
Ingest snapshot data. The snapshot param must include the fields v (doc version), data, and type (OT type). This method is generally called interally as a result of fetch or subscribe and not directly from user code. However, it may still be called directly from user code to pass data that was transferred to the client external to the client's ShareDB connection, such as snapshot data sent along with server rendering of a webpage.
doc.destroy()
Unsubscribe and stop firing events.
doc.on('load', function() {...})
The initial snapshot of the document was loaded from the server. Fires at the
same time as callbacks to fetch and subscribe.
doc.on('create', function(source) {...})
The document was created. Technically, this means it has a type. source will be false for ops received from the server and defaults to true for ops generated locally.
doc.on('before op batch'), function() {...})
An operation batch is about to be applied to the data. For each partial operation a pair of before op and op events will be emitted after this event.
doc.on('before op'), function(op, source) {...})
An operation is about to be applied to the data. source will be false for ops received from the server and defaults to true for ops generated locally.
doc.on('op', function(op, source) {...})
An operation was applied to the data. source will be false for ops received from the server and defaults to true for ops generated locally.
doc.on('after op batch'), function() {...})
An operation batch was applied to the data.
doc.on('del', function(data, source) {...})
The document was deleted. Document contents before deletion are passed in as an argument. source will be false for ops received from the server and defaults to true for ops generated locally.
doc.on('error', function(err) {...})
There was an error fetching the document or applying an operation.
doc.removeListener(eventName, listener)
Removes any listener you added with doc.on. eventName should be one of 'load', 'create', 'before op', 'op', 'del', or 'error'. listener should be the function you passed in as the second argument to on. Note that both on and removeListener are inherited from EventEmitter.
doc.create(data[, type][, options][, function(err) {...}])
Create the document locally and send create operation to the server.
data Initial document contentstype (OT type)
Defaults to 'ot-json0', for which data is an Objectoptions.source Argument passed to the 'create' event locally. This is not sent to the server or other clients. Defaults to true.doc.submitOp(op, [, options][, function(err) {...}])
Apply operation to document and send it to the server.
op structure depends on the document type. See the
operations for the default 'ot-json0' type.
Call this after you've either fetched or subscribed to the document.
options.source Argument passed to the 'op' event locally. This is not sent to the server or other clients. Defaults to true.doc.del([options][, function(err) {...}])
Delete the document locally and send delete operation to the server.
Call this after you've either fetched or subscribed to the document.
options.source Argument passed to the 'del' event locally. This is not sent to the server or other clients. Defaults to true.doc.whenNothingPending(function(err) {...})
Invokes the given callback function after
doc.submitOp have been sent to the server, andNote that whenNothingPending does NOT wait for pending model.query() calls.
ShareDB.Queryquery.ready (Boolean)
True if query results are ready and available on query.results
query.results (Array)
Query results, as an array of ShareDB.Doc instances.
query.extra (Type depends on database adapter and query)
Extra query results that aren't an array of documents. Available for certain database adapters and queries.
query.on('ready', function() {...}))
The initial query results were loaded from the server. Fires at the same time as
the callbacks to createFetchQuery and createSubscribeQuery.
query.on('error', function(err) {...}))
There was an error receiving updates to a subscription.
query.destroy()
Unsubscribe and stop firing events.
query.on('changed', function(results) {...}))
(Only fires on subscription queries) The query results changed. Fires only once
after a sequence of diffs are handled.
query.on('insert', function(docs, atIndex) {...}))
(Only fires on subscription queries) A contiguous sequence of documents were added to the query result array.
query.on('move', function(docs, from, to) {...}))
(Only fires on subscription queries) A contiguous sequence of documents moved position in the query result array.
query.on('remove', function(docs, atIndex) {...}))
(Only fires on subscription queries) A contiguous sequence of documents were removed from the query result array.
query.on('extra', function() {...}))
(Only fires on subscription queries) query.extra changed.
By default, ShareDB logs to console. This can be overridden if you wish to silence logs, or to log to your own logging driver or alert service.
Methods can be overridden by passing a console-like object to logger.setMethods
var ShareDB = require('sharedb/lib/client');
ShareDB.logger.setMethods({
info: () => {}, // Silence info
warn: () => alerts.warn(arguments), // Forward warnings to alerting service
error: () => alerts.critical(arguments) // Remap errors to critical alerts
});
ShareDB only supports the following logger methods:
infowarnerrorShareDB returns errors as plain JavaScript objects with the format:
{
code: 5000,
message: 'ShareDB internal error'
}
Additional fields may be added to the error object for debugging context depending on the error. Common additional fields include collection, id, and op.
The 41xx and 51xx codes are reserved for use by ShareDB DB adapters, and the 42xx and 52xx codes are reserved for use by ShareDB PubSub adapters.
FAQs
JSON OT database backend
The npm package @evercoder/sharedb receives a total of 1 weekly downloads. As such, @evercoder/sharedb popularity was classified as not popular.
We found that @evercoder/sharedb demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.