Updated email agent fork

.eslintrc.js

@@ -49,5 +49,17 @@ module.exports = {
   ),
   ignorePatterns: [
     '/docs/'
+  ],
+  overrides: [
+    {
+      files: ['examples/counter-json1-vite/*.js'],
+      parserOptions: {
+        ecmaVersion: 6,
+        sourceType: 'module'
+      },
+      rules: {
+        quotes: ['error', 'single']
+      }
+    }
   ]
 };

.github/workflows/docs.yml

@@ -18,10 +18,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-ruby@v1
+    - uses: actions/checkout@v3
+    - uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 2.7
+        ruby-version: '2.7'
     - name: Install
       run: cd docs && gem install bundler && bundle install
     - name: Build

.github/workflows/test.yml

@@ -15,18 +15,18 @@ jobs:
     strategy:
       matrix:
         node:
-        - 12
-        - 14
         - 16
+        - 18
+        - 20
     services:
       mongodb:
         image: mongo:4.4
         ports:
         - 27017:27017
     timeout-minutes: 10
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-node@v1
+    - uses: actions/checkout@v3
+    - uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node }}
     - name: Install

.gitignore

@@ -38,3 +38,4 @@ jspm_packages
 
 # Don't commit generated JS bundles
 examples/**/static/dist/bundle.js
+examples/**/dist

docs/Gemfile.lock

@@ -14,7 +14,7 @@ GEM
       execjs
     coffee-script-source (1.11.1)
     colorator (1.1.0)
-    commonmarker (0.23.4)
+    commonmarker (0.23.6)
     concurrent-ruby (1.1.9)
     dnsruby (1.61.9)
       simpleidn (~> 0.1)
@@ -232,7 +232,7 @@ GEM
       jekyll-seo-tag (~> 2.1)
     minitest (5.15.0)
     multipart-post (2.1.1)
-    nokogiri (1.13.3)
+    nokogiri (1.13.9)
       mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     octokit (4.22.0)
@@ -265,7 +265,7 @@ GEM
     thread_safe (0.3.6)
     typhoeus (1.4.0)
       ethon (>= 0.9.0)
-    tzinfo (1.2.9)
+    tzinfo (1.2.10)
       thread_safe (~> 0.1)
     tzinfo-data (1.2021.1)
       tzinfo (>= 1.0.0)

docs/api/backend.md

@@ -388,10 +388,6 @@ backend.getOpsBulk(agent, index, fromMap, toMap [, options [, callback]])
 
 > The name of the collection or [projection]({{ site.baseurl }}{% link projections.md %})
 
-`id` -- string
-
-> The document ID
-
 `fromMap` -- Object
 
 > An object whose keys are the IDs of the target documents. The values are the first versions requested of each document (inclusive)

docs/api/connection.md

@@ -68,9 +68,9 @@ Optional
 
 > Default: `{}`
 
-> `options.results` -- Object[]
+> `options.results` -- [`Doc`]({{ site.baseurl }}{% link api/doc.md %})[]
 
-> > Prior query results, if available, such as from server rendering
+> > Prior query results, if available, such as from server rendering. This should be an array of Doc instances, as obtained from  `connection.get(collection, id)`. If the docs' data is already available, invoke [`ingestSnapshot`]({{ site.baseurl }}{% link api/doc.md %}#ingestsnapshot) for each Doc instance beforehand to avoid re-transferring the data from the server.
 
 > `options.*` -- any
 
@@ -105,9 +105,9 @@ Optional
 
 > Default: `{}`
 
-> `options.results` -- Object[]
+> `options.results` -- [`Doc`]({{ site.baseurl }}{% link api/doc.md %})[]
 
-> > Prior query results, if available, such as from server rendering
+> > Prior query results, if available, such as from server rendering. This should be an array of Doc instances, as obtained from `connection.get(collection, id)`. If the docs' data is already available, invoke [`ingestSnapshot`]({{ site.baseurl }}{% link api/doc.md %}#ingestsnapshot) for each Doc instance beforehand to avoid re-transferring the data from the server.
 
 > `options.*` -- any
 
