MongoDB Extended (mongodb-extended)

Extends the Node.js driver adding a useful API for modeling MongoDB objects and keeping database structures in sync across environments.

Use case:

When using MongoDB without a tool like Mongoose, it can be burdensome and problematic to maintain indexes, schemas, etc. across environments.

This module provides a mechanism for configuring your MongoDB collections in code and keeping things in sync across multiple environments.

MongoDB driver version:

• Version 3.x: Supports mongodb driver version 4.x, 5.x & 6.x
• Version 2.x: Supports mongodb driver version 4.x
• Version 1.x: Supports mongodb driver version 3.x

Collection Configuration Management

With mongodb-extended, your application can configure each collection as necessary and mongodb-extended will keep the database in sync with your configuration.

This includes:

• Keeping indexes in sync between the database and configuration.
• Keeping collection options in sync between the database and configuration.
• Dropping legacy indexes as denoted in configuration.
• Pre-populating a collection with documents.

Installation

With NPM:

npm i mongodb-extended

With Yarn:

yarn add mongodb-extended

API Reference

connect ⇒ Promise

Connect to MongoDB and optionally initialize the database configuration and collections.

Returns: Promise - Resolves an objecting the MongoDB client, db, and collections.

| Param | Type | Default | Description | | --- | --- | --- | --- | | dbConf | Configuration | | Full configuration. See the type definition for details. | | [options] | object | | Run-time options. | | [options.initialize] | boolean | false | Whether to initialize the db and collections. | | [options.concurrency] | number | | Override the concurrency for all relevant operations. |

Example (Basic connection.)

const connect = require('mongodb-extended');

connect({
  collections: {
    myCollection: {
      indexes: {
        name: { keys: { name: 1 }, options: { unique: true } },
      },
      // MongoDB collection options. Providing a simple schema validator.
      options: {
        validator: {
          $jsonSchema: {
            required: ['name', 'value'],
            properties: {
              name: { type: 'string' },
              value: { type: 'string|number' },
            },
          },
        },
      },
      // Pre-populate our db with data
      data: [
        { name: 'foo', value: 'bar' },
        { name: 'abc', value: 123 },
      ],
      // Ensure old indexes that are no longer used are removed
      dropIndexes: [
        'legacyIndex1',
        'legacyIndex2',
      ],
    },
    myView: {
      options: {
        viewOn: 'myCollection',
        pipeline: [
          { $group: { _id: '$value', names: { $addToSet: '$name' } } },
          { $sort: { _id: -1 } },
        ],
      },
    },
  },
  // Ensure old collections that are no longer used are removed.
  dropCollections: [
    'legacyCollection1',
    'legacyCollection2',
  ],
  // Syncronize the database server parameters with the parameters specified
  // here. WARNING: These settings affect the entire database server.
  serverParameters: {
    notablescan: true,
  },
  // This initialize flag triggers the initialization operations. When true
  // server parameters and collection settings are synchonized with the
  // database.
}, { initialize: true }).then(({ client, collections }) => {
  collections.foo.findOne({ name: 'bar' })
    .then((document) => {
      console.log(document);
      client.close();
    })
    .catch((e) => {
      client.close();
      console.error(e);
    });
});

• connect ⇒ Promise
  • .connect ⇒ Promise
  • .connectAndInitialize ⇒ Promise
  • .dropCollections ⇒ Promise
  • .ensureCollection ⇒ Promise
    • .CollectionOptions : object
  • .ensureIndexes ⇒ Promise
    • .IndexKeySpec : string | number
    • .IndexSpec : object
  • .initializeAll ⇒ Promise
  • .initializeCollection ⇒ Promise
    • .CollectionSpec : object
  • .initializeCollections ⇒ Promise.<InitializeCollectionsResult>
    • .InitializeCollectionsType : Object.<CollectionSpec> | Array.<CollectionSpec>
    • .InitializeCollectionsOptions : object
    • .InitializeCollectionsResult : Object.<initializeCollections>
  • .initializeServer ⇒ Promise
  • .Configuration : object

connect.connect ⇒ Promise

Connect to mongodb with extended configuration options.

Kind: static property of connect
Returns: Promise - Resolves an object containing the client, db, and collections.

| Param | Type | Description | | --- | --- | --- | | conf | object | Extended database configuration. |

connect.connectAndInitialize ⇒ Promise

Connect and initialize (sync database and collection settings).

Kind: static property of connect
Returns: Promise - Resolves an object containing the MongoDB client, db, and an object with each configured collection.

| Param | Type | Description | | --- | --- | --- | | conf | Configuration | Full database and collection configuration. |

connect.dropCollections ⇒ Promise

Ensure collections do not exist. If a provided collection exists, it will be dropped.

Kind: static property of connect
Returns: Promise - Resolves an array of collection names that existed and were dropped.

| Param | Type | Description | | --- | --- | --- | | db | module:c