ShareDB MongoDB Adapter

Common errors

• Query hangs when using $map operator.

  cause A bug in the `$map` query transform implementation.
  fix Upgrade to `sharedb-mongo@4.1.1` or later, which includes a fix for this issue. Avoid using `$map` in earlier versions.

• Memory leak detected when performing cursor operations like `$count`.

  cause A memory leak issue affecting `mongodb@4-6` when using cursor operations such as `$count` or `$explain`.
  fix Upgrade to `sharedb-mongo@4.1.1` or later, which resolved this memory leak.

• TypeError: ShareDbMongo is not a constructor

  cause Attempting to use `require('sharedb-mongo')` directly as a class constructor in CommonJS, or incorrect ESM import.
  fix If using CommonJS, `require('sharedb-mongo')` returns a function; call it with `const db = require('sharedb-mongo')(url);`. If using ESM, ensure `import ShareDbMongo from 'sharedb-mongo';` and then `new ShareDbMongo(url);`.

Warnings

• breaking Node.js v16 support was dropped with the release of v5.0.0. Projects using Node.js v16 or earlier must upgrade their Node.js environment to a supported version (Node.js v18 or later is recommended).
  Fix: Upgrade your Node.js runtime to version 18 or higher.
• breaking Node.js v14 support was dropped with the release of v4.0.0. Users on Node.js v14 need to upgrade their runtime.
  Fix: Upgrade your Node.js runtime to version 16 or higher for sharedb-mongo v4.x, or 18+ for v5.x.
• breaking Support for `mongodb@2` was dropped in v3.0.0. Users connecting to older MongoDB server versions or using older `mongodb` driver versions must upgrade their MongoDB setup.
  Fix: Ensure your `mongodb` package is version 3.x or higher, and your MongoDB server is compatible.
• gotcha Direct modification of ShareDB documents using the native MongoDB driver or command line is strictly prohibited. This can lead to data inconsistencies and corruption as ShareDB's operational transformation mechanism will be bypassed.
  Fix: Always use the ShareDB API to make changes to documents managed by ShareDB. Only read-only operations are safe outside of ShareDB's control.
• gotcha The default `src`/`seq`/`v` index is created automatically. If you're using `sharedb@5.0.1` or later which aims to avoid this index, you can disable its creation via `disableIndexCreation` option in `sharedb-mongo` v4.2.0+. Existing, undesired indexes must be manually deleted from MongoDB.
  Fix: To disable: `new ShareDbMongo(mongoUrl, { disableIndexCreation: { src_seq_v: true } });`. Manually delete existing indexes if no longer needed.

Install

• npm install sharedb-mongo npm
• yarn add sharedb-mongo yarn
• pnpm add sharedb-mongo pnpm

Imports

• ShareDbMongo
  wrong:

  const ShareDbMongo = require('sharedb-mongo');

  correct:

  import ShareDbMongo from 'sharedb-mongo';

  While `require` syntax is common in older examples, modern Node.js environments and TypeScript projects should use ESM `import`. The default export is a function that can be called directly or passed options.
• ShareDbMongo

  const db = require('sharedb-mongo')('mongodb://localhost:27017/test');

  CommonJS usage pattern where the module itself is a function that returns a configured database instance.
• { mongoOptions: {...} } (configuration)
  wrong:

  new ShareDbMongo('mongodb://localhost:27017/test', { /* top-level mongo options */ });

  correct:

  import ShareDbMongo from 'sharedb-mongo'; new ShareDbMongo('mongodb://localhost:27017/test', { mongoOptions: { /* ... */ } });

  Configuration options for the underlying MongoDB driver should typically be nested under `mongoOptions` when passed directly to the `ShareDbMongo` constructor or function call.

Quickstart

Initializes a ShareDB backend with sharedb-mongo as the database adapter and sets up a basic WebSocket server for client connections.

import ShareDB from 'sharedb';
import ShareDbMongo from 'sharedb-mongo';
import { WebSocketServer } from 'ws';
import http from 'http';

const mongoUrl = 'mongodb://localhost:27017/test';
const db = new ShareDbMongo(mongoUrl);
const backend = new ShareDB({ db });

// Create a WebSocket server to listen for client connections
const server = http.createServer();
const wss = new WebSocketServer({ server });

wss.on('connection', (ws) => {
  // Connect client to ShareDB backend
  const stream = backend.connect(ws);
  // Handle stream errors
  stream.on('error', (err) => console.error('ShareDB stream error:', err));
});

server.listen(8080, () => {
  console.log('ShareDB server listening on http://localhost:8080');
  console.log(`Connected to MongoDB at ${mongoUrl}`);
});

// Example document creation (optional, for testing)
const connection = backend.connect();
const doc = connection.get('examples', 'myDocument');
doc.fetch((err) => {
  if (err) throw err;
  if (doc.type === null) {
    doc.create({ content: 'Hello, ShareDB!' }, 'json0', (err) => {
      if (err) console.error('Error creating document:', err);
      else console.log('Document created!');
    });
  }
});