mongodb-extended

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.