sharedb-mongo 1.0.0-beta.8 → 2.0.0

package/.eslintrc.js

@@ -0,0 +1,49 @@
+// 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}],
+  // ES3 doesn't support spread
+  'prefer-spread': 'off',
+  // 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
+  ),
+};

package/.github/workflows/test.yml

@@ -0,0 +1,58 @@
+name: Test
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+
+jobs:
+  test:
+    name: Node.js ${{ matrix.node }} + mongoDB ${{ matrix.mongodb }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node:
+        - 14
+        - 16
+        - 18
+        mongodb:
+        - 4.0
+        - 4.2
+        - 4.4
+        - 5.0
+    services:
+      mongodb:
+        image: mongo:${{ matrix.mongodb }}
+        ports:
+        - 27017:27017
+    timeout-minutes: 10
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node }}
+    - name: Install
+      run: npm install
+    - name: Lint
+      run: npm run lint
+    - name: Test
+      run: npm run test-cover
+    - name: Coveralls
+      uses: coverallsapp/github-action@master
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        flag-name: node-${{ matrix.node }}-mongodb-${{ matrix.mongodb }}
+        parallel: true
+
+  finish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Submit coverage
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          parallel-finished: true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2015 Joseph Gentle and Nate Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,13 @@
 # sharedb-mongo
 
