josephg / ShareJS

> **NOTE**: ShareJS is now ShareDB. See here and here for more information. > . > . > . ShareJS ======= This is a little server & client library to allow concurrent editing of any kind of content via OT. The server runs on NodeJS and the client works in NodeJS or a web browser. ShareJS currently supports operational transform on plain-text and arbitrary JSON data. **Visit Google groups for discussions and announcements** **Immerse yourself in API Documentation.** Browser support --------------- ShareJS **should** work with all browsers, down to IE5.5 (although IE support hasn't been tested with the new version). That said, I only test regularly with FF, Safari and Chrome, and occasionally with IE8+. **File bug reports if you have issues** Installing and running ---------------------- # npm install share Run the example server with: # coffee node_modules/share/examples/server.coffee > Not all of the sharejs 0.6 examples have been ported across yet. I'd love > some pull requests! ShareJS depends on LiveDB for its database backend & data model. Read the livedb readme for information on how to configure your database. Run the tests: # npm install # mocha Server API To get started with the server API, you need to do 2 things: • Decide where your data is going to be stored. You can mess around using the livedb inmemory store. For more options, see the livedb api. • Decide how your client and server will communicate. The easiest solution is to use browserchannel. To create a ShareJS server instance: The method is called because its sort of a client of the database... its a weird name, just roll with it. The sharejs server instance has 3 methods you might care about: • To communicate with a client, create a node stream which can communicate with a client and use **share.listen(stream)** to hand control of the stream to sharejs. See the section below on client server communication for an example of this. • **share.rest()** returns a connect/express router which exposes the sharejs REST API. This code is in the process of moving to its own repo. In the meantime, the documentation is here • You can intercept requests to the livedb backend to do access control using sharejs middleware. **share.use(method, function(action, callback){...})** will make your function intercept & potentially rewrite requests. This is not currently documented, but when it is, the documentation will live here. Client server communication ShareJS requires *you* to provide a way for the client to communicate with the server. As such, its transport agnostic. You can use browserchannel, websockets, or whatever you like. ShareJS requires the transport to: • Guarantee in-order message delivery. (**Danger danger socket.io does not guarantee this**) • Provide a websocket-like API on the client • Provide a node object stream to the server to talk to a client. When a client times out, the server will throw away all information related to that client. When the client client reconnects, it will reestablish all its state on the server again. It is the responsibility of the transport to handle reconnection - the client should emit state change events to tell sharejs that it has reconnected. Server communication The server exposes a method which you can call with a node stream which can communicate with the client. Here's an example using browserchannel: And here is a more complete example using websockets. Client communication The client needs a websocket-like session object to communicate. You can use a normal websocket if you want: Sharejs also supports the following changes from the spec: • The socket can reconnect. Simply call again when the socket reconnects and sharejs will reestablish its session state and send any outstanding user data. • If your underlying API allows data to be sent while in the CONNECTING state, set . • If your API allows JSON messages, set to avoid extra JSON stringifying. If you use browserchannel, all of this is done for you. Simply tell browserchannel to reconnect and it'll take care of everything: --- Client API The client API can be used either from nodejs or from a browser. From the server: From the browser, you'll need to first include the sharejs library. You can use browserify and require('share').client or include the script directly. The browser library is built to the directory when you install sharejs. This path is exposed programatically at . You can add this to your express app: Then in your web app include whichever OT types you need in your app and sharejs: This will create a global object in the browser. Connections The client exposes 2 classes you care about: • The **Connection** class wraps a socket and handles the communication to the sharejs server. You use the connection instance to create document references in the client. • All actual data you edit will be wrapped by the **Doc** class. The document class stores an in-memory copy of the document data with your local edits applied. Create a document instance by calling . > ShareJS also allows you to make queries to your database. Live-bound queries will return a **Query** object. These are not currently documented. To get started, you first need to create a connection: The socket must be a websocket-like object. See the section on client server communication for details about how to create a socket. The most important method of the connection object is .get: **connection.get(collection, docname)**: Get a document reference to the named document on the server. This function returns the same document reference each time you call connection.get(). *collection* and *docname* are both strings. Connections also expose methods for executing queries: • **createFetchQuery(index, query, options, callback)**: Executes a query against the backend and returns a set of documents matching the query via the callback. • **createSubscribeQuery(index, query, options, callback)**: Run a query against…