@ackplus/nest-seeder 1.1.16 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to `@ackplus/nest-seeder` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-06-15
+
+A focused redesign that keeps the proven core (`@Factory`, `Seeder`, `DataFactory`) while
+overhauling the CLI, configuration ergonomics, packaging, and documentation.
+
+See the [Migration Guide](https://ack-solutions.github.io/nest-seeder/migration) for upgrade steps.
+
+### Added
+
+- **`nest-seed init`** — scaffolds a `seeder.config.ts`, a factory, and a seeder (`--orm typeorm|mongoose`, `--force`).
+- **`nest-seed list`** — lists registered seeders and their `--name` aliases.
+- **Config auto-discovery** — the CLI finds `seeder.config.{ts,js,cjs,mjs}` automatically; `--config` is now optional.
+- **`--dry-run`** — preview which seeders would run without writing data.
+- **`--continue-on-error`** — keep going when a seeder throws instead of aborting.
+- **`--context <json>`** — forward arbitrary JSON to every seeder via `options.context`.
+- **`@SeederName('name')`** decorator and `getSeederName()` helper for stable, minification-safe seeder names.
+- **`defineSeederConfig()`** — a typed identity helper for `seeder.config.ts`.
+- **`DataFactory` `generateOne()`** convenience method.
+- **Factory inheritance** — a factory that `extends` a base factory inherits its `@Factory` properties.
+- **Dual ESM + CJS build** with a proper `exports` map and full TypeScript declarations.
+- **Unit test suite** for the library (factory, service, decorators).
+- **Documentation site** built with VitePress, plus this changelog and a migration guide.
+
+### Changed
+
+- **CLI** rewritten with subcommands (`run`/`init`/`list`) and clearer, colorized output.
+- **Logging** now uses the NestJS `Logger` instead of raw `console.*`.
+- **Refresh** drops seeders in **reverse order** (foreign-key safe) before reseeding.
+- **`drop()` is now optional** on the `Seeder` interface; seeders without it are skipped during refresh.
+- **Factory overrides** now always appear in the generated record — including keys that are not
+  `@Factory` properties (e.g. a foreign key passed in a seeder).
+- **`dependsOn`** is resolved transitively and is no longer sensitive to declaration order.
+- **Build tooling** switched to `tsup`. Node `>= 18` is now required.
+- `--dummyData` flag renamed to `--dummy-data` (the `options.dummyData` value is still delivered, deprecated).
+
+### Fixed
+
+- Overrides for non-decorated properties were silently dropped, causing `NOT NULL` failures when
+  seeding relationships (e.g. `factory.generate(3, { authorId })`).
+- Transitive `dependsOn` chains were not fully resolved.
+- Generated property order was reversed relative to declaration order.
+- Seeder selection mutated the shared options object in place.
+
+### Removed
+
+- The bundled `examples/` directory and `seeder.config.example.ts` — replaced by the
+  [documentation site](https://ack-solutions.github.io/nest-seeder/) and the runnable example app.
+- Deep imports of internal files (`@ackplus/nest-seeder/dist/lib/...`) are no longer supported;
+  import from the package root.
+
+## [1.1.16] - 2026-01-04
+
+- Last release of the v1 line. Iterative fixes and packaging tweaks across the `1.1.x` series
+  (including the `1.1.15-beta.*` pre-releases).
+
+[2.0.0]: https://github.com/ack-solutions/nest-seeder/releases/tag/2.0.0
+[1.1.16]: https://github.com/ack-solutions/nest-seeder/releases/tag/1.1.16

package/MIGRATION.md

@@ -0,0 +1,89 @@
+# Migrating from v1 to v2
+
+`@ackplus/nest-seeder` v2 is a **focused redesign**. The core — the `@Factory` decorator, the
+`Seeder` interface, and `DataFactory` — is unchanged, so most apps upgrade in a few minutes.
+Breaking changes are concentrated in the **CLI**, **config ergonomics**, and **packaging**.
+
+> 📖 Full, searchable guide: https://ack-solutions.github.io/nest-seeder/migration
+
+## TL;DR
+
+1. `npm install @ackplus/nest-seeder@^2`
+2. Replace your long seed script with `"seed": "nest-seed"`.
+3. Rename the `--dummyData` flag to `--dummy-data`.
+4. If your `drop()` uses `repository.delete({})`, switch to `repository.createQueryBuilder().delete().execute()`.
+
+Everything else is optional polish.
+
+## At a glance
+
+| Area | v1 | v2 |
+| --- | --- | --- |
+| Run command | `node -r ts-node/register … dist/cli.js -c ./seeder.config.ts` | `nest-seed` (config auto-detected) |
+| `--config` | Required | Optional (auto-discovers `seeder.config.{ts,js,cjs,mjs}`) |
+| Dummy-data flag | `--dummyData` | `--dummy-data` (or the new `--context`) |
+| Scaffolding | none | `nest-seed init` |
+| Inspect seeders | none | `nest-seed list` |
+| Preview | none | `nest-seed --dry-run` |
+| `drop()` | required | optional |
+| Refresh drop order | same as list | reverse of list (foreign-key safe) |
+| Build output | CommonJS only | Dual ESM + CJS with an `exports` map |
+
+## Steps
+
+### 1. Update the dependency
+
+```bash
+npm install @ackplus/nest-seeder@^2 @faker-js/faker
+npm install -D ts-node typescript   # for .ts config files
+```
+
+### 2. Simplify your run script
+
+```json
+{
+  "scripts": {
+    "seed": "nest-seed",
+    "seed:refresh": "nest-seed --refresh"
+  }
+}
+```
+
+The verbose v1 command still works; the `dist/cli.js` path is preserved.
+
+### 3. Rename the dummy-data flag
+
+```bash
+nest-seed --dummy-data        # was: --dummyData
+```
+
+For new code prefer the general-purpose `--context '{ "size": "large" }'`, read via `options.context`.
+
+### 4. Fix your `drop()` (⚠️ important)
+
+```ts
+// before — modern TypeORM throws "Empty criteria(s) are not allowed"
+await this.userRepository.delete({});
+
+// after
+await this.userRepository.createQueryBuilder().delete().execute();
+```
+
+Mongoose is unchanged: `await this.userModel.deleteMany({})`.
+
+### 5. Optional polish
+
+- Wrap your config in `defineSeederConfig({ … })` for full type-checking.
+- Add `@SeederName('users')` to seeders for stable `--name users` selection (run `nest-seed list` to verify).
+
+## Behavior changes
+
+- **Overrides are always applied** — `factory.generate(3, { authorId })` now includes `authorId`
+  even though it isn't a `@Factory` field (v1 dropped it; this fixes relationship seeding).
+- **`dependsOn` is transitive** and order-independent.
+- **Factory inheritance works** — `extends` a base factory to reuse its fields.
+- **Refresh drops in reverse order**; keep your seeder list parent-first.
+- **`drop()` is optional**.
+- **Deep imports** (`@ackplus/nest-seeder/dist/lib/...`) are gone — import from the package root.
+
+Questions? https://github.com/ack-solutions/nest-seeder/issues

package/QUICKSTART.md

@@ -1,45 +1,41 @@
-# ⚡ Quick Start - 5 Minutes to Seeding!
+# ⚡ Quick Start
 
-Get started with `@ackplus/nest-seeder` in just 5 simple steps.
+Get seeding with `@ackplus/nest-seeder` in a few minutes.
+For the full guide, see **[ack-solutions.github.io/nest-seeder](https://ack-solutions.github.io/nest-seeder/guide/getting-started)**.
 
-## 📦 Installation
+## Install
 
 ```bash
 npm install @ackplus/nest-seeder @faker-js/faker
-npm install -D ts-node typescript
+npm install -D ts-node typescript   # for .ts config files
 ```
 
-## Step 1: Create an Entity
+## Scaffold (fastest)
 
-```typescript
-// src/entities/user.entity.ts
-import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';
-
-@Entity('users')
-export class User {
-  @PrimaryGeneratedColumn()
-  id: number;
+```bash
+npx nest-seed init
+```
 
-  @Column()
-  name: string;
+This creates `seeder.config.ts`, a factory, and a seeder. Point the config at your database, then:
 
-  @Column({ unique: true })
-  email: string;
+```json
+{ "scripts": { "seed": "nest-seed" } }
+```
 
-  @Column({ default: 'user' })
-  role: string;
-}
+```bash
+npm run seed
 ```
 
-## Step 2: Create a Factory
+## Or wire it up by hand
+
+**1. Factory** — `src/database/factories/user.factory.ts`
 
-```typescript
-// src/factories/user.factory.ts
+```ts
 import { Factory } from '@ackplus/nest-seeder';
 
 export class UserFactory {
-  @Factory((faker) => faker.person.fullName())
-  name: string;
+  @Factory((faker) => faker.person.firstName())
+  firstName: string;
 
   @Factory((faker) => faker.internet.email())
   email: string;
@@ -49,175 +45,62 @@ export class UserFactory {
 }
 ```
 
-## Step 3: Create a Seeder
+**2. Seeder** — `src/database/seeders/user.seeder.ts`
 
-```typescript
-// src/seeders/user.seeder.ts
+```ts
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Repository } from 'typeorm';
-import { Seeder, DataFactory } from '@ackplus/nest-seeder';
+import { Seeder, SeederName, DataFactory } from '@ackplus/nest-seeder';
 import { User } from '../entities/user.entity';
 import { UserFactory } from '../factories/user.factory';
 
 @Injectable()
+@SeederName('users')
 export class UserSeeder implements Seeder {
   constructor(
-    @InjectRepository(User)
-    private readonly userRepository: Repository<User>,
+    @InjectRepository(User) private readonly userRepository: Repository<User>,
   ) {}
 
   async seed(): Promise<void> {
-    const factory = DataFactory.createForClass(UserFactory);
-    const users = factory.generate(10);
+    const users = DataFactory.createForClass(UserFactory).generate(10);
     await this.userRepository.save(users);
-    console.log('✅ Seeded 10 users');
   }
 
   async drop(): Promise<void> {
-    await this.userRepository.delete({});
+    await this.userRepository.createQueryBuilder().delete().execute();
   }
 }
 ```
 
-## Step 4: Create Seeder Configuration
+**3. Config** — `seeder.config.ts`
 
-Create `seeder.config.ts` in your **project root**:
-
-> **Note:** The seeder configuration is independent and does not require importing your main `AppModule`.
-
-```typescript
-// seeder.config.ts (in project root)
+```ts
 import { TypeOrmModule } from '@nestjs/typeorm';
-import { ConfigModule, ConfigService } from '@nestjs/config';
-import { User } from './src/entities/user.entity';
-import { UserSeeder } from './src/seeders/user.seeder';
-import * as dotenv from 'dotenv';
-
-dotenv.config();
+import { defineSeederConfig } from '@ackplus/nest-seeder';
+import { User } from './src/database/entities/user.entity';
+import { UserSeeder } from './src/database/seeders/user.seeder';
 
-export default {
+export default defineSeederConfig({
   imports: [
-    ConfigModule.forRoot({
-      isGlobal: true,
-    }),
-    TypeOrmModule.forRootAsync({
-      imports: [ConfigModule],
-      inject: [ConfigService],
-      useFactory: (config: ConfigService) => ({
-        type: 'postgres',
-        host: config.get<string>('DB_HOST'),
-        port: config.get<number>('DB_PORT'),
-        username: config.get<string>('DB_USERNAME'),
-        password: config.get<string>('DB_PASSWORD'),
-        database: config.get<string>('DB_DATABASE'),
-        entities: [User],
-        synchronize: true,
-      }),
-    }),
+    TypeOrmModule.forRoot({ type: 'sqlite', database: 'db.sqlite', entities: [User], synchronize: true }),
     TypeOrmModule.forFeature([User]),
   ],
   seeders: [UserSeeder],
-};
+});
 ```
 
-## Step 5: Add Script & Run
-
-Add to `package.json`:
-
-```json
-{
-  "scripts": {
-    "seed": "node -r ts-node/register -r tsconfig-paths/register ./node_modules/@ackplus/nest-seeder/dist/cli.js -c ./seeder.config.ts",
-    "seed:refresh": "npm run seed -- --refresh"
-  }
-}
-```
-
-Run it:
+**4. Run**
 
 ```bash
-npm run seed
-```
-
-**Output:**
-```
-🌱 Starting NestJS Seeder...
-📁 Loading configuration from: seeder.config.ts
-[Nest] Starting Nest application...
-[Nest] TypeOrmModule dependencies initialized
-✅ Seeded 10 users
+npm run seed              # seed
+npm run seed -- --refresh # drop (reverse order) then reseed
+nest-seed list            # see available seeders
 ```
 
-## 🎉 Success!
-
-You've successfully seeded your database! 
-
-## 📚 Next Steps
-
-### Run with options:
-
-```bash
-# Drop and reseed
-npm run seed:refresh
-
-# Run specific seeder
-npm run seed -- --name UserSeeder
-
-# With dummy data flag
-npm run seed -- --dummyData
-```
-
-### Add More Seeders
-
-1. Create more factories and seeders
-2. Add them to `seeder.config.ts`:
-
-```typescript
-export default {
-  imports: [/* ... */],
-  seeders: [
-    UserSeeder,
-    PostSeeder,
-    CommentSeeder,
-  ],
-};
-```
-
-### Watch Mode for Development
-
-Add to `package.json`:
-
-```json
-{
-  "scripts": {
-    "seed:watch": "nodemon --watch src/seeders --watch src/factories --ext ts --exec \"npm run seed\""
-  }
-}
-```
-
-Run:
-
-```bash
-npm run seed:watch
-```
-
-Now your database will auto-reseed when you modify seeders or factories!
-
-## 💡 Tips
-
-- **Start small**: Begin with one entity, then add more
-- **Use factories**: They make generating data super easy
-- **Order matters**: List seeders in dependency order
-- **Drop method**: Always implement drop() to clear data
-- **Environment variables**: Use them for database config
-
-## 🔗 Resources
-
-- [Full Documentation](./README.md)
-- [Examples Directory](./examples/)
-- [GitHub Repository](https://github.com/ackplus/nest-seeder)
-
----
+## Next steps
 
-Ready to seed! 🌱
+- [Factories](https://ack-solutions.github.io/nest-seeder/guide/factories)
+- [Seeders](https://ack-solutions.github.io/nest-seeder/guide/seeders)
+- [CLI reference](https://ack-solutions.github.io/nest-seeder/guide/cli)
+- [Migration v1 → v2](https://ack-solutions.github.io/nest-seeder/migration)