@@ -228,4 +228,19 @@ The document **must** be of a [type]({{ site.baseurl }}{% link types/index.md %}
 
 Return value
 
-> A [`Presence`]({{ site.baseurl }}{% link api/presence.md %}) instance tied to the given document
+> A [`Presence`]({{ site.baseurl }}{% link api/presence.md %}) instance tied to the given document
+
+### ping()
+
+Send a short message to the server, which will respond with another short message, emitted on the connection as a
+`'pong'` event.
+
+```js
+connection.ping()
+connection.on('pong', () => {
+  // The server is still there
+})
+```
+
+{: .warn }
+Calling `ping()` when not connected will throw an error with code `ERR_CANNOT_PING_OFFLINE`.

docs/api/presence.md

@@ -143,6 +143,9 @@ presence.on('receive', function(id, value) { ... });
 
 > The presence value. The structure of this object will depend on the [type]({{ site.baseurl }}{% link types/index.md %})
 
+{: .info }
+> A `null` value means the remote client is no longer present in the document (e.g. they disconnected)
+
 ### `'error'`
 
 An error has occurred.

docs/getting-started.md

@@ -38,6 +38,7 @@ The ShareDB backend expects an instance of a [`Stream`](https://nodejs.org/api/s
 ```js
 var express = require('express')
 var WebSocket = require('ws')
+var http = require('http')
 var ShareDB = require('sharedb')
 var WebSocketJSONStream = require('@teamwork/websocket-json-stream')
 
@@ -70,7 +71,11 @@ Try running the [working example](https://github.com/share/sharedb/tree/master/e
 var ReconnectingWebSocket = require('reconnecting-websocket')
 var Connection = require('sharedb/lib/client').Connection
 
-var socket = new ReconnectingWebSocket('ws://localhost:8080')
+var socket = new ReconnectingWebSocket('ws://localhost:8080', [], {
+  // ShareDB handles dropped messages, and buffering them while the socket
+  // is closed has undefined behavior
+  maxEnqueuedMessages: 0
+})
 var connection = new Connection(socket)
 
 var doc = connection.get('doc-collection', 'doc-id')

docs/middleware/actions.md

@@ -149,9 +149,13 @@ This action has these additional `context` properties:
 
 > The query's projection [fields]({{ site.baseurl }}{% link api/backend.md %}#addprojection)
 
-`channel` -- string
+`channel` -- string (deprecated)
 
-> The [Pub/Sub]({{ site.baseurl }}{% link adapters/pub-sub.md %}) channel the query will subscribe to. Defaults to its collection channel.
+> This property is deprecated use `channels` instead. The [Pub/Sub]({{ site.baseurl }}{% link adapters/pub-sub.md %}) channels the query will subscribe to. Defaults to its collection channel.
+
+`channels` -- string[]
+
+> The [Pub/Sub]({{ site.baseurl }}{% link adapters/pub-sub.md %}) channels the query will subscribe to. Defaults to its collection channel.
 
 `query` -- Object
 

docs/middleware/op-submission.md

@@ -140,12 +140,20 @@ Since `'submitRequestEnd'` is an event -- not a middleware hook -- it provides n
 
 ## Mutating ops
 
-{: .warn :}
-Mutating ops in middleware is generally a **bad idea**, and should be avoided.
+Ops may be amended in the `apply` middleware using the special `request.$fixup()` method:
 
-The main reason for avoiding op mutation is that the client who submitted the op will not be informed of the mutation, so the client's doc will never receive the mutation.
+```js
+backend.use('apply', (request, next) => {
+  let error;
+  try {
+    request.$fixup([{p: ['meta'], oi: {timestamp: Date.now()}}]);
+  } catch (e) {
+    error = e;
+  }
 
-The general workaround is to trigger a second op submission, rather than mutate the provided op. This obviously has the downside of op submissions being unatomic, but is the safest way to get the original client to receive the update.
+  next(error);
+});
+```
 
 {: .warn :}
-When submitting ops from the middleware, set careful conditions under which you submit ops in order to avoid infinite op submission loops, where submitting an op recursively triggers infinite op submissions.
+The `request.$fixup()` method may throw an error, which should be handled appropriately, usually by passing directly to the `next()` callback.

docs/presence.md

@@ -22,6 +22,14 @@ In this case, clients just need to subscribe to a common channel using [`connect
 ```js
 const presence = connection.getPresence('my-channel')
 presence.subscribe()
+
+presence.on('receive', (presenceId, update) => {
+  if (update === null) {
+    // The remote client is no longer present in the document
+  } else {
+    // Handle the new value by updating UI, etc.
+  }
+})
 ```
 
 In order to send presence information to other clients, a [`LocalPresence`]({{ site.baseurl }}{% link api/local-presence.md %}) should be created. The presence object can take any arbitrary value
@@ -51,6 +59,14 @@ Clients subscribe to a particular [`Doc`]({{ site.baseurl }}{% link api/doc.md %
 ```js
 const presence = connection.getDocPresence(collection, id)
 presence.subscribe()
+
+presence.on('receive', (presenceId, update) => {
+  if (update === null) {
+    // The remote client is no longer present in the document
+  } else {
+    // Handle the new value by updating UI, etc.
+  }
+})
 ```
 
 The shape of the presence value will be defined by the [type]({{ site.baseurl }}{% link types/index.md %}):

docs/queries.md

@@ -32,7 +32,7 @@ See the [API documentation]({{ site.baseurl }}{% link api/connection.md %}#creat
 [`Query`]({{ site.baseurl }}{% link api/query.md %}) instance, which can be used instead:
 
 ```js
-const query = connection.createFetchQuery('my-connection', {userId: 1})
+const query = connection.createFetchQuery('my-collection', {userId: 1})
 query.on('ready', () => {
   // results are now available in query.results
 })
@@ -48,7 +48,7 @@ A subscribed query will automatically cause any matched `Doc` instances to recei
 Subscribe queries can be created similarly to fetch queries, but you may also be interested in [other events]({{ site.baseurl }}{% link api/query.md %}#events):
 
 ```js
-const query = connection.createSubscribeQuery('my-connection', {userId: 1})
+const query = connection.createSubscribeQuery('my-collection', {userId: 1})
 query.on('ready', () => {
   // The initial results are available in query.results
 })
@@ -73,7 +73,7 @@ If a query can potentially return a large number of results, you may want to con
 For example, a `sharedb-mongo` limit might look like this:
 
 ```js
-const query = connection.createSubscribeQuery('my-connection', {userId: 1, $skip: 10, $limit: 10})
+const query = connection.createSubscribeQuery('my-collection', {userId: 1, $skip: 10, $limit: 10})
 ```
 
 {: .info }
@@ -160,7 +160,7 @@ backend.use('commit', (context, next) => {
 
 backend.use('query', (context, next) => {
   // Set our query to only listen for changes on our user-specific channel
-  context.channel = userChannel(context)
+  context.channels = [userChannel(context)]
   next()
 })
 

examples/counter-json1-vite/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

examples/counter-json1-vite/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>ShareDB Counter (ottype json1 with Vite)</title>
+  </head>
+  <body>
+    <div style="font-family: Helvetica Neue, Helvetica, Arial, sans-serif; font-size: 36px;">
+      You clicked <span id="num-clicks"></span> times.
+      <button style="font-size: 36px;" class="increment">+1</button>
+    </div>
+    <script type="module" src="/main.js"></script>
+  </body>
+</html>

examples/counter-json1-vite/main.js

@@ -0,0 +1,37 @@
+import ReconnectingWebSocket from 'reconnecting-websocket';
+import {json1} from 'sharedb-client-browser/dist/ot-json1-umd.cjs';
+import sharedb from 'sharedb-client-browser/dist/sharedb-client-umd.cjs';
+
+// Open WebSocket connection to ShareDB server
+var socket = new ReconnectingWebSocket('ws://' + window.location.host + '/ws', [], {
+  // ShareDB handles dropped messages, and buffering them while the socket
+  // is closed has undefined behavior
+  maxEnqueuedMessages: 0
+});
+sharedb.types.register(json1.type);
+var connection = new sharedb.Connection(socket);
+
+// Create local Doc instance mapped to 'examples' collection document with id 'counter'
+var doc = connection.get('examples', 'counter');
+
+// Get initial value of document and subscribe to changes
+doc.subscribe(showNumbers);
+// When document changes (by this client or any other, or the server),
+// update the number on the page
+doc.on('op', showNumbers);
+
+function showNumbers() {
+  document.querySelector('#num-clicks').textContent = doc.data.numClicks;
+};
+
+// When clicking on the '+1' button, change the number in the local
+// document and sync the change to the server and other connected
+// clients
+function increment() {
+  // Increment `doc.data.numClicks`. See
+  // https://github.com/ottypes/json1/blob/master/spec.md for list of valid operations.
+  doc.submitOp(['numClicks', {ena: 1}]);
+}
+
+var button = document.querySelector('button.increment');
+button.addEventListener('click', increment);

examples/counter-json1-vite/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "counter-json1-vite",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "@teamwork/websocket-json-stream": "^2.0.0",
+    "express": "^4.18.2",
+    "ot-json1": "^1.0.2",
+    "reconnecting-websocket": "^4.4.0",
+    "sharedb": "^3.3.1",
+    "sharedb-client-browser": "^4.2.1",
+    "ws": "^8.13.0"
+  },
+  "devDependencies": {
+    "vite": "^4.2.1"
+  }
+}