Presence 2

.eslintrc.js

@@ -0,0 +1,47 @@
+// The ESLint ecmaVersion argument is inconsistently used. Some rules will ignore it entirely, so if the rule has
+// been set, it will still error even if it's not applicable to that version number. Since Google sets these
+// rules, we have to turn them off ourselves.
+const DISABLED_ES6_OPTIONS = {
+  'no-var': 'off',
+  'prefer-rest-params': 'off'
+};
+
+const SHAREDB_RULES = {
+  // Comma dangle is not supported in ES3
+  'comma-dangle': ['error', 'never'],
+  // We control our own objects and prototypes, so no need for this check
+  'guard-for-in': 'off',
+  // Google prescribes different indents for different cases. Let's just use 2 spaces everywhere. Note that we have
+  // to override ESLint's default of 0 indents for this.
+  'indent': ['error', 2, {
+    'SwitchCase': 1
+  }],
+  // Less aggressive line length than Google, which is especially useful when we have a lot of callbacks in our code
+  'max-len': ['error',
+    {
+      code: 120,
+      tabWidth: 2,
+      ignoreUrls: true,
+    }
+  ],
+  // Google overrides the default ESLint behaviour here, which is slightly better for catching erroneously unused variables
+  'no-unused-vars': ['error', {vars: 'all', args: 'after-used'}],
+  // It's more readable to ensure we only have one statement per line
+  'max-statements-per-line': ['error', {max: 1}],
+  // as-needed quote props are easier to write
+  'quote-props': ['error', 'as-needed'],
+  'require-jsdoc': 'off',
+  'valid-jsdoc': 'off'
+};
+
+module.exports = {
+  extends: 'google',
+  parserOptions: {
+    ecmaVersion: 3
+  },
+  rules: Object.assign(
+    {},
+    DISABLED_ES6_OPTIONS,
+    SHAREDB_RULES
+  ),
+};

.gitignore

@@ -34,4 +34,5 @@ coverage
 # Dependency directories
 node_modules
 package-lock.json
+yarn.lock
 jspm_packages

.travis.yml

@@ -3,6 +3,6 @@ node_js:
   - "10"
   - "8"
   - "6"
-script: "npm run jshint && npm run test-cover"
+script: "npm run lint && npm run test-cover"
 # Send coverage data to Coveralls
 after_script: "cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js"

README.md

