❤
npm
Sign UpSign In

mongodb-extended

2.0.0 • Public • Published

view on npm npm module downloads Build Status Coverage Status Maintainability

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.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.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.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.

Readme

Keywords

none

Package Sidebar

Install

npm i mongodb-extended

Repository

github.com/speedytwenty/mongodb-extended

Homepage

github.com/speedytwenty/mongodb-extended#readme

Weekly Downloads

22

Version

2.0.0

License

Apache-2.0

Unpacked Size

55.5 kB

Total Files

18

Last publish

Collaborators

  • speedytwenty
Try on RunKit
Report malware