mongodb-extended
v2.0.0
Published
Extends the node.js MongoDB driver providing useful tools for keeping database and collection settings in sync.
Downloads
31
Readme
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>
- .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.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.