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 1.x: Supports mongodb driver version 3.x
• Version 2.x: Supports mongodb driver version 4.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:connect.Db | Active MongoDB database object. | | colNames | Array.<string> | Array of collection names to ensure do not exist. |

connect.ensureCollection ⇒ Promise

Ensure collection is in sync.

Kind: static property of connect
Returns: Promise - Resolves the collection object.
Throws:

• Error For invalid arguments or invalid options.

| Param | Type | Description | | --- | --- | --- | | db | connect | Active MongoDB database object. | | colName | string | The name of the collection. | | [options] | CollectionOptions | Collection options. |

ensureCollection.CollectionOptions : object

MongoDB Collection options.

Kind: static typedef of ensureCollection
Properties

| Name | Type | Description | | --- | --- | --- | | [validator] | object | Custom validaor. |

connect.ensureIndexes ⇒ Promise

Ensure indexes exist and are in sync.

Kind: static property of connect
Returns: Promise - Resolves an object containing the results of the operation.

| Param | Type | Description | | --- | --- | --- | | collection | module:connect.Collection | The collection object to ensure indexes on. | | indexes | object.<IndexSpec> | The indexes to ensure. |

• .ensureIndexes ⇒ Promise
  • .IndexKeySpec : string | number
  • .IndexSpec : object

ensureIndexes.IndexKeySpec : string | number

Index key specification.

Kind: static typedef of ensureIndexes

ensureIndexes.IndexSpec : object

Index specification.

Kind: static typedef of ensureIndexes
Properties

| Name | Type | Description | | --- | --- | --- | | keys | object.<IndexKeySpec> | Index key specifications. | | [options] | object | MongoDB index options. Refer to the documentation for full details of available options. |

connect.initializeAll ⇒ Promise

Connect and initialize (sync database and collection settings).

Kind: static property of connect
Returns: Promise - Resolves and array of the operation results.

| Param | Type | Description | | --- | --- | --- | | db | module:connect.Db | MongoDB database object. | | conf | object | Full database and collection configuration. |

connect.initializeCollection ⇒ Promise

Initialize a collection while keeping configured indexes and options in sync.

Kind: static property of connect
Returns: Promise - Resolves the collection object.

| Param | Type | Description | | --- | --- | --- | | db | module:connect.Db | An active database object. | | colName | string | The name of the collection to initialize. | | colConf | CollectionSpec | Collection configuration specification. |

initializeCollection.CollectionSpec : object

Collection specifiction.

Kind: static typedef of initializeCollection
Properties

| Name | Type | Description | | --- | --- | --- | | [options] | CollectionOptions | Collection options. | | data | Array.<object> | Optionally initialize with preset data. | | [indexes] | Array.<IndexSpec> | object.<IndexSpec> | Initialize the collection with configured indexes and keep the database indexes in sync. | | dropIndexes | Array.<string> | List of indexes that will be dropped if they exist. |

connect.initializeCollections ⇒ Promise.<InitializeCollectionsResult>

Initialize multiple collections.

Kind: static property of connect
Returns: Promise.<InitializeCollectionsResult> - Resolves an object keyed with collection names containing their corresponding (extended) MongoDB collection.

| Param | Type | Description | | --- | --- | --- | | db | module:connect.Db | An active database object. | | collectionsConf | object.<CollectionSpec> | The collections configuration object. | | [options] | InitializeCollectionsOptions | Execution options. |

• .initializeCollections ⇒ Promise.<InitializeCollectionsResult>
  • .InitializeCollectionsType : object.<CollectionSpec> | Array.<CollectionSpec>
  • .InitializeCollectionsOptions : object
  • .InitializeCollectionsResult : object.<initializeCollections>

initializeCollections.InitializeCollectionsType : object.<CollectionSpec> | Array.<CollectionSpec>

Parameter structure for initializeCollections.

Either an array of collection specifications with a "name" field added to the spec, or an object keyed by the collectionNames.

Kind: static typedef of initializeCollections

initializeCollections.InitializeCollectionsOptions : object

Operation run-time options for initializeCollections().

Kind: static typedef of initializeCollections
Properties

| Name | Type | Default | Description | | --- | --- | --- | --- | | [concurrency] | number | 0 | Limit the number of collections that are processed in parallel. |

initializeCollections.InitializeCollectionsResult : object.<initializeCollections>

Result structure for initializeCollections().

The resulting object is derrived from the collection specifications provided. Each collection with be keyed by name with the corresponding Collection object.

Kind: static typedef of initializeCollections

connect.initializeServer ⇒ Promise

Initialize server parameters.

Kind: static property of connect
Returns: Promise - Resolves the command result.

| Param | Type | Description | | --- | --- | --- | | db | module:connect.Db | The MongoDB database object. | | serverParams | object | Server parameters object. |

connect.Configuration : object

Complete configuration for connecting and initializing with mongodb-extended.

Kind: static typedef of connect
Properties

| Name | Type | Description | | --- | --- | --- | | name | string | The name of the database. | | [url] | string | The MongoDB URL. | | [options] | object | MongoDB connection options. | | [collections] | object.<CollectionSpec> | The collection specifications for the application. | | [dropCollections] | Array.<string> | List of collections that will be dropped if they exist. | | [serverParameters] | object | Optionally set server parameters on initialization. |

Support

Feel free to report a bug or open a feature request on Github.

Testing

npm i && npm test

Developed by Chris Lee. Sponsored by CodeCatalysts.

API reference generated with jsdoc2md.