ShareDB Mingo Memory Adapter

Common errors

• Error: $mapReduce is not supported

  cause The `sharedb-mingo-memory` adapter does not implement the `$mapReduce` MongoDB operator.
  fix Refactor your query to avoid `$mapReduce` or consider using a different ShareDB database adapter that supports it (e.g., `sharedb-mongo`).

• TypeError: ShareDBMingo is not a constructor

  cause This error often occurs when attempting to `new` an imported module incorrectly, especially if mixing ESM `import` with CommonJS `require()` patterns or when the module exports a default that isn't directly constructible.
  fix Ensure you are using the correct import syntax for your module system. For ESM, use `import ShareDBMingo from 'sharedb-mingo-memory';`. For CommonJS, use `const ShareDBMingo = require('sharedb-mingo-memory');`.

• RangeError: Invalid version: X.Y.Z (sharedb-mingo-memory)

  cause This usually indicates an incompatibility between the version of `sharedb-mingo-memory` and the version of `sharedb` being used in your project, or a Node.js version mismatch.
  fix Check the `peerDependencies` of `sharedb-mingo-memory` to ensure your `sharedb` version is compatible. Also, verify that your Node.js runtime meets the minimum version required by `sharedb-mingo-memory` (e.g., v4.x requires Node.js >=18).

Warnings

• breaking Node.js v16 is no longer supported. Applications running on Node.js v16 or older will need to upgrade their Node.js environment to at least v18 to use sharedb-mingo-memory v4.0.0 and above.
  Fix: Upgrade your Node.js runtime to version 18 or newer. For projects that cannot upgrade, sharedb-mingo-memory v3.x.x should be used.
• breaking Node.js v14 is no longer supported. Applications running on Node.js v14 will need to upgrade their Node.js environment to at least v16 to use sharedb-mingo-memory v3.0.0 and above.
  Fix: Upgrade your Node.js runtime to version 16 or newer. For projects that cannot upgrade, sharedb-mingo-memory v2.x.x should be used.
• breaking Node.js v12 is no longer supported. Applications running on Node.js v12 will need to upgrade their Node.js environment to at least v14 to use sharedb-mingo-memory v2.0.0 and above.
  Fix: Upgrade your Node.js runtime to version 14 or newer. For projects that cannot upgrade, sharedb-mingo-memory v1.x.x should be used.
• gotcha The `$aggregate` operator was not supported in earlier versions (pre-2.1.0) and would throw an error. Support for basic `$aggregate` was added in v2.1.0, and `$lookup` for `$aggregate` was added in v4.1.0.
  Fix: Upgrade to sharedb-mingo-memory v2.1.0 or higher for basic `$aggregate` support. For `$lookup` within `$aggregate`, upgrade to v4.1.0 or higher. Consult the mingo documentation for supported aggregation pipeline stages.
• gotcha The `process` global was previously a requirement, which could cause issues in certain non-Node.js environments. This requirement was dropped in v3.0.1.
  Fix: Upgrade to sharedb-mingo-memory v3.0.1 or higher to remove the dependency on the `process` global, improving compatibility with bundlers and alternative JavaScript runtimes.

Install

• npm install sharedb-mingo-memory npm
• yarn add sharedb-mingo-memory yarn
• pnpm add sharedb-mingo-memory pnpm

Imports

• ShareDBMingo
  wrong:

  const ShareDBMingo = require('sharedb-mingo-memory').default;

  correct:

  import ShareDBMingo from 'sharedb-mingo-memory';

  While CommonJS `require` is shown in older documentation, ESM `import` is the preferred and modern way. The module typically exports as a default.
• ShareDBMingo

  const ShareDBMingo = require('sharedb-mingo-memory');

  This is the classic CommonJS `require` syntax as demonstrated in the package's README, suitable for Node.js environments.
• extendMemoryDB
  wrong:

  const { extendMemoryDB } = require('sharedb-mingo-memory');

  correct:

  import ShareDBMingo from 'sharedb-mingo-memory';
  const CustomDB = ShareDBMingo.extendMemoryDB(SomeOtherMemoryDB);

  The `extendMemoryDB` method is a static property of the default export, not a named export itself. It's used for creating a new ShareDBMingo class that extends a specific `MemoryDB`.

Quickstart

This quickstart demonstrates how to initialize sharedb-mingo-memory, integrate it with ShareDB, create a document, and perform a basic query against the in-memory database.

import ShareDBMingo from 'sharedb-mingo-memory';
import ShareDB from 'sharedb';

// Initialize the in-memory database adapter
const db = new ShareDBMingo();

// Initialize ShareDB with the in-memory adapter
const backend = new ShareDB({ db });

// Example usage: Create a connection and a document
const connection = backend.connect();
const doc = connection.get('myCollection', 'myDocument');

doc.fetch((err) => {
  if (err) throw err;

  if (doc.type === null) {
    // Create the document if it doesn't exist
    doc.create({ title: 'Hello World', content: 'This is an in-memory document.' }, (err) => {
      if (err) throw err;
      console.log('Document created:', doc.data);
      queryDocuments();
    });
  } else {
    console.log('Document already exists:', doc.data);
    queryDocuments();
  }
});

function queryDocuments() {
  const query = connection.query('myCollection', { title: 'Hello World' });
  query.subscribe((err) => {
    if (err) throw err;
    console.log('Query results:', query.results.map(d => d.data));
    // Remember to unsubscribe or close connection in a real app
    query.destroy();
    connection.close();
  });
}