MongoDB Database Seeding Library

Common errors

• MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

  cause The MongoDB server is not running or is not accessible at the specified URI/port.
  fix Ensure your MongoDB instance is running. Verify the `database.uri` in your `SeederConfig` or the `MONGO_URI` environment variable is correct and points to an active MongoDB server.

• Error: ENOENT: no such file or directory, scandir '/path/to/nonexistent/data'

  cause The path provided to `seeder.readCollectionsFromPath()` does not exist or is incorrect.
  fix Double-check the path provided to `readCollectionsFromPath`. Use `path.resolve(__dirname, 'your-data-directory')` to ensure an absolute path is used, especially when running from different working directories.

• TypeError: Cannot read properties of undefined (reading 'insertMany')

  cause This often occurs when the database connection is not established correctly or the `mongodb` driver version is incompatible.
  fix Ensure the `mongodb` driver is installed and compatible with `mongo-seeding`'s version. Check the `database.uri` and `database.options` in your `SeederConfig` for correct connection parameters.

Warnings

• breaking The `collectionInsertManyOptions` property in `SeederConfig` has been removed and replaced with `bulkWriteOptions`. This change aligns with updates in the underlying MongoDB driver's bulk operation handling.
  Fix: Update your `SeederConfig` to use `bulkWriteOptions` instead of `collectionInsertManyOptions`. For example, `bulkWriteOptions: { ordered: true }` replaces `collectionInsertManyOptions: { ordered: true }`.
• gotcha When using JavaScript files (`.js`) or TypeScript files (`.ts`) for seed data, ensure that the files export an array of documents as their default export. Non-array exports or incorrect export formats will lead to silent failures or errors during import.
  Fix: Verify that your seed data files (e.g., `users.js`) contain a `export default [...]` where `...` is an array of MongoDB documents.
• gotcha The library might not explicitly close the underlying MongoDB client connection after seeding, depending on how it's initialized. In long-running processes or serverless environments, this can lead to open connections.
  Fix: Ensure you manage the MongoDB client lifecycle externally if necessary. If `mongo-seeding` creates the client internally, there might not be a direct method to close it via the `Seeder` instance. Consider explicitly connecting and passing an `MongoClient` instance to the seeder's config if fine-grained control is needed.

Install

• npm install mongo-seeding npm
• yarn add mongo-seeding yarn
• pnpm add mongo-seeding pnpm

Imports

• Seeder
  wrong:

  const Seeder = require('mongo-seeding');

  correct:

  import { Seeder } from 'mongo-seeding';

  The library primarily uses ES modules. For CommonJS, dynamic import or specific transpilation settings might be required, though direct `require` is not recommended for modern usage.
• SeederConfig
  wrong:

  import { SeederConfig } from 'mongo-seeding';

  correct:

  import type { SeederConfig } from 'mongo-seeding';

  Used as a type for configuration options. Use `import type` for type-only imports to prevent bundling issues and improve tree-shaking.
• DatabaseConfig

  import type { DatabaseConfig } from 'mongo-seeding';

  A type definition for database connection settings, useful when defining the `database` property within `SeederConfig`.

Quickstart

This quickstart demonstrates how to initialize `mongo-seeding`, configure the database connection, read seed data from a directory, and import it into MongoDB. It includes handling potential errors during the seeding process.

import { Seeder } from 'mongo-seeding';
import path from 'path';

const MONGO_URI = process.env.MONGO_URI ?? 'mongodb://localhost:27017/my-database';

const config = {
  database: {
    uri: MONGO_URI,
    options: {
      useNewUrlParser: true,
      useUnifiedTopology: true,
    },
  },
  dropDatabase: true, // Clears the database before seeding
  bulkWriteOptions: {
    ordered: true,
    // writeConcern: { w: 'majority' }
  }
};

const seeder = new Seeder(config);

const collections = seeder.readCollectionsFromPath(
  path.resolve(__dirname, 'data'), // Assuming 'data' directory contains JSON/JS files
  {
    extensions: ['json', 'js', 'ts'],
  },
);

async function seedDatabase() {
  try {
    await seeder.import(collections);
    console.log('Database seeded successfully!');
  } catch (err) {
    console.error('Error seeding database:', err);
  } finally {
    // The Seeder class doesn't expose a direct close method for the client.
    // In a real application, ensure the underlying MongoClient is closed if managed externally.
  }
}

seedDatabase();

// Example content for 'data/users.json':
// [
//   { "name": "Alice", "email": "alice@example.com" },
//   { "name": "Bob", "email": "bob@example.com" }
// ]