MongoDB Persistence Provider for Yjs

Warnings

• gotcha This `y-mongodb-provider` package is not officially supported or maintained by the core Yjs team. While functional, users should be aware of its community-driven support model.
  Fix: Review the GitHub repository for active development, open issues, and pull requests to gauge maintenance status and potential issues. Consider contributing to its development if you find gaps.
• breaking Node.js version 16 or newer is required to use this package. Using older Node.js versions will result in runtime errors due to reliance on modern JavaScript features and ESM module format.
  Fix: Upgrade your Node.js environment to version 16 or later (e.g., `nvm install 16 && nvm use 16`).
• breaking Version 0.1.8 replaced the internal 'mongoist' library with the official 'mongodb' Node.js Driver. While the public API signature for `MongodbPersistence` generally remained, internal behaviors, error handling, or specific connection options might have changed. This change was also made for security enhancements.
  Fix: Review the official MongoDB Node.js driver documentation for any specific connection string options or client configurations, especially if encountering unexpected behavior when migrating from versions prior to 0.1.8.
• gotcha For optimal performance and robust connection pooling, especially when sharing a `MongoClient` instance across your application, it is recommended to pass an object `{ client: MongoClient, db: Db }` to the `MongodbPersistence` constructor instead of just a connection string. This avoids creating redundant MongoDB client instances.
  Fix: Manually instantiate `MongoClient`, connect it, and pass the `{ client, db: client.db('yourDatabaseName') }` object to the `MongodbPersistence` constructor.
• gotcha If the `multipleCollections` option is set to `true` in the `MongodbPersistence` constructor, each Yjs document will be stored in its own dedicated MongoDB collection. In this scenario, the `collectionName` option will be ignored.
  Fix: Ensure that if you intend to store all documents within a single, named collection, `multipleCollections` must be set to `false` (which is its default value).
• breaking Version 0.2.0 introduced changes to the `MongodbPersistence` constructor's internal handling of the database name for user authentication. While passing a connection string is still supported, improper database naming could lead to authentication failures or incorrect access rights.
  Fix: Verify that the database name specified in your MongoDB connection string or through the `client.db('databaseName')` call accurately corresponds to the database against which your MongoDB user is authenticated and has the necessary permissions.

Install

• npm install y-mongodb-provider npm
• yarn add y-mongodb-provider yarn
• pnpm add y-mongodb-provider pnpm

Imports

• MongodbPersistence
  wrong:

  const { MongodbPersistence } = require('y-mongodb-provider')

  correct:

  import { MongodbPersistence } from 'y-mongodb-provider'

  This package is primarily ESM-first, requiring Node.js 16+. Named import is the standard way. Ships TypeScript types.
• MongodbPersistence constructor (connection string)

  new MongodbPersistence('mongodb://localhost:27017/yjstest')

  The constructor accepts a MongoDB connection string. Since v0.2.0+, ensure proper database name in the string for authentication purposes.
• MongodbPersistence constructor (client object)

  import { MongoClient } from 'mongodb'; const client = new MongoClient('mongodb://localhost:27017'); await client.connect(); const db = client.db('yourDatabaseName'); new MongodbPersistence({ client, db })

  Passing an object with `MongoClient` and `Db` instances is recommended for managing connection pools and resource sharing, especially when the same client is used elsewhere in your application.

Quickstart

This example sets up a Yjs WebSocket server using `y-websocket` and integrates `y-mongodb-provider` for persistent storage of Yjs document states in a MongoDB database. It demonstrates binding document state on connection and asynchronously storing updates as they occur.

import http from 'http';
import { WebSocketServer } from 'ws';
import * as Y from 'yjs';
import { MongodbPersistence } from 'y-mongodb-provider';
import yUtils from 'y-websocket/bin/utils'; // Note: y-websocket/bin/utils is an internal utility, adapt as needed.

const port = process.env.PORT || 1234;
const mongoConnectionString = process.env.MONGODB_URL || 'mongodb://localhost:27017/yjstest';

const server = http.createServer((request, response) => {
	response.writeHead(200, { 'Content-Type': 'text/plain' });
	response.end('okay');
});

// Initialize Yjs WebSocket server
const wss = new WebSocketServer({ server });
wss.on('connection', yUtils.setupWSConnection);

// Initialize MongoDB persistence for Yjs
const mdb = new MongodbPersistence(mongoConnectionString, {
	collectionName: 'transactions',
	flushSize: 100,
	multipleCollections: false, // Default; set to true if each document needs its own collection
});

// Set up persistence with y-websocket
yUtils.setPersistence({
	bindState: async (docName, ydoc) => {
		// Retrieve the persisted document state
		const persistedYdoc = await mdb.getYDoc(docName);
		
		// Apply the persisted state to the current ydoc
		Y.applyUpdate(ydoc, Y.encodeStateAsUpdate(persistedYdoc));

		// Store initial state and listen for future updates
		mdb.storeUpdate(docName, Y.encodeStateAsUpdate(ydoc));
		ydoc.on('update', async (update) => {
			mdb.storeUpdate(docName, update);
		});
	},
	writeState: async (docName, ydoc) => {
		// This function is called when all connections to a document are closed.
		// Ensure all pending updates are written to the database.
		// For y-mongodb-provider, `storeUpdate` handles this incrementally.
		// The promise resolution signals that the document can be destroyed.
		return new Promise(resolve => resolve());
	},
});

server.listen(port, () => {
	console.log(`Yjs WebSocket server with MongoDB persistence listening on port: ${port}`);
});