{"id":16684,"library":"sharedb-milestone-mongo","title":"ShareDB Milestone MongoDB Adapter","description":"sharedb-milestone-mongo is a database adapter for ShareDB that specifically targets MongoDB, enabling the use of 'milestone snapshots' to optimize the `connection.fetchSnapshot` method. These snapshots create specific points in time from which a smaller number of operations can be applied to reconstruct the requested document version, significantly improving performance for frequently accessed older versions. The current stable version is 2.1.0, and the package demonstrates a consistent release cadence, frequently updating to support newer versions of both Node.js (dropping older LTS versions) and its core dependencies, `mongodb` and `sharedb`. It stores these milestones in a dedicated `m_COLLECTION` in the MongoDB database, configurable for saving intervals or complex middleware-based logic.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"git://github.com/share/sharedb-milestone-mongo","tags":["javascript"],"install":[{"cmd":"npm install sharedb-milestone-mongo","lang":"bash","label":"npm"},{"cmd":"yarn add sharedb-milestone-mongo","lang":"bash","label":"yarn"},{"cmd":"pnpm add sharedb-milestone-mongo","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core operational transformation library that this package extends and integrates with.","package":"sharedb","optional":false},{"reason":"The underlying MongoDB driver used for all database interactions.","package":"mongodb","optional":false}],"imports":[{"note":"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.","wrong":"import { MongoMilestoneDB } from 'sharedb-milestone-mongo';","symbol":"MongoMilestoneDB","correct":"import MongoMilestoneDB from 'sharedb-milestone-mongo';\n// or for CJS:\nconst MongoMilestoneDB = require('sharedb-milestone-mongo');"},{"note":"While not part of sharedb-milestone-mongo, ShareDB is always used in conjunction with this adapter and is typically imported as a default export.","symbol":"ShareDB","correct":"import ShareDB from 'sharedb';\n// or for CJS:\nconst ShareDB = require('sharedb');"},{"note":"When providing a custom MongoClient instance, it's crucial to correctly import named exports from the `mongodb` package.","wrong":"import mongodb from 'mongodb';\nconst MongoClient = mongodb.MongoClient;","symbol":"MongoClient","correct":"import { MongoClient } from 'mongodb';"}],"quickstart":{"code":"import ShareDB from 'sharedb';\nimport MongoMilestoneDB from 'sharedb-milestone-mongo';\n\nconst mongoUrl = process.env.MONGO_URL ?? 'mongodb://localhost:27017/test';\n\nasync function startServer() {\n  try {\n    const milestoneDb = new MongoMilestoneDB(mongoUrl);\n    const shareDb = new ShareDB({ milestoneDb: milestoneDb });\n\n    // Example of using ShareDB with the milestone adapter\n    const connection = shareDb.connect();\n    const doc = connection.get('mycollection', 'mydocument');\n\n    await new Promise((resolve, reject) => {\n      doc.fetch(err => {\n        if (err) return reject(err);\n        if (doc.type === null) {\n          doc.create({ content: 'Hello initial world!' }, resolve);\n        } else {\n          resolve();\n        }\n      });\n    });\n\n    console.log('ShareDB with milestone-mongo initialized and document fetched/created.');\n\n    // Cleanup (in a real app, this would be part of graceful shutdown)\n    // await milestoneDb.close(); // Note: MongoMilestoneDB doesn't expose a direct close method, it relies on underlying MongoClient close.\n    // shareDb.close();\n\n  } catch (error) {\n    console.error('Failed to start ShareDB server:', error);\n    process.exit(1);\n  }\n}\n\nstartServer();","lang":"typescript","description":"Initializes ShareDB with sharedb-milestone-mongo, connecting to a MongoDB instance. It demonstrates basic document fetching/creation using the configured milestone database."},"warnings":[{"fix":"Upgrade Node.js to v18 or a later supported version. Older Node.js versions require sharedb-milestone-mongo v1.x.","message":"Node.js v16 support was dropped in v2.0.0. Ensure your environment uses Node.js v18 or newer.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Node.js v14 support was dropped in v1.0.0. This aligns with Node.js LTS lifecycle.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Review error handling logic and update to check for string error codes instead of direct object comparisons or older error patterns.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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`).","message":"Support for `mongodb@2` was explicitly dropped in v0.10.0. This means older MongoDB server versions or driver clients are no longer compatible.","severity":"breaking","affected_versions":">=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Plan index creation carefully, especially on production systems with substantial data. Consider creating indexes during maintenance windows or on smaller, new collections.","message":"Enabling indexing on existing, large milestone collections can have a significant adverse impact on performance during the index creation process.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For CommonJS: `const MongoMilestoneDB = require('sharedb-milestone-mongo');`. For ES Modules: `import MongoMilestoneDB from 'sharedb-milestone-mongo';`.","cause":"Attempting to use `new MongoMilestoneDB()` with an incorrect import statement, likely trying to destructure a default export.","error":"TypeError: MongoMilestoneDB is not a constructor"},{"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`).","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.","error":"Error: Mongo driver version 'X' is not supported. Please use a supported version."},{"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+).","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.","error":"Error: Node.js version X is not supported by sharedb-milestone-mongo Y. Please upgrade Node.js."},{"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.","cause":"The MongoDB server is not running or is inaccessible at the specified connection string.","error":"MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017"}],"ecosystem":"npm"}