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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ShareDbMongo
✓ import ShareDbMongo from 'livedb-mongo'; // For ESM
// Or for CommonJS:
const ShareDbMongo = require('livedb-mongo');
✗ import { ShareDbMongo } from 'livedb-mongo';
The primary export is a default function/class, often aliased as `ShareDbMongo` or `livedbmongo`. CommonJS `require` is still widely used in existing `livedb`/`sharedb` applications.
SharedbMongoOptions
✓ import type { SharedbMongoOptions } from 'livedb-mongo';
✗ import { SharedbMongoOptions } from 'livedb-mongo';
This type definition is for configuring the adapter instance, including options like `disableIndexCreation`.
Db
✓ import { Db } from 'mongodb'; // When passing an existing MongoDB Db instance
While `livedb-mongo` can take a connection string, it can also accept an already initialized `mongodb` `Db` instance for more control.
Initializes `livedb-mongo` as an adapter for `livedb`, then fetches or creates a document and applies an update operation.
const ShareDbMongo = require('livedb-mongo'); // Or import ShareDbMongo from 'livedb-mongo'; for ESM
const livedb = require('livedb'); // This adapter is for livedb (and sharedb)
// MongoDB connection string. Ensure MongoDB is running locally.
// Replace with your actual MongoDB connection string in production.
const mongoUrl = process.env.MONGO_URL || 'mongodb://localhost:27017/livedb_test_db';
// Initialize the livedb-mongo adapter (also known as sharedb-mongo)
// The second argument is for MongoDB driver options.
const mongoAdapter = new ShareDbMongo(mongoUrl, {
// Modern driver options, crucial for recent MongoDB versions
useUnifiedTopology: true,
// replicaSet can be important for change streams if using sharedb's oplog features
// replicaSet: 'rs0'
});
// Initialize livedb client with the mongo adapter
const db = livedb.client(mongoAdapter);
const collection = 'documents';
const docId = 'exampleDoc';
console.log(`Attempting to connect to MongoDB at ${mongoUrl} via livedb-mongo...`);
// Try to fetch a document. If it doesn't exist, create it.
db.fetch(collection, docId, (err, snapshot) => {
if (err) {
console.error('Error fetching document:', err);
mongoAdapter.close(); // Ensure connection is closed on error
return;
}
if (snapshot.v === 0) { // Document does not exist (version is 0)
console.log(`Document '${docId}' not found. Creating it...`);
const initialData = { title: 'Hello World', content: 'This is the initial version.', counter: 0 };
db.create(collection, docId, 'json0', initialData, (createErr) => {
if (createErr) {
console.error('Error creating document:', createErr);
} else {
console.log(`Document '${docId}' created successfully with data:`, initialData);
}
mongoAdapter.close(); // Close connection after operation
});
} else {
console.log(`Document '${docId}' found (v${snapshot.v}):`, snapshot.data);
// Example: Apply an operation to update the document (e.g., increment counter)
const op = { p: ['counter'], na: 1 }; // Operational Transform: Increment 'counter' by 1
db.apply(collection, docId, op, { source: 'example_script', version: snapshot.v + 1 }, (applyErr) => {
if (applyErr) {
console.error('Error applying operation:', applyErr);
} else {
console.log('Operation applied successfully: counter incremented.');
// Fetch again to see the updated state
db.fetch(collection, docId, (fetchUpdatedErr, updatedSnapshot) => {
if (fetchUpdatedErr) console.error('Error fetching updated document:', fetchUpdatedErr);
else console.log('Updated document data:', updatedSnapshot.data);
mongoAdapter.close();
});
}
});
}
});
Errors
Common errors & fixes
MongoServerSelectionError: connect ECONNREFUSED
The MongoDB server is not running or is not accessible at the specified connection URL.
fixEnsure your MongoDB instance is running and accessible from your application's environment. Verify the connection string and firewall rules.
Error: Document already exists. Cannot create.
Attempted to `db.create` a document with an `_id` that already exists in the collection.
fixBefore creating, use `db.fetch` to check if the document exists (`snapshot.v === 0`). If it does, use `db.apply` to update it, or choose a unique `_id`.
Error applying operation: Invalid op
The operational transform (OT) operation applied via `db.apply` is malformed or incompatible with the document's current type/data.
fixReview the structure of your OT operation. Ensure it correctly targets document paths and uses valid transformations for the document type (e.g., 'json0' for JSON documents).
Application hangs when using $map query transform
A bug in older versions of the adapter (prior to v4.1.1) caused `$map` queries to hang indefinitely.
fixUpgrade `livedb-mongo` to version 4.1.1 or newer. This issue was fixed in PR #154.
Audit
Dependencies
sharedbrequiredThis package is an adapter for sharedb (and historically livedb). sharedb is a peer dependency.
mongodbrequiredThe underlying MongoDB driver used for database interaction. It is a peer dependency.