2.0.0 • Published 2 years ago

mongodb-extended v2.0.0

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
2 years ago

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.

ParamTypeDefaultDescription
dbConfConfigurationFull configuration. See the type definition for details.
optionsobjectRun-time options.
options.initializebooleanfalseWhether to initialize the db and collections.
options.concurrencynumberOverride 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.

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

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

ParamTypeDescription
dbmodule:connect.DbActive MongoDB database object.
colNamesArray.<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.
ParamTypeDescription
dbconnectActive MongoDB database object.
colNamestringThe name of the collection.
optionsCollectionOptionsCollection options.

ensureCollection.CollectionOptions : object

MongoDB Collection options.

Kind: static typedef of ensureCollection
Properties

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

ParamTypeDescription
collectionmodule:connect.CollectionThe collection object to ensure indexes on.
indexesobject.<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

NameTypeDescription
keysobject.<IndexKeySpec>Index key specifications.
optionsobjectMongoDB 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.

ParamTypeDescription
dbmodule:connect.DbMongoDB database object.
confobjectFull 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.

ParamTypeDescription
dbmodule:connect.DbAn active database object.
colNamestringThe name of the collection to initialize.
colConfCollectionSpecCollection configuration specification.

initializeCollection.CollectionSpec : object

Collection specifiction.

Kind: static typedef of initializeCollection
Properties

NameTypeDescription
optionsCollectionOptionsCollection options.
dataArray.<object>Optionally initialize with preset data.
indexesArray.<IndexSpec> | object.<IndexSpec>Initialize the collection with configured indexes and keep the database indexes in sync.
dropIndexesArray.<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.

ParamTypeDescription
dbmodule:connect.DbAn active database object.
collectionsConfobject.<CollectionSpec>The collections configuration object.
optionsInitializeCollectionsOptionsExecution 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

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

ParamTypeDescription
dbmodule:connect.DbThe MongoDB database object.
serverParamsobjectServer parameters object.

connect.Configuration : object

Complete configuration for connecting and initializing with mongodb-extended.

Kind: static typedef of connect
Properties

NameTypeDescription
namestringThe name of the database.
urlstringThe MongoDB URL.
optionsobjectMongoDB connection options.
collectionsobject.<CollectionSpec>The collection specifications for the application.
dropCollectionsArray.<string>List of collections that will be dropped if they exist.
serverParametersobjectOptionally 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.

1.3.0

2 years ago

2.0.0

2 years ago

1.2.1

2 years ago

1.2.0

3 years ago

1.1.2

3 years ago

1.1.1

3 years ago

1.1.0

3 years ago

1.0.4

3 years ago

1.0.3

3 years ago

1.0.2

3 years ago

1.0.1

3 years ago

1.0.0

3 years ago