@@ -19,6 +19,7 @@ tracker](https://github.com/share/sharedb/issues).
 
 - Realtime synchronization of any JSON document
 - Concurrent multi-user collaboration
+- Realtime synchronization of any ephemeral "presence" data
 - Synchronous editing API with asynchronous eventual consistency
 - Realtime query subscriptions
 - Simple integration with any database - [MongoDB](https://github.com/share/sharedb-mongo), [PostgresQL](https://github.com/share/sharedb-postgres) (experimental)
@@ -73,6 +74,22 @@ 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.
 
+## User Presence Synchronization
+
+ShareDB supports synchronization of user presence data such as cursor positions and text selections. This feature is opt-in, not enabled by default. To enable this feature, pass a presence implementation as the `presence` option to the ShareDB constructor.
+
+ShareDB includes an implementation of presence called `StatelessPresence`. This provides an implementation of presence that works out of the box, but it has some scalability problems. Each time a client joins a document, this implementation requests current presence information from all other clients, via the server. This approach may be problematic in terms of performance when a large number of users are present on the same document simultaneously. If you don't expect too many simultaneous users per document, `StatelessPresence` should work well. The server does not store any state at all regarding presence (it exists only in clients), hence the name "Stateless Presence".
+
+In `StatelessPresence`, presence data represents a user and is automatically synchronized between all clients subscribed to the same document. Its format is defined by the document's [OT Type](https://github.com/ottypes/docs) (specifically, by [`transformPresence`, `createPresence`, and `comparePresence`](https://github.com/teamwork/ot-docs#optional-properties)). All clients can modify their own presence data and receive a read-only version of other client's data. Presence data is automatically cleared when a client unsubscribes from the document or disconnects. It is also automatically transformed against applied operations, so that it still makes sense in the context of a modified document, for example a cursor position may be automatically advanced when a user types at the beginning of a text document.
+
+To use `StatelessPresence`, pass it into the ShareDB constructor like this:
+
+```js
+var ShareDB = require('sharedb');
+var statelessPresence = require('sharedb/lib/presence/stateless');
+var share = new ShareDB({ presence: statelessPresence })`).
+```
+
 ## Server API
 
 ### Initialization
@@ -91,6 +108,8 @@ __Options__
 * `options.pubsub` _(instance of `ShareDB.PubSub`)_
   Notify other ShareDB processes when data changes
   through this pub/sub adapter. Defaults to `ShareDB.MemoryPubSub()`.
+* `options.presence` _(implementation of presence classes)_
+  Enable user presence synchronization. The value of `options.presence` option is expected to contain implementations of the classes `DocPresence`, `ConnectionPresence`, `AgentPresence`, and `BackendPresence`. Logic related to presence is encapsulated within these classes, so it is possible develop additional third party presence implementations external to ShareDB.
 
 #### Database Adapters
 * `ShareDB.MemoryDB`, backed by a non-persistent database with no queries
@@ -308,6 +327,9 @@ Unique document ID
 `doc.data` _(Object)_
 Document contents. Available after document is fetched or subscribed to.
 
+`doc.presence` _(Object)_
+Each property under `doc.presence` contains presence data shared by a client subscribed to this document. The property name is an empty string for this client's data and connection IDs for other clients' data. The structure of the presence object is defined by the OT type of the document (for example, in [ot-rich-text](https://github.com/Teamwork/ot-rich-text#presence) and [@datavis-tech/json0](https://github.com/datavis-tech/json0#presence)).
+
 `doc.fetch(function(err) {...})`
 Populate the fields on `doc` with a snapshot of the document from the server.
 
@@ -337,6 +359,9 @@ An operation was applied to the data. `source` will be `false` for ops received
 `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('presence', function(srcList, submitted) {...})`
+Presence data has changed. `srcList` is an Array of `doc.presence` property names for which values have changed. `submitted` is `true`, if the event is the result of new presence data being submitted by the local or remote user, otherwise it is `false` - eg if the presence data was transformed against an operation or was cleared on unsubscribe, disconnect or roll-back.
+
 `doc.on('error', function(err) {...})`
 There was an error fetching the document or applying an operation.
 
@@ -370,6 +395,11 @@ Invokes the given callback function after
 
 Note that `whenNothingPending` does NOT wait for pending `model.query()` calls.
 
+`doc.submitPresence(presenceData[, function(err) {...}])`
+Set local presence data and publish it for other clients.
+`presenceData` structure depends on the document type.
+Presence is synchronized only when subscribed to the document.
+
 ### Class: `ShareDB.Query`
 
 `query.ready` _(Boolean)_
@@ -467,6 +497,10 @@ Additional fields may be added to the error object for debugging context dependi
 * 4022 - Database adapter does not support queries
 * 4023 - Cannot project snapshots of this type
 * 4024 - Invalid version
+* 4025 - Passing options to subscribe has not been implemented
+* 4026 - Not subscribed to document
+* 4027 - Presence data superseded
+* 4028 - OT Type does not support presence
 
 ### 5000 - Internal error
 

examples/counter/package.json

@@ -17,7 +17,7 @@
   "dependencies": {
     "express": "^4.14.0",
     "sharedb": "^1.0.0-beta",
-    "websocket-json-stream": "^0.0.1",
+    "@teamwork/websocket-json-stream": "^2.0.0",
     "ws": "^1.1.0"
   },
   "devDependencies": {

examples/counter/server.js

@@ -2,7 +2,7 @@ var http = require('http');
 var express = require('express');
 var ShareDB = require('sharedb');
 var WebSocket = require('ws');
-var WebSocketJSONStream = require('websocket-json-stream');
+var WebSocketJSONStream = require('@teamwork/websocket-json-stream');
 
 var backend = new ShareDB();
 createDoc(startServer);
@@ -29,7 +29,7 @@ function startServer() {
 
   // Connect any incoming WebSocket connection to ShareDB
   var wss = new WebSocket.Server({server: server});
-  wss.on('connection', function(ws, req) {
+  wss.on('connection', function(ws) {
     var stream = new WebSocketJSONStream(ws);
     backend.listen(stream);
   });

examples/leaderboard/README.md

@@ -2,7 +2,7 @@
 
 ![Demo](demo.gif)
 
-This is a port of [https://github.com/percolatestudio/react-leaderboard](Leaderboard) to
+This is a port of [Leaderboard](https://github.com/percolatestudio/react-leaderboard) to
 ShareDB.
 
 In this demo, data is not persisted. To persist data, run a Mongo

examples/leaderboard/package.json

@@ -24,7 +24,7 @@
     "sharedb-mingo-memory": "^1.0.0-beta",
     "through2": "^2.0.1",
     "underscore": "^1.8.3",
-    "websocket-json-stream": "^0.0.3",
+    "@teamwork/websocket-json-stream": "^2.0.0",
     "ws": "^1.1.0"
   },
   "devDependencies": {

examples/leaderboard/server/index.js

@@ -1,37 +1,38 @@
-var http = require("http");
-var ShareDB = require("sharedb");
-var connect = require("connect");
+var http = require('http');
+var ShareDB = require('sharedb');
+var connect = require('connect');
 var serveStatic = require('serve-static');
 var ShareDBMingoMemory = require('sharedb-mingo-memory');
-var WebSocketJSONStream = require('websocket-json-stream');
+var WebSocketJSONStream = require('@teamwork/websocket-json-stream');
 var WebSocket = require('ws');
-var util = require('util');
 
 // Start ShareDB
-var share = ShareDB({db: new ShareDBMingoMemory()});
+var share = new ShareDB({db: new ShareDBMingoMemory()});
 
 // Create a WebSocket server
 var app = connect();
 app.use(serveStatic('.'));
 var server = http.createServer(app);
 var wss = new WebSocket.Server({server: server});
 server.listen(8080);
-console.log("Listening on http://localhost:8080");
+console.log('Listening on http://localhost:8080');
 
 // Connect any incoming WebSocket connection with ShareDB
-wss.on('connection', function(ws, req) {
+wss.on('connection', function(ws) {
   var stream = new WebSocketJSONStream(ws);
   share.listen(stream);
 });
 
 // Create initial documents
 var connection = share.connect();
 connection.createFetchQuery('players', {}, {}, function(err, results) {
-  if (err) { throw err; }
+  if (err) {
+    throw err;
+  }
 
   if (results.length === 0) {
-    var names = ["Ada Lovelace", "Grace Hopper", "Marie Curie",
-                 "Carl Friedrich Gauss", "Nikola Tesla", "Claude Shannon"];
+    var names = ['Ada Lovelace', 'Grace Hopper', 'Marie Curie',
+      'Carl Friedrich Gauss', 'Nikola Tesla', 'Claude Shannon'];
 
     names.forEach(function(name, index) {
       var doc = connection.get('players', ''+index);

examples/rich-text/package.json

@@ -18,7 +18,7 @@
     "quill": "^1.0.0-beta.11",
     "rich-text": "^3.0.1",
     "sharedb": "^1.0.0-beta",
-    "websocket-json-stream": "^0.0.1",
+    "@teamwork/websocket-json-stream": "^2.0.0",
     "ws": "^1.1.0"
   },
   "devDependencies": {

examples/rich-text/server.js

@@ -3,7 +3,7 @@ var express = require('express');
 var ShareDB = require('sharedb');
 var richText = require('rich-text');
 var WebSocket = require('ws');
-var WebSocketJSONStream = require('websocket-json-stream');
+var WebSocketJSONStream = require('@teamwork/websocket-json-stream');
 
 ShareDB.types.register(richText.type);
 var backend = new ShareDB();
@@ -32,7 +32,7 @@ function startServer() {
 
   // Connect any incoming WebSocket connection to ShareDB
   var wss = new WebSocket.Server({server: server});
-  wss.on('connection', function(ws, req) {
+  wss.on('connection', function(ws) {
     var stream = new WebSocketJSONStream(ws);
     backend.listen(stream);
   });

examples/textarea/client.js

@@ -2,35 +2,35 @@ var sharedb = require('sharedb/lib/client');
 var StringBinding = require('sharedb-string-binding');
 
 // Open WebSocket connection to ShareDB server
-const WebSocket = require('reconnecting-websocket');
+var WebSocket = require('reconnecting-websocket');
 var socket = new WebSocket('ws://' + window.location.host);
 var connection = new sharedb.Connection(socket);
 
 var element = document.querySelector('textarea');
 var statusSpan = document.getElementById('status-span');
-status.innerHTML = "Not Connected"
+statusSpan.innerHTML = 'Not Connected';
 
-element.style.backgroundColor = "gray";
-socket.onopen = function(){
-  status.innerHTML = "Connected"
-  element.style.backgroundColor = "white";
+element.style.backgroundColor = 'gray';
+socket.onopen = function() {
+  statusSpan.innerHTML = 'Connected';
+  element.style.backgroundColor = 'white';
 };
 
-socket.onclose = function(){
-  status.innerHTML = "Closed"
-  element.style.backgroundColor = "gray";
+socket.onclose = function() {
+  statusSpan.innerHTML = 'Closed';
+  element.style.backgroundColor = 'gray';
 };
 
 socket.onerror = function() {
-  status.innerHTML = "Error"
-  element.style.backgroundColor = "red";
-}
+  statusSpan.innerHTML = 'Error';
+  element.style.backgroundColor = 'red';
+};
 
 // Create local Doc instance mapped to 'examples' collection document with id 'textarea'
 var doc = connection.get('examples', 'textarea');
 doc.subscribe(function(err) {
   if (err) throw err;
-  
+
   var binding = new StringBinding(element, doc, ['content']);
   binding.setup();
 });

examples/textarea/server.js

@@ -14,7 +14,7 @@ function createDoc(callback) {
   doc.fetch(function(err) {
     if (err) throw err;
     if (doc.type === null) {
-      doc.create({ content: '' }, callback);
+      doc.create({content: ''}, callback);
       return;
     }
     callback();
@@ -29,7 +29,7 @@ function startServer() {
 
   // Connect any incoming WebSocket connection to ShareDB
   var wss = new WebSocket.Server({server: server});
-  wss.on('connection', function(ws, req) {
+  wss.on('connection', function(ws) {
     var stream = new WebSocketJSONStream(ws);
     backend.listen(stream);
   });