@conpago/mongo-seeding
v4.1.0
Published
The ultimate Node.js library for populating your MongoDB database.
Downloads
13
Readme
Mongo Seeding
The ultimate solution for populating your MongoDB database. Define the data in JavaScript or JSON files. Import collections and documents!
Table of contents
Installation
To install the app, run the following command:
npm install mongo-seeding --save
Usage
Import the
Seeder
class:const { Seeder } = require('mongo-seeding');
Define a partial configuration object. The object will be merged with the default config object (see Configuration section). Therefore, you can specify only properties, which should override the default values, for example:
const config = { database: { host: '127.0.0.1', port: 27017, name: 'mydatabase', }, dropDatabase: true, };
Instead of database configuration object, you can also provide database connection URI to the
database
property:const config = { database: 'mongodb://127.0.0.1:27017/mydatabase', dropDatabase: true, };
Instantiate
Seeder
class:const seeder = new Seeder(config);
(OPTIONAL) To read MongoDB collections from disk, firstly follow the tutorial in order to define documents and collections to import. Next, read them using
readCollectionsFromPath
method:const path = require('path'); const collections = seeder.readCollectionsFromPath( path.resolve('./your/path'), );
Seed your database:
with
async/await
, for example:try { await seeder.import(collections); } catch (err) { // Handle errors } // Do whatever you want after successful import
with raw promises:
seeder .import(collections) .then(() => { // Do whatever you want after successful import }) .catch((err) => { // Handle errors });
See an import data example for a sample Node.js application utilizing the library.
API description
The Seeder
class contains the following methods.
constructor(partialConfig?)
Constructs a new Seeder
instance and loads configuration for data import.
Configuration
You can override any default configuration property by passing partial config object to the Seeder
constructor. The object is merged with the default configuration object. To use all default settings, simply omit the constructor argument (new Seeder()
).
The following snippet represents the type definition of Seeder
config with all available properties:
export interface SeederConfig {
database: string | SeederDatabaseConfigObject; // database connection URI or configuration object
databaseReconnectTimeout: number; // maximum time of waiting for successful MongoDB connection in milliseconds. Ignored when `mongoClientOptions` are passed.
dropDatabase: boolean; // drops entire database before import
dropCollections: boolean; // drops every collection which is being imported
mongoClientOptions?: MongoClientOptions; // optional MongoDB connect options
}
export interface SeederDatabaseConfigObject {
protocol: string;
host: string;
port: number;
name: string;
username?: string;
password?: string;
options?: SeederDatabaseConfigObjectOptions; // see all options for Database Connection URI: https://docs.mongodb.com/manual/reference/connection-string
}
export type SeederDatabaseConfigObjectOptions = {
[key: string]: string;
};
In order to configure database connection, specify connection URI for database
property or assign a partial SeederDatabaseConfigObject
object, overriding necessary properties.
Default configuration:
The default configuration object is as follows:
const defaultConfig = {
database: {
protocol: 'mongodb',
host: '127.0.0.1',
port: 27017,
name: 'database',
username: undefined,
password: undefined,
},
databaseReconnectTimeout: 10000,
dropDatabase: false,
dropCollections: false,
mongoClientOptions: undefined,
};
readCollectionsFromPath(path, partialOptions?)
Populates collections and their documents from given path. The path has to contain import data structure described here.
Options
You can specify an optional partial options object for this method, which will be merged with default configuration object. See the interface of the options, which describes all possible options:
export interface SeederCollectionReadingOptions {
extensions: string[]; // files that should be imported
ejsonParseOptions?: EJSON.Options; // options for parsing EJSON files with `.json` extension
transformers: Array<(collection: SeederCollection) => SeederCollection>; // optional transformer functions
}
For example, you may provide the following options object:
const collectionReadingOptions = {
extensions: ['ts', 'js', 'cjs', 'json'],
ejsonParseOptions: {
relaxed: false,
},
transformers: [Seeder.Transformers.replaceDocumentIdWithUnderscoreId],
};
const collections = seeder.readCollectionsFromPath(
path.resolve('./your/path'),
collectionReadingOptions,
);
Transform function is a simple function in a form of (collection: SeederCollection) => SeederCollection
. It means that you can manipulate collections after reading them from disk. SeederCollection
is defined as follows:
interface SeederCollection {
name: string;
documents: object[];
}
There is two built-in transform functions:
Seeder.Transformers.replaceDocumentIdWithUnderscoreId
, which replacesid
field with_id
property for every document in collection.Seeder.Transformers.setTimestamps
, which setscreatedAt
andupdatedAt
timestamps for every document in collection.
Default options
The default options object is as follows:
const defaultCollectionReadingConfig: SeederCollectionReadingConfig = {
extensions: ['json', 'js', 'cjs'],
ejsonParseOptions: {
relaxed: true,
},
transformers: [],
};
import(collections, partialConfig?)
This method connects to a database and imports all provided collections. collections
argument type is an array of SeederCollection
type, which is defined as follows:
interface SeederCollection {
name: string;
documents: object[];
}
Configuration
You can provide additional partialConfig
argument in a form of Seeder
partial configuration object - the same used in the constructor. It is an easy way to change the configuration for one single data import. The configuration object will be merged with provided configuration from constructor and default config.
Debug output
In order to see debug output, set environmental variable DEBUG
to value mongo-seeding
before starting your Node.js app:
DEBUG=mongo-seeding node yourapp/index.js
You can also set it programmatically before requiring mongo-seeding
:
process.env.DEBUG = 'mongo-seeding';
const { Seeder } = require('mongo-seeding');