-  [![NPM Version](https://img.shields.io/npm/v/sharedb-mongo.svg)](https://npmjs.org/package/sharedb-mongo)
-  [![Build Status](https://travis-ci.org/share/sharedb-mongo.svg?branch=master)](https://travis-ci.org/share/sharedb-mongo)
-  [![Coverage Status](https://coveralls.io/repos/github/share/sharedb-mongo/badge.svg?branch=master)](https://coveralls.io/github/share/sharedb-mongo?branch=master)
+[![NPM Version](https://img.shields.io/npm/v/sharedb-mongo.svg)](https://npmjs.org/package/sharedb-mongo)
+[![Test](https://github.com/share/sharedb-mongo/workflows/Test/badge.svg)](https://github.com/share/sharedb-mongo/actions/workflows/test.yml)
+[![Coverage Status](https://coveralls.io/repos/github/share/sharedb-mongo/badge.svg?branch=master)](https://coveralls.io/github/share/sharedb-mongo?branch=master)
 
 MongoDB database adapter for [sharedb](https://github.com/share/sharedb). This
 driver can be used both as a snapshot store and oplog.
 
-Snapshots are stored where you'd expect (the named collection with _id=id). In
+Snapshots are stored where you'd expect (the named collection with \_id=id). In
 addition, operations are stored in `o_COLLECTION`. For example, if you have
 a `users` collection, the operations are stored in `o_users`.
 
@@ -17,38 +17,36 @@ the form of `_v` and `_type`). It is safe to query documents directly with the
 MongoDB driver or command line. Any read only mongo features, including find,
 aggregate, and map reduce are safe to perform concurrent with ShareDB.
 
-However, you must *always* use ShareDB to edit documents. Never use the
+However, you must _always_ use ShareDB to edit documents. Never use the
 MongoDB driver or command line to directly modify any documents that ShareDB
 might create or edit. ShareDB must be used to properly persist operations
 together with snapshots.
 
-
 ## Usage
 
-`sharedb-mongo` wraps native [mongodb](https://github.com/mongodb/node-mongodb-native), and it supports the same configuration options.
+`sharedb-mongo` uses the [MongoDB NodeJS Driver](https://github.com/mongodb/node-mongodb-native), and it supports the same configuration options.
 
 There are two ways to instantiate a sharedb-mongo wrapper:
 
-1. The simplest way is to invoke the module and pass in your mongo DB
-arguments as arguments to the module function. For example:
-
-```javascript
-const db = require('sharedb-mongo')('mongodb://localhost:27017/test');
-const backend = new ShareDB({db});
-```
+1.  The simplest way is to invoke the module and pass in your mongo DB
+    arguments as arguments to the module function. For example:
 
-2. If you'd like to reuse a mongo db connection or handle mongo driver
-instantiation yourself, you can pass in a function that calls back with
-a mongo instance.
+        ```javascript
+        const db = require('sharedb-mongo')('mongodb://localhost:27017/test', {mongoOptions: {...}});
+        const backend = new ShareDB({db});
+        ```
 
-```javascript
-const mongodb = require('mongodb');
-const db = require('sharedb-mongo')({mongo: function(callback) {
-  mongodb.connect('mongodb://localhost:27017/test', callback);
-}});
-const backend = new ShareDB({db});
-```
+2.  If you'd like to reuse a mongo db connection or handle mongo driver
+    instantiation yourself, you can pass in a function that calls back with
+    a mongo instance.
 
+        ```javascript
+        const mongodb = require('mongodb');
+        const db = require('sharedb-mongo')({mongo: function(callback) {
+          mongodb.connect('mongodb://localhost:27017/test', callback);
+        }});
+        const backend = new ShareDB({db});
+        ```
 
 ## Queries
 
@@ -172,7 +170,7 @@ failed ops:
 - v4: collision 4
 - v5: unique
 - v6: unique
-...
+  ...
 - v1000: unique
 
 If I want to fetch ops v1-v3, then we:
@@ -190,6 +188,39 @@ In the case where a valid op cannot be determined, we still
 fall back to fetching all ops and working backwards from the
 current version.
 
+### Middlewares
+
+Middlewares let you hook into the `sharedb-mongo` pipeline for certain actions. They are distinct from [middleware in `ShareDB`](https://github.com/share/sharedb) as they are closer to the concrete calls that are made to `MongoDB` itself.
+
+The original intent for middleware on `sharedb-mongo` is to support running in a sharded `MongoDB` cluster to satisfy the requirements on shard keys for versions 4.2 and greater of `MongoDB`. For more information see [the MongoDB docs](https://docs.mongodb.com/manual/core/sharding-shard-key/#shard-keys).
+
+#### Usage
+
+`share.use(action, fn)`
+Register a new middleware.
+
+- `action` _(String)_
+  One of:
+  - `'beforeCreate'`: directly before the call to write a new document
+  - `'beforeOverwrite'`: directly before the call to replace a document, can include edits as well as deletions
+  - `'beforeSnapshotLookup'`: directly before the call to issue a query for one or more snapshots by ID
+- `fn` _(Function(context, callback))_
+  Call this function at the time specified by `action`
+  - `context` will always have the following properties:
+    - `action`: The action this middleware is handling
+    - `collectionName`: The collection name being handled
+    - `options`: Original options as they were passed into the relevant function that triggered the action
+    - `'beforeCreate'` actions have additional context properties:
+      - `documentToWrite` - The document to be written
+      - `op` - The op that represents the changes that will be made to the document
+    - `'beforeOverwrite'` actions have additional context properties:
+      - `documentToWrite` - The document to be written
+      - `op` - The op that represents the changes that will be made to the document
+      - `query` - A filter that will be used to lookup the document that is about to be edited, which should always include an ID and snapshot version e.g. `{_id: 'uuid', _v: 1}`
+    - `'beforeSnapshotLookup'` actions have additional context properties:
+      - `query` - A filter that will be used to lookup the snapshot. When a single snapshot is looked up the query will take the shape `{_id: docId}` while a bulk lookup by a list of IDs will resemble `{_id: {$in: docIdsArray}}`.
+      - `findOptions` - Middleware can define and populate this object on the context to pass options to the MongoDB driver when doing the lookup.
+
 ### Limitations
 
 #### Integrity
@@ -226,42 +257,20 @@ Mongo errors are passed back directly. Additional error codes:
 
 #### 4100 -- Bad request - DB
 
-* 4101 -- Invalid op version
-* 4102 -- Invalid collection name
-* 4103 -- $where queries disabled
-* 4104 -- $mapReduce queries disabled
-* 4105 -- $aggregate queries disabled
-* 4106 -- $query property deprecated in queries
-* 4107 -- Malformed query operator
-* 4108 -- Only one collection operation allowed
-* 4109 -- Only one cursor operation allowed
-* 4110 -- Cursor methods can't run after collection method
+- 4101 -- Invalid op version
+- 4102 -- Invalid collection name
+- 4103 -- $where queries disabled
+- 4104 -- $mapReduce queries disabled
+- 4105 -- $aggregate queries disabled
+- 4106 -- $query property deprecated in queries
+- 4107 -- Malformed query operator
+- 4108 -- Only one collection operation allowed
+- 4109 -- Only one cursor operation allowed
+- 4110 -- Cursor methods can't run after collection method
 
 #### 5100 -- Internal error - DB
 
-* 5101 -- Already closed
-* 5102 -- Snapshot missing last operation field
-* 5103 -- Missing ops from requested version
-* 5104 -- Failed to parse query
-
-
-## MIT License
-Copyright (c) 2015 by Joseph Gentle and Nate Smith
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+- 5101 -- Already closed
+- 5102 -- Snapshot missing last operation field
+- 5103 -- Missing ops from requested version
+- 5104 -- Failed to parse query