TypeORM Extension Library

Common errors

• Error: Cannot find module '@faker-js/faker'

  cause You are using SeederFactory features (e.g., `setSeederFactory().make()`) but `@faker-js/faker` is not installed as a direct dependency in your project.
  fix Install faker as a project dependency: `npm install @faker-js/faker` or `yarn add @faker-js/faker`.

• DataSource is not initialized.

  cause A TypeORM DataSource object was not properly initialized or connected before an operation (e.g., `runSeeder`, `createDatabase`) was attempted. This often happens if `createDataSource` fails or `dataSource.initialize()` is not awaited.
  fix Ensure `await createDataSource(config)` successfully completes and returns an initialized DataSource instance before proceeding with any database operations or seeding.

• Error: connect ECONNREFUSED ::1:5432

  cause The database server configured in your TypeORM DataSource options (e.g., PostgreSQL on port 5432) is not running or is not accessible from where your application is executing.
  fix Verify that your database server is running, listening on the correct port, and that your connection credentials and hostname in the DataSource configuration are accurate. Check firewall rules if applicable.

Warnings

• gotcha The `@faker-js/faker` library is a peer dependency and became optional/on-demand loaded since v3.8.0. If you are using `setSeederFactory` or other faker-dependent features, you must explicitly install `@faker-js/faker` in your project.
  Fix: npm install @faker-js/faker
• breaking Prior to v3.9.0, the `generateMigration` operation could inadvertently destroy the data-source connection after execution, leading to unexpected errors or requiring manual re-initialization for subsequent operations.
  Fix: Upgrade to v3.9.0 or later. If unable to upgrade, ensure your application re-initializes the DataSource or handles potential connection loss after calling `generateMigration`.
• gotcha In versions prior to v3.7.3, certain database operations might not have consistently preserved all DataSource options, potentially leading to incorrect behavior or configurations not being applied as expected.
  Fix: Update to v3.7.3 or a newer version to ensure DataSource options are consistently preserved across operations.
• breaking Behavior related to pagination (`options.maxLimit`) was adjusted in versions 3.7.4 and 3.8.0. If you rely on specific default pagination limits or their application, review your code after upgrading, as the exact application and defaulting logic may have changed.
  Fix: Test pagination-dependent features thoroughly after upgrading. Explicitly define pagination options where specific behavior is required, rather than relying solely on defaults.

Install

• npm install typeorm-extension npm
• yarn add typeorm-extension yarn
• pnpm add typeorm-extension pnpm

Imports

• DataSource
  wrong:

  import { DataSource } from 'typeorm-extension';

  correct:

  import { DataSource } from 'typeorm';

  DataSource is a core TypeORM class, not exported directly from typeorm-extension. Always import it from 'typeorm'.
• createDataSource
  wrong:

  const createDataSource = require('typeorm-extension').createDataSource;

  correct:

  import { createDataSource } from 'typeorm-extension';

  The library primarily uses ES Modules. While CommonJS might work via transpilation, direct require() is less idiomatic for modern Node.js environments targeted by this library.
• runSeeder
  wrong:

  import runSeeder from 'typeorm-extension';

  correct:

  import { runSeeder } from 'typeorm-extension';

  runSeeder is a named export. Ensure you destructure it correctly.
• Seeder
  wrong:

  import Seeder from 'typeorm-extension';

  correct:

  import { Seeder } from 'typeorm-extension';

  The base Seeder class for creating custom seeders is a named export.
• setSeederFactory
  wrong:

  import { seederFactory } from 'typeorm-extension';

  correct:

  import { setSeederFactory } from 'typeorm-extension';

  setSeederFactory is used to define factories for entities; it's a named export.

Quickstart

This quickstart demonstrates how to create a TypeORM DataSource, define an entity, set up a SeederFactory for generating fake data with `@faker-js/faker`, and then execute a custom Seeder to populate the database. It includes creating and dropping the schema for a clean run.

import { DataSource, Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
import { createDataSource, runSeeder, Seeder, SeederFactory, setSeederFactory } from 'typeorm-extension';
import { faker } from '@faker-js/faker';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id!: number;

  @Column()
  firstName!: string;

  @Column()
  lastName!: string;

  @Column({ unique: true })
  email!: string;
}

// 1. Define a SeederFactory
setSeederFactory(User, (faker) => {
  const user = new User();
  user.firstName = faker.person.firstName();
  user.lastName = faker.person.lastName();
  user.email = faker.internet.email().toLowerCase();
  return user;
});

// 2. Create a Seeder class
class UserSeeder implements Seeder {
  async run(dataSource: DataSource): Promise<any> {
    const repository = dataSource.getRepository(User);

    const users = await Promise.all(
      Array(10)
        .fill(null)
        .map(() => setSeederFactory(User)(faker).make())
    );
    await repository.save(users);
    console.log(`Seeded ${users.length} users.`);
  }
}

// 3. Main execution function
async function bootstrap() {
  // Create a new DataSource connection
  const dataSource = await createDataSource({
    type: 'sqlite',
    database: './temp_db.sqlite',
    entities: [User],
    synchronize: true, // Automatically create schema for demo
    logging: false,
    dropSchema: true // Drop schema to ensure a clean state for demo
  });

  if (!dataSource) {
    throw new Error('DataSource not initialized');
  }

  console.log('DataSource created and connected.');

  try {
    // Run the seeder
    await runSeeder(dataSource, UserSeeder);
    console.log('Seeding complete.');
  } catch (error) {
    console.error('Seeding failed:', error);
  } finally {
    // Ensure the data source is closed
    if (dataSource.isInitialized) {
      await dataSource.destroy();
      console.log('DataSource destroyed.');
    }
  }
}

bootstrap().catch(console.error);