Introduction

@nestbolt/factory is a model factory and database seeder package for NestJS applications. It lets you generate realistic fake data for any TypeORM entity through a fluent, chainable builder API powered by Faker.js.

Key Features

• Fluent builder API -- chain count(), state(), override(), sequence(), and lifecycle callbacks to build exactly the data you need.
• Named states -- define reusable entity variations (e.g., admin, inactive, published) as methods on your factory class.
• Sequences -- auto-increment, cycle, or compute field values across multiple generated entities.
• Database seeders -- populate your database with structured test data using ordered, composable seeder classes.
• Lifecycle hooks -- run logic after entities are made or persisted with afterMake and afterCreate hooks on both the factory and the builder.
• Reproducible data -- set a Faker seed for deterministic output across test runs.
• Event system -- react to seeder lifecycle events via @nestjs/event-emitter (optional).
• Make or create -- generate in-memory entities with make() or persist them to the database with create().

Architecture

The package is built around several core components:

FactoryModule registers all providers globally. You call FactoryModule.forRoot() or FactoryModule.forRootAsync() once in your root module, and FactoryService becomes available everywhere via dependency injection.

FactoryService is the primary API surface. It manages registered factory instances, provides access to the Faker instance, and orchestrates seeder execution.

BaseFactory<T> is the abstract class you extend to define how each entity is generated. It declares the entity class, a definition() method that returns default attributes, and optional afterMake/afterCreate lifecycle hooks.

FactoryBuilder<T> implements the fluent builder pattern. You chain configuration calls (.count(), .state(), .override(), .sequence(), .afterCreating(), .afterMaking()) and finalize by calling .make() or .create().

Sequence provides auto-incrementing, cycling, and custom-computed values for fields that need unique or predictable patterns across multiple entities.

Seeder is an interface for classes that populate the database. Each seeder has an order property for execution priority and a run() method that receives the FactoryService.

Basic Usage

import { BaseFactory, FactoryService } from "@nestbolt/factory";
import type { Faker } from "@faker-js/faker";

class UserFactory extends BaseFactory<User> {
  get entity() { return User; }

  definition(faker: Faker): Partial<User> {
    return {
      name: faker.person.fullName(),
      email: faker.internet.email(),
      role: "user",
    };
  }

  admin(): Partial<User> {
    return { role: "admin" };
  }
}

// In your service or seeder:
await factoryService.use(UserFactory).count(5).state("admin").create();

Next Steps

• Installation -- install the package and its peer dependencies.
• Quick Start -- set up the module, define a factory, and generate data in minutes.
• Configuration -- all forRoot and forRootAsync options explained.
• Defining Factories -- create factory classes with definitions and lifecycle hooks.
• Factory Builder -- the full fluent builder API reference.
• States -- define and apply named entity variations.
• Sequences -- auto-increment, cycle, and compute field values.
• Seeders -- populate your database with structured test data.
• Events -- listen to seeder lifecycle events.