sharedb-mongo

library5.1.0jsnpmunverified

sharedb-mongo is a database adapter for ShareDB, a full-stack library for realtime JSON document collaboration. It serves as both a snapshot store and an oplog for ShareDB documents, integrating directly with MongoDB. Currently at v5.1.0, the package sees active development with regular updates to support the latest Node.js and MongoDB versions. A key differentiator is its ability to unwrap JSON document snapshots, allowing direct MongoDB queries against these documents (for read-only operations), while strictly requiring ShareDB for any modifications to ensure proper operational transformation and persistence. It also extends MongoDB's querying capabilities within the ShareDB context through special `$`-prefixed operators for methods like `mapReduce` and `sort`.

database serialization

npm install sharedb-mongo

github ↗package ↗

INSTALL

IMPORT

SIG · SHAREDB-MONGO

sharedb-mongo

databasejavascriptv5.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ShareDbMongo

✓ import ShareDbMongo from 'sharedb-mongo';

✗ const ShareDbMongo = require('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)

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

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

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

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!'); }); } });

Debug

Known issues

breakingNode.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.

affects: >=5.0.0

breakingNode.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.

affects: >=4.0.0 <5.0.0

breakingSupport 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.

affects: >=3.0.0

gotchaDirect 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=4.2.0

Errors

Common errors & fixes

Query hangs when using $map operator.

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`.

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

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);`.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

sharedbrequiredCore ShareDB library that this package integrates with as a database backend.

mongodbrequiredThe underlying MongoDB NodeJS driver used for database interactions. Compatible with mongodb@7 since v5.1.0.

Agent activity

22 hits · last 30 days

node