mongodb-igniter
A declarative MongoDB initializer
Description
The purpose of mongodb-igniter
is to provide an easy way to initialize your application's baseline MongoDB database content from a declarative object format using Node.js. It maximizes the use of Node.js's async capabilities to process the initialization very quickly, and returns all results in a neatly organized array of objects. Both the DB declaration and results object formats leverage the MongoDB native driver object types, for simplicity. It can initiate its own MongoDB connection, or use an existing one. The module source is written in TypeScript and exposes all relevant types for consumption by IDEs and/or the TypeScript language.
Features
- Create a MongoDB database connection or use an existing one
- Create collections with any MongoDB supported options
- Create/update indexes with any MongoDB supported options
- Create/replace documents with any MongoDB supported options (uses
replaceOne
)
Compatibility
The current version uses the Node.js MongoDB native driver version 2.2, and therefore supports up to MongoDB 3.4. An update to the version 3.0 driver and support for MongoDB 3.6 is forthcoming.
For more information on Node.js MongoDB native driver compatibility, see: https://docs.mongodb.com/ecosystem/drivers/driver-compatibility-reference/#node-js-driver-compatibility
Installation
These instructions assume you have already installed Node.js, which includes NPM.
To install the module, use the following command:
npm install mongodb-igniter
or, if you have created a project with a package.json
file:
npm install mongodb-igniter --save
Basic Usage
Create a Database Declaration
First create a configuration object for your database, collections, indexes, and documents using the following property specifications (click the links for more detailed information on the types):
DbDeclaration
: The overall declaration for the database configuration
Property | Type | Description |
---|---|---|
db | string or Promise<Db> |
MongoDB connection URI or Promise which resolves to MongoDB Db type |
options | MongoClientOptions |
Optional: Options for the MongoClient.connect() method |
collections | CollectionDeclaration[] |
This is an array of a custom type in this module. Details are in the next table. |
CollectionDeclaration
: A declaration of a collection to create within the database
Property | Type | Description |
---|---|---|
name | string |
The name of the collection |
options | CollectionCreateOptions |
Optional: Options for the Db.createCollection() method |
indexes | IndexDeclaration[] |
Optional: This is an array of a custom type in this module. Details are in the next table. |
documents | DocumentDeclaration[] |
Optional: This is an array of a custom type in this module. Details are two tables down. |
IndexDeclaration
: A declaration of an index to create within a collection
Property | Type | Description |
---|---|---|
keys | string or Object |
This can be the name of a field to create an ascending index on with default options, or an object which describes the index. See the fieldOrSpec parameter of the Collection.createIndex() method for more information on the object format |
options | IndexOptions |
Optional: Options for the Collection.createIndex() method |
DocumentDeclaration
: A declaration of a document to create or replace within a collection. mongo-igniter
uses the Node.js MongoDB native driver's Collection.replaceOne() method for all declared documents.
Property | Type | Description |
---|---|---|
filter | Object |
An object which describes the filter used to locate the document to replace, if it exists. See the filter parameter of the Collection.replaceOne() method for more information on the object format |
data | Object |
The document data to insert or replace an existing document with |
options | ReplaceOneOptions |
Optional: Options for the Collection.replaceOne() method |
Example
The following is an example of a Database Declaration:
const dbDeclaration = db: 'mongodb://localhost:27017/testdb' // Remember, you can also use an existing connection of type Promise<Db> here options: appname: 'mongodb-igniter' collections: name: 'clients' indexes: keys: clientIdHash: 1 options: unique: true background: true documents: filter: name: 'Test Client for Mobile' data: name: "Test Client for Mobile" clientIdHash: "rdZBlx68P07di+3XZ8hMROh+GrcN9ccO2W0+cZa39jI=" clientSecretHash: "$2a$10$8MTa8EaiqsxBSCqdgIv0O.g1jOEyAGm5RmZzEaPB3DxY0/wcZUhzq" trustedClient: true options: upsert: true filter: name: 'Test Client for Web' data: name: "Test Client for Web" clientIdHash: "jqcQMI4QllIFRyTDuirdu3TVQ2r6rjXR4gfUlsYtCG4=" clientSecretHash: "$2a$10$gVDmGvOBrOjk.TF6z1TkkuljtkQNH6Ktxs8/mN9qhce3J8vVEWcum" redirectUri: "http://localhost:3000/login" trustedClient: true options: upsert: true name: 'tokens' indexes: keys: userId: 1 clientIdHash: 1 options: name: 'userId_1_clientIdHash_1' unique: true background: true keys: expirationDate: 1 options: name: 'expirationDate_1' expireAfterSeconds: 31536000 // 1 year in seconds background: true name: 'sessions' indexes: keys: expires: 1 options: expireAfterSeconds: 0 background: true name: 'users' indexes: keys: email: 1 options: unique: true background: true name: 'logs' options: capped: true size: 1048576 // Capped at 1MB in bytes ;
Initialize the Database
Once you have the database configuration declared, you can use it to initialize the database. This module was created "callback-hell"-free, so the initialization function returns a Promise
.
Examples
Using Promise.then()
-style syntax, you could do the following:
const MongoDbIgniter = ; MongoDbIgniter ;
or using async
/await
:
const MongoDbIgniter = ; { try await MongoDbIgniter; console; catch err console; } ;
This is all you need for basic usage. Depending on your use case, you may want to log or analyze the results of the initialization operations. See the next section for more information on this.
Results
mongodb-igniter
returns results for all operations it performs in a neatly organized array of objects. The result is an array of collection initialization results (CollectionInitializationResult[]
), as described below:
CollectionInitializationResult
: The result of operations on a single initialized collection
Property | Type | Description |
---|---|---|
collectionName | string |
The name of the initialized collection |
indexNames | string[] |
This property will only exist if there are indexes initialized. It is an array of the initialized index names. |
documentInitializationResults | ReplaceWriteOpResult[] |
This property will only exist if there are documents initialized. It is an array of ReplaceWriteOpResult, which is the return object from the Collection.replaceOne() method. |
For a more detailed example of module usage and processing these result objects, see the TypeScript test folder or the JavaScript test folder.