{"id":16557,"library":"typeorm-extension","title":"TypeORM Extension Library","description":"typeorm-extension is a robust library that augments TypeORM with essential database management functionalities, including streamlined database creation and dropping, and a powerful, flexible data seeding mechanism. It integrates seamlessly with the TypeORM ecosystem, offering CLI commands for many of its operations. Currently at version 3.9.0, the library maintains an active release cadence, frequently introducing minor features and critical bug fixes. Its key differentiators lie in simplifying complex database setup and teardown, as well as providing sophisticated factory-based data seeding capabilities, which are especially useful for development, testing, and populating initial datasets. It acts as a significant convenience layer over raw TypeORM operations for these specific use cases.","status":"active","version":"3.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/tada5hi/typeorm-extension","tags":["javascript","database","create","drop","api","json-api","jsonapi","migration","seeder","typescript"],"install":[{"cmd":"npm install typeorm-extension","lang":"bash","label":"npm"},{"cmd":"yarn add typeorm-extension","lang":"bash","label":"yarn"},{"cmd":"pnpm add typeorm-extension","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core ORM library that typeorm-extension extends. All operations depend on a TypeORM DataSource.","package":"typeorm","optional":false},{"reason":"Required for using the SeederFactory feature to generate fake data. It became an optional, on-demand loaded peer dependency in v3.8.0, meaning it's only needed if you use factories.","package":"@faker-js/faker","optional":true}],"imports":[{"note":"DataSource is a core TypeORM class, not exported directly from typeorm-extension. Always import it from 'typeorm'.","wrong":"import { DataSource } from 'typeorm-extension';","symbol":"DataSource","correct":"import { DataSource } from 'typeorm';"},{"note":"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.","wrong":"const createDataSource = require('typeorm-extension').createDataSource;","symbol":"createDataSource","correct":"import { createDataSource } from 'typeorm-extension';"},{"note":"runSeeder is a named export. Ensure you destructure it correctly.","wrong":"import runSeeder from 'typeorm-extension';","symbol":"runSeeder","correct":"import { runSeeder } from 'typeorm-extension';"},{"note":"The base Seeder class for creating custom seeders is a named export.","wrong":"import Seeder from 'typeorm-extension';","symbol":"Seeder","correct":"import { Seeder } from 'typeorm-extension';"},{"note":"setSeederFactory is used to define factories for entities; it's a named export.","wrong":"import { seederFactory } from 'typeorm-extension';","symbol":"setSeederFactory","correct":"import { setSeederFactory } from 'typeorm-extension';"}],"quickstart":{"code":"import { DataSource, Entity, PrimaryGeneratedColumn, Column } from 'typeorm';\nimport { createDataSource, runSeeder, Seeder, SeederFactory, setSeederFactory } from 'typeorm-extension';\nimport { faker } from '@faker-js/faker';\n\n@Entity()\nexport class User {\n  @PrimaryGeneratedColumn()\n  id!: number;\n\n  @Column()\n  firstName!: string;\n\n  @Column()\n  lastName!: string;\n\n  @Column({ unique: true })\n  email!: string;\n}\n\n// 1. Define a SeederFactory\nsetSeederFactory(User, (faker) => {\n  const user = new User();\n  user.firstName = faker.person.firstName();\n  user.lastName = faker.person.lastName();\n  user.email = faker.internet.email().toLowerCase();\n  return user;\n});\n\n// 2. Create a Seeder class\nclass UserSeeder implements Seeder {\n  async run(dataSource: DataSource): Promise<any> {\n    const repository = dataSource.getRepository(User);\n\n    const users = await Promise.all(\n      Array(10)\n        .fill(null)\n        .map(() => setSeederFactory(User)(faker).make())\n    );\n    await repository.save(users);\n    console.log(`Seeded ${users.length} users.`);\n  }\n}\n\n// 3. Main execution function\nasync function bootstrap() {\n  // Create a new DataSource connection\n  const dataSource = await createDataSource({\n    type: 'sqlite',\n    database: './temp_db.sqlite',\n    entities: [User],\n    synchronize: true, // Automatically create schema for demo\n    logging: false,\n    dropSchema: true // Drop schema to ensure a clean state for demo\n  });\n\n  if (!dataSource) {\n    throw new Error('DataSource not initialized');\n  }\n\n  console.log('DataSource created and connected.');\n\n  try {\n    // Run the seeder\n    await runSeeder(dataSource, UserSeeder);\n    console.log('Seeding complete.');\n  } catch (error) {\n    console.error('Seeding failed:', error);\n  } finally {\n    // Ensure the data source is closed\n    if (dataSource.isInitialized) {\n      await dataSource.destroy();\n      console.log('DataSource destroyed.');\n    }\n  }\n}\n\nbootstrap().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"npm install @faker-js/faker","message":"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.","severity":"gotcha","affected_versions":">=3.8.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":"<3.9.0"},{"fix":"Update to v3.7.3 or a newer version to ensure DataSource options are consistently preserved across operations.","message":"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.","severity":"gotcha","affected_versions":"<3.7.3"},{"fix":"Test pagination-dependent features thoroughly after upgrading. Explicitly define pagination options where specific behavior is required, rather than relying solely on defaults.","message":"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.","severity":"breaking","affected_versions":">=3.7.4 <3.8.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install faker as a project dependency: `npm install @faker-js/faker` or `yarn add @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.","error":"Error: Cannot find module '@faker-js/faker'"},{"fix":"Ensure `await createDataSource(config)` successfully completes and returns an initialized DataSource instance before proceeding with any database operations or seeding.","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.","error":"DataSource is not initialized."},{"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.","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.","error":"Error: connect ECONNREFUSED ::1:5432"}],"ecosystem":"npm"}