Mongo Seeding CLI and Library

Common errors

• TypeError: Cannot read properties of undefined (reading 'collectionInsertManyOptions') or Property 'collectionInsertManyOptions' does not exist on type 'SeederConfig'.

  cause Attempting to use `collectionInsertManyOptions` in `SeederConfig` after upgrading to `mongo-seeding` v4.x.
  fix Replace `collectionInsertManyOptions` with `bulkWriteOptions` in your `SeederConfig` object.

• SyntaxError: Cannot use import statement outside a module or ReferenceError: require is not defined

  cause Mixing CommonJS `require()` with ESM `import` statements in Node.js, or trying to use ESM syntax in a non-ESM context (e.g., a `.js` file without `"type": "module"` in `package.json`).
  fix For programmatic use, ensure your project is configured for ESM (add `"type": "module"` to `package.json`) and use `import` statements. If using CommonJS, stick to `require()` and ensure the library version supports it, or use a transpiler.

• MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017 or Unable to connect to MongoDB

  cause The MongoDB server is not running, is configured on a different host/port, or network issues are preventing a connection.
  fix Verify that your MongoDB instance is running and accessible. Check the connection URI/details (host, port, credentials) in your `SeederConfig` or CLI parameters (e.g., `--db-uri`). Ensure no firewall is blocking the connection. Run `docker run --rm -p 27017:27017 mongo` for a quick local MongoDB instance.

• Error: Path to collections is not specified or Error: No collections found in the specified path

  cause The path provided to `seeder.readCollectionsFromPath()` is incorrect, empty, or the data files within do not follow the expected structure (e.g., subdirectories for collections, JS/JSON files exporting data).
  fix Double-check the `path.resolve()` argument. Ensure your data directory has subdirectories named after your collections (e.g., `./data/users/user-data.js`) and each file exports an array or object of documents.

Warnings

• breaking In `mongo-seeding` v4.0.0, the `collectionInsertManyOptions` property in `SeederConfig` was replaced by `bulkWriteOptions`. This change aligns with updates in the underlying MongoDB driver API.
  Fix: Update your `SeederConfig` to use `bulkWriteOptions` instead of `collectionInsertManyOptions`. For example, `{ bulkWriteOptions: { ordered: false } }`.
• gotcha The `mongo-seeding` library and CLI periodically update their supported Node.js versions. For example, v3.7.1 updated to Node 16, and v4.0.2 updated to Node 22.15. Using an older Node.js runtime with newer package versions may lead to compatibility issues or errors.
  Fix: Ensure your Node.js environment meets the minimum requirements specified in the package's `package.json` or release notes. Consider using `nvm` or a similar tool to manage Node.js versions.
• gotcha For TypeScript data import files, ensure proper configuration for `ts-node` or a similar transpiler if running directly, or pre-transpile the files. The `--transpile-only` CLI option can improve performance by skipping type checking.
  Fix: If encountering issues with TypeScript data files, add `ts-node` to your project and register it, or use the `--transpile-only` flag with the CLI: `DEBUG=mongo-seeding npx ts-node your-seed-script.ts` or `seed --transpile-only ./data`.

Install

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

Imports

• Seeder
  wrong:

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

  correct:

  import { Seeder } from 'mongo-seeding';

  While CommonJS `require` is shown in older examples, modern Node.js and TypeScript projects should use ESM `import` for `mongo-seeding` v3+ for better compatibility and type inference.
• SeederConfig
  wrong:

  import { SeederConfig } from 'mongo-seeding';

  correct:

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

  Import `SeederConfig` as a type for configuration interfaces, primarily used with TypeScript for type checking.
• Transformers
  wrong:

  import { Transformers } from 'mongo-seeding';

  correct:

  import { Seeder } from 'mongo-seeding'; const { replaceDocumentIdWithUnderscoreId, setTimestamps } = Seeder.Transformers;

  Utility transformers are exposed as static properties on the `Seeder` class, not as top-level named exports.

Quickstart

This quickstart demonstrates how to programmatically seed a MongoDB database using the `mongo-seeding` library in TypeScript, including configuring the seeder, reading data from files, and applying transformers. It also highlights the usage of `bulkWriteOptions` introduced in v4.0.0.

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

const config = {
  database: 'mongodb://localhost:27017/my-database-test',
  dropDatabase: true, // Be cautious: this will delete the entire database
  dropCollections: true,
  // As of v4.0.0, use bulkWriteOptions instead of collectionInsertManyOptions
  bulkWriteOptions: {
    ordered: false,
  },
};

const seeder = new Seeder(config);
const collections = seeder.readCollectionsFromPath(
  path.resolve(__dirname, './data'),
  {
    transformers: [Seeder.Transformers.replaceDocumentIdWithUnderscoreId],
  },
);

async function seedDatabase() {
  try {
    console.log('Starting database seeding...');
    await seeder.import(collections);
    console.log('Database seeding completed successfully.');
  } catch (err) {
    console.error('Database seeding failed:', err);
    process.exit(1);
  }
}

// Example data structure in a './data/users/users.js' file:
// module.exports = [
//   { id: 'user1', name: 'Alice', email: 'alice@example.com' },
//   { id: 'user2', name: 'Bob', email: 'bob@example.com' },
// ];

seedDatabase();