ShareDB Milestone MongoDB Adapter

Common errors

• TypeError: MongoMilestoneDB is not a constructor

  cause Attempting to use `new MongoMilestoneDB()` with an incorrect import statement, likely trying to destructure a default export.
  fix For CommonJS: `const MongoMilestoneDB = require('sharedb-milestone-mongo');`. For ES Modules: `import MongoMilestoneDB from 'sharedb-milestone-mongo';`.

• Error: Mongo driver version 'X' is not supported. Please use a supported version.

  cause Mismatched `mongodb` package version with the `sharedb-milestone-mongo` version. The library has frequent updates to support new `mongodb` versions and drops support for older ones.
  fix Check the `sharedb-milestone-mongo` release notes (e.g., on GitHub or npm) for the specific version you are using and update your `mongodb` dependency to a compatible version (e.g., v2.1.0 supports `mongodb@7`).

• Error: Node.js version X is not supported by sharedb-milestone-mongo Y. Please upgrade Node.js.

  cause Running `sharedb-milestone-mongo` on an unsupported Node.js version. Newer versions of the library frequently drop support for older Node.js LTS releases.
  fix Upgrade your Node.js environment to the minimum required version for your `sharedb-milestone-mongo` version (e.g., v2.0.0 requires Node.js v18+).

• MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

  cause The MongoDB server is not running or is inaccessible at the specified connection string.
  fix Ensure your MongoDB server is running and accessible from the application's host, and verify the connection string (host, port, database name) is correct.

Warnings

• breaking Node.js v16 support was dropped in v2.0.0. Ensure your environment uses Node.js v18 or newer.
  Fix: Upgrade Node.js to v18 or a later supported version. Older Node.js versions require sharedb-milestone-mongo v1.x.
• breaking Node.js v14 support was dropped in v1.0.0. This aligns with Node.js LTS lifecycle.
  Fix: Upgrade Node.js to v16 or newer for versions >=1.0.0. For v1.0.0 specifically, v16+ is required; for v2.0.0+, v18+ is needed.
• breaking Error handling was refactored in v1.0.0 to use string error codes and a dedicated error module. Direct comparison of error objects or properties might break.
  Fix: Review error handling logic and update to check for string error codes instead of direct object comparisons or older error patterns.
• breaking Support for `mongodb@2` was explicitly dropped in v0.10.0. This means older MongoDB server versions or driver clients are no longer compatible.
  Fix: Ensure your `mongodb` package dependency is v3.x or higher. For full compatibility, refer to recent release notes for the specific `mongodb` version supported (e.g., v2.1.0 supports `mongodb@7`).
• gotcha When configuring complex milestone saving logic via ShareDB middleware, explicitly set `request.saveMilestoneSnapshot = false` to disable milestones for certain collections. Leaving it `null` will revert to the default interval logic.
  Fix: Always set `request.saveMilestoneSnapshot` to `false` if you intend to prevent milestone snapshots for a given request/collection, rather than leaving it undefined or null.
• gotcha Enabling indexing on existing, large milestone collections can have a significant adverse impact on performance during the index creation process.
  Fix: Plan index creation carefully, especially on production systems with substantial data. Consider creating indexes during maintenance windows or on smaller, new collections.

Install

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

Imports

• MongoMilestoneDB
  wrong:

  import { MongoMilestoneDB } from 'sharedb-milestone-mongo';

  correct:

  import MongoMilestoneDB from 'sharedb-milestone-mongo';
  // or for CJS:
  const MongoMilestoneDB = require('sharedb-milestone-mongo');

  The primary class is a default export, though the `require` syntax might imply a named export if one is not careful. Ensure correct default import for ESM.
• ShareDB

  import ShareDB from 'sharedb';
  // or for CJS:
  const ShareDB = require('sharedb');

  While not part of sharedb-milestone-mongo, ShareDB is always used in conjunction with this adapter and is typically imported as a default export.
• MongoClient
  wrong:

  import mongodb from 'mongodb';
  const MongoClient = mongodb.MongoClient;

  correct:

  import { MongoClient } from 'mongodb';

  When providing a custom MongoClient instance, it's crucial to correctly import named exports from the `mongodb` package.

Quickstart

Initializes ShareDB with sharedb-milestone-mongo, connecting to a MongoDB instance. It demonstrates basic document fetching/creation using the configured milestone database.

import ShareDB from 'sharedb';
import MongoMilestoneDB from 'sharedb-milestone-mongo';

const mongoUrl = process.env.MONGO_URL ?? 'mongodb://localhost:27017/test';

async function startServer() {
  try {
    const milestoneDb = new MongoMilestoneDB(mongoUrl);
    const shareDb = new ShareDB({ milestoneDb: milestoneDb });

    // Example of using ShareDB with the milestone adapter
    const connection = shareDb.connect();
    const doc = connection.get('mycollection', 'mydocument');

    await new Promise((resolve, reject) => {
      doc.fetch(err => {
        if (err) return reject(err);
        if (doc.type === null) {
          doc.create({ content: 'Hello initial world!' }, resolve);
        } else {
          resolve();
        }
      });
    });

    console.log('ShareDB with milestone-mongo initialized and document fetched/created.');

    // Cleanup (in a real app, this would be part of graceful shutdown)
    // await milestoneDb.close(); // Note: MongoMilestoneDB doesn't expose a direct close method, it relies on underlying MongoClient close.
    // shareDb.close();

  } catch (error) {
    console.error('Failed to start ShareDB server:', error);
    process.exit(1);
  }
}

startServer();