@flusys/nestjs-core 4.0.2 → 4.1.1

package/README.md

@@ -1,742 +1,642 @@
-# Core Package Guide
+# @flusys/nestjs-core
 
-> **Package:** `@flusys/nestjs-core`
-> **Version:** 4.0.2
-> **Type:** Pure TypeScript foundation (zero NestJS dependencies)
+> Foundation infrastructure for NestJS applications — type-safe environment configuration, TypeORM migration CLI, intelligent data seeding, and modular Swagger documentation.
 
-Foundation layer providing type-safe configuration, database utilities, migration CLI, seeders with intelligent pattern detection, and Swagger setup.
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-core.svg)](https://www.npmjs.com/package/@flusys/nestjs-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
+
+---
 
 ## Table of Contents
 
-- [Package Architecture](#package-architecture)
-- [Environment Configuration](#environment-configuration)
-- [Database Interfaces](#database-interfaces)
-- [Migration System](#migration-system)
+- [Overview](#overview)
+- [Features](#features)
+- [Architecture](#architecture)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Environment Setup](#environment-setup)
+- [Quick Start](#quick-start)
+- [EnvConfigService](#envconfigservice)
+- [Migration CLI](#migration-cli)
+  - [Migration Config File](#migration-config-file)
+  - [CLI Commands](#cli-commands)
+  - [Programmatic API](#programmatic-api)
 - [Seed System](#seed-system)
-- [Field Pattern Detection](#field-pattern-detection)
+  - [BaseSeeder](#baseseeder)
+  - [SeedRunner](#seedrunner)
+  - [DataGenerator](#datagenerator)
+  - [Seed CLI](#seed-cli)
 - [Swagger Documentation](#swagger-documentation)
-- [API Reference](#api-reference)
+  - [setupSwaggerDocs](#setupswaggerdocs)
+  - [setupModuleSwaggerDocs](#setupmoduleswaggerdocs)
+- [Database Utilities](#database-utilities)
+- [Core Interfaces](#core-interfaces)
+- [Injection Tokens & Constants](#injection-tokens--constants)
+- [Multi-Tenant Support](#multi-tenant-support)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
-## Package Architecture
+## Overview
 
-```
-nestjs-core/src/
-├── config/
-│   └── env-config.service.ts       # Environment configuration singleton
-├── constants/
-│   └── database.constants.ts       # MODULE_OPTIONS, DEFAULT_TENANT_HEADER
-├── interfaces/
-│   ├── app-config.interfaces.ts    # IBootstrapAppConfig, IDynamicModuleConfig
-│   ├── base-entity.interface.ts    # IBaseEntity, ISoftDeletable, ITimestampable
-│   ├── database.interface.ts       # IDatabaseConfig, ITenantDatabaseConfig, IDataSourceBuildOptions
-│   └── migration.interface.ts      # IMigrationConfig, IMigrationResult
-├── utils/
-│   └── datasource-config.builder.ts # DataSource utilities
-├── migration/
-│   ├── cli.ts                      # CLI entry point
-│   ├── migration.cli.ts            # Migration CLI commands
-│   ├── datasource.factory.ts       # DataSource factory
-│   └── migration.runner.ts         # Migration execution
-├── seeders/
-│   ├── cli.ts                      # Seed CLI entry point
-│   ├── base-seeder.ts              # Abstract base seeder class
-│   ├── seed-runner.ts              # Seed orchestration
-│   ├── seed-config.ts              # Global seed configuration
-│   ├── entity-reader.ts            # TypeORM metadata extraction
-│   ├── data-generator.ts           # Faker.js data generation
-│   └── field-patterns.ts           # Intelligent field pattern detection
-├── docs/
-│   └── docs.config.ts              # Swagger setup utilities
-└── index.ts
-```
+`@flusys/nestjs-core` is the lowest-level dependency in the FLUSYS NestJS monorepo. Every other package depends on it.
+
+**Key design decision:** This package is **pure TypeScript with zero NestJS runtime dependencies** (except the isolated `docs/` module). The migration and seed CLIs run as standalone Node.js processes — no NestJS app bootstrap required. This makes it usable in CI pipelines, build scripts, and non-NestJS tools.
 
 ---
 
-## Environment Configuration
+## Features
 
-```typescript
-import { envConfig } from '@flusys/nestjs-core/config';
+- **Type-safe environment config** — Strongly typed `process.env` access with restricted key protection and validation
+- **Migration CLI** — Full CLI and programmatic API for TypeORM migrations, including multi-tenant (run-for-all-tenants)
+- **Data seeder** — Metadata-driven test data generation with Faker.js, topological sort for dependency resolution, and custom seeder support
+- **Swagger setup** — Modular API documentation with advanced filtering by tags, schemas, parameters, and examples
+- **DataSource utilities** — TypeORM DataSource configuration builders for single and multi-tenant setups
+- **Core interfaces** — Contract definitions (entities, config, database, migrations) used by all feature modules
+- **SnakeNamingStrategy** — All columns use `snake_case` by default via `typeorm-naming-strategies`
+
+---
+
+## Architecture
+
+```
+@flusys/nestjs-core          ← THIS PACKAGE (pure TypeScript)
+        ↓
+@flusys/nestjs-shared        ← NestJS shared infrastructure
+        ↓
+auth | iam | storage | email | form-builder | event-manager | notification | localization
 ```
 
-### Available Methods
-
-| Method | Description |
-|--------|-------------|
-| `tryGetValue(key, throwOnMissing?)` | Get env value (throws for restricted keys) |
-| `getNumber(key, throwOnMissing?)` | Get env value as number |
-| `getBoolean(key, throwOnMissing?)` | Get env value as boolean |
-| `getPort()` | Get PORT (default: 3000) |
-| `isProduction()` | Check if MODE !== 'DEV' |
-| `getFrontendUrl()` | Get FRONTEND_URL |
-| `getOrigins()` | Get ALLOW_ORIGINS as comma-separated array |
-| `getTypeOrmConfig()` | Get database config |
-| `getJwtConfig()` | Get JWT config (secret, expiration, refreshSecret, refreshExpiration) |
-| `getRedisUrl()` | Get Redis connection URL (default: redis://localhost:6379) |
-| `getMailConfig()` | Get mail configuration (MAIL_FROM, MAIL_APP_PASSWORD) |
-| `getTenantId()` | Get TENANT_ID |
-| `useTenantMode()` | Check USE_TENANT_MODE |
-| `getLogConfig()` | Get logging config `{ dir, level, maxSize, maxFiles }` |
-| `getEnv()` | Get all env vars as `Record<string, string>` |
+`nestjs-core` is the only FLUSYS package with no upstream FLUSYS dependencies. All other packages depend on it.
 
-### Restricted Keys
+---
 
-The following keys require using specific methods (prevents misuse):
+## Compatibility
 
-| Key | Use Instead |
-|-----|-------------|
-| `FRONTEND_URL` | `getFrontendUrl()` |
-| `ALLOW_ORIGINS` | `getOrigins()` |
-| `PORT` | `getPort()` |
-| `MODE` | `isProduction()` |
-| `DB_HOST/PORT/USER/PASSWORD` | `getTypeOrmConfig()` |
+| Package | Version |
+|---------|---------|
+| `typeorm` | `^0.3.0` |
+| `typeorm-naming-strategies` | `^4.1.0` |
+| `@faker-js/faker` | `^8.0.0` |
+| `dotenv` | `^16.0.0` |
+| `@nestjs/common` | `^11.0.0` *(docs/ only)* |
+| `@nestjs/swagger` | `^8.0.0` *(docs/ only)* |
+| Node.js | `>= 18.x` |
+| TypeScript | `>= 5.0` |
 
 ---
 
-## Database Interfaces
+## Installation
 
-### Core Interfaces
+```bash
+npm install @flusys/nestjs-core
+```
 
-```typescript
-type DatabaseType = 'mysql' | 'postgres' | 'mariadb' | 'sqlite' | 'mssql';
-type DatabaseMode = 'single' | 'multi-tenant';
+```bash
+# Peer dependencies
+npm install typeorm typeorm-naming-strategies @faker-js/faker dotenv
 
-interface IDatabaseConfig {
-  type: DatabaseType;
-  host?: string;
-  port?: number;
-  username?: string;
-  password?: string;
-  database?: string;
-}
+# For migration and seed CLIs
+npm install -D ts-node tsconfig-paths
 
-interface ITenantDatabaseConfig {
-  id: string;
-  database: string;
-  name?: string;
-  host?: string;
-  port?: number;
-  username?: string;
-  password?: string;
-  enableCompanyFeature?: boolean;
-  enableEmailVerification?: boolean;
-  permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
-}
+# For Swagger (docs/ module only)
+npm install @nestjs/common @nestjs/swagger
+```
 
-interface IBootstrapAppConfig {
-  databaseMode: 'single' | 'multi-tenant';
-  enableCompanyFeature: boolean;
-  permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
-  enableEmailVerification?: boolean;
-}
+---
 
-interface IDataSourceBuildOptions {
-  type: string;
-  host?: string;
-  port?: number;
-  username?: string;
-  password?: string;
-  database: string;
-  entities: any[];
-  migrations: string[];
-  migrationsTableName: string;
-  synchronize: boolean;
-  namingStrategy?: any;
-}
+## Environment Setup
+
+Create a `.env` file in your project root:
+
+```env
+PORT=2002
+MODE=dev
+FRONTEND_URL=http://localhost:2001
+ALLOW_ORIGINS=http://localhost:2001,http://localhost:3000
+
+# Database
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=password
+DB_NAME=myapp
+
+# JWT
+JWT_SECRET=your-jwt-secret-min-32-chars
+JWT_EXPIRATION=15m
+REFRESH_TOKEN_SECRET=your-refresh-secret
+REFRESH_TOKEN_EXPIRATION=7d
+
+# Cache
+REDIS_URL=redis://localhost:6379
+
+# Email
+MAIL_FROM=noreply@example.com
+MAIL_APP_PASSWORD=app-password
+
+# Multi-tenant (optional)
+TENANT_ID=
+USE_TENANT_MODE=false
+
+# Logging
+LOG_DIR=logs
+LOG_LEVEL=debug
+LOG_MAX_SIZE=20m
+LOG_MAX_FILES=14d
+DISABLE_HTTP_LOGGING=false
 ```
 
-### Entity Interfaces
+---
 
-```typescript
-interface IBaseEntity {
-  id: string;
-  createdAt: Date;
-  updatedAt: Date;
-  deletedAt?: Date | null;
-}
+## Quick Start
 
-interface ISoftDeletable {
-  deletedAt?: Date | null;
-}
+### Environment Config
 
-interface ITimestampable {
-  createdAt: Date;
-  updatedAt: Date;
-}
+```typescript
+import { envConfig } from '@flusys/nestjs-core';
+
+const port       = envConfig.getPort();           // number (default: 3000)
+const isProd     = envConfig.isProduction();       // boolean
+const db         = envConfig.getTypeOrmConfig();   // { host, port, username, password }
+const jwt        = envConfig.getJwtConfig();       // { secret, expiration, refreshSecret, refreshExpiration }
+const origins    = envConfig.getOrigins();         // string[] from ALLOW_ORIGINS
+const redis      = envConfig.getRedisUrl();        // string
+const mail       = envConfig.getMailConfig();      // { MAIL_FROM, MAIL_APP_PASSWORD }
+const logConfig  = envConfig.getLogConfig();       // { dir, level, maxSize, maxFiles, disableHttpLogging }
+const tenantId   = envConfig.getTenantId();        // string | null
+const multiTenant = envConfig.useTenantMode();     // boolean
+
+// Custom variable (throws if missing when throwOnMissing: true)
+const myVar = envConfig.tryGetValue('MY_CUSTOM_VAR', true);
+```
 
-interface IOrderable {
-  serial?: number | null;
+### Add Migration Scripts to package.json
+
+```json
+{
+  "scripts": {
+    "migration:generate": "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/migration/cli generate",
+    "migration:run":      "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/migration/cli run",
+    "migration:revert":   "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/migration/cli revert",
+    "migration:status":   "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/migration/cli status",
+    "migration:run:all":  "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/migration/cli run:all",
+    "seed:run":           "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/seeders/cli run",
+    "seed:clear":         "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/seeders/cli clear",
+    "seed:status":        "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/seeders/cli status"
+  }
 }
+```
 
-interface IMetadata {
-  metadata?: Record<string, any> | null;
-}
+### Setup Swagger
 
-interface ICompanyOwned {
-  companyId?: string | null;
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { setupSwaggerDocs } from '@flusys/nestjs-core/docs';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  setupSwaggerDocs(app, { title: 'My API', version: '1.0' });
+  await app.listen(3000);
 }
 ```
 
 ---
 
-## Migration System
+## EnvConfigService
 
-### CLI Commands
+A singleton pre-instantiated as `envConfig`. Loads `.env` on import via `dotenv`.
 
-```bash
-npm run migration:generate -- -n CreateUsers    # Generate migration
-npm run migration:run                           # Run pending migrations
-npm run migration:revert                        # Revert last migration
-npm run migration:status                        # Show migration status
-TENANT_ID=tenant1 npm run migration:run         # Specific tenant
-npm run migration:run:all                       # All tenants
-npm run migration:revert:all                    # Revert all tenants
-npm run migration:status:all                    # Status all tenants
-```
+### Restricted Keys
+
+The following keys cannot be accessed via `tryGetValue()` — use their dedicated typed methods instead:
+
+`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `JWT_SECRET`, `JWT_EXPIRATION`, `REFRESH_TOKEN_SECRET`, `REFRESH_TOKEN_EXPIRATION`, `MAIL_FROM`, `MAIL_APP_PASSWORD`, `REDIS_URL`
+
+### Method Reference
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `tryGetValue(key, throwOnMissing?)` | `string` | Get any non-restricted env var |
+| `getNumber(key, throwOnMissing?)` | `number` | Get env var as number |
+| `getBoolean(key, throwOnMissing?)` | `boolean` | Get env var as boolean |
+| `getPort()` | `number` | `PORT` (default: 3000) |
+| `isProduction()` | `boolean` | `MODE !== 'DEV'` (case-insensitive) |
+| `getFrontendUrl()` | `string` | `FRONTEND_URL` |
+| `getOrigins()` | `string[]` | `ALLOW_ORIGINS` split by comma |
+| `getTypeOrmConfig()` | `IDatabaseConfig` | DB connection config |
+| `getJwtConfig()` | `IJwtConfig` | JWT secrets and expirations |
+| `getRedisUrl()` | `string` | `REDIS_URL` (default: `redis://localhost:6379`) |
+| `getMailConfig()` | `IMailConfig` | `MAIL_FROM`, `MAIL_APP_PASSWORD` |
+| `getTenantId()` | `string \| null` | `TENANT_ID` or null |
+| `useTenantMode()` | `boolean` | `USE_TENANT_MODE` |
+| `getLogConfig()` | `ILogConfig` | Logging configuration |
+| `getEnv()` | `Record<string, string>` | Full `process.env` snapshot |
+
+---
 
-### Migration Configuration
+## Migration CLI
+
+### Migration Config File
+
+Create `migration.config.ts` in your project root:
 
 ```typescript
 import { IMigrationConfig } from '@flusys/nestjs-core';
+import { AuthModule } from '@flusys/nestjs-auth';
+import { IAMModule } from '@flusys/nestjs-iam';
 
-const migrationConfig: IMigrationConfig = {
+const config: IMigrationConfig = {
   defaultDatabaseConfig: {
     type: 'postgres',
-    host: 'localhost',
-    port: 5432,
-    username: 'user',
-    password: 'password',
-    database: 'app_db',
-  },
-  bootstrapAppConfig: {
-    databaseMode: 'multi-tenant',
-    enableCompanyFeature: true,
+    host: process.env.DB_HOST ?? 'localhost',
+    port: Number(process.env.DB_PORT ?? 5432),
+    username: process.env.DB_USER ?? 'postgres',
+    password: process.env.DB_PASSWORD ?? '',
+    database: process.env.DB_NAME ?? 'myapp',
   },
-  tenants: [
-    { id: 'tenant1', database: 'tenant1_db' },
-    { id: 'tenant2', database: 'tenant2_db', host: 'different-server.com' },
+  entities: [
+    ...AuthModule.getEntities({ enableCompanyFeature: true, enableEmailVerification: true }),
+    ...IAMModule.getEntities({ enableCompanyFeature: true, permissionMode: 'FULL' }),
+    // ... other module entities
   ],
-  migrationsPath: './src/persistence/migrations',
-  entities: (tenantConfig) => {
-    // Dynamic entity resolution per tenant
-    return tenantConfig?.enableCompanyFeature
-      ? [UserWithCompany, RoleWithCompany]
-      : [User, Role];
-  },
-  migrationsTableName: 'typeorm_migrations',
+  migrationsPath: 'src/migrations',
+  migrationsTableName: 'migrations',
 };
+
+export default config;
 ```
 
-### Core Functions
+### CLI Commands
+
+```bash
+# Generate a new migration (compares entities to current DB schema)
+npm run migration:generate -- -n CreateUsersTable
+
+# Run all pending migrations
+npm run migration:run
+
+# Revert the last applied migration
+npm run migration:revert
+
+# Show migration status (which are applied, which are pending)
+npm run migration:status
+
+# Multi-tenant: run migrations for all tenants
+npm run migration:run:all
+```
+
+### Programmatic API
 
 ```typescript
 import {
-  generateMigration,
+  createMigrationDataSource,
   runMigrations,
   revertMigration,
   migrationStatus,
+  generateMigration,
   runForAllTenants,
-  createMigrationDataSource,
-} from '@flusys/nestjs-core/migration';
+} from '@flusys/nestjs-core';
 
-// Generate new migration
-await generateMigration(config, 'CreateUsersTable', tenantId?);
+// Create a DataSource for migration operations
+const dataSource = await createMigrationDataSource(config, tenantId);
 
 // Run pending migrations
-const result: IMigrationResult = await runMigrations(config, tenantId?);
+await runMigrations(dataSource);
 
 // Revert last migration
-const result: IMigrationResult = await revertMigration(config, tenantId?);
+await revertMigration(dataSource);
 
 // Check status
-await migrationStatus(config, tenantId?);
+const status = await migrationStatus(dataSource);
+
+// Generate a new migration file
+await generateMigration(config, 'MigrationName');
 
-// Multi-tenant operations
-const results: IMigrationResult[] = await runForAllTenants(config, 'run');
+// Multi-tenant: run for all configured tenants
+await runForAllTenants(config, runMigrations);
 ```
 
 ---
 
 ## Seed System
 
-### CLI Commands
-
-```bash
-npm run seed:run                                # Seed all entities
-npm run seed:run -- --entity=User --count=100   # Specific entity
-npm run seed:run -- --count=50 --clear          # Clear before seeding
-npm run seed:clear                              # Clear all data
-npm run seed:clear -- --hard                    # Hard delete
-npm run seed:status                             # Show status
-npm run seed:run:all                            # Multi-tenant
-```
-
-### Seed Configuration
-
-```typescript
-import { configureSeedConfig, seedConfig, ISeedConfig } from '@flusys/nestjs-core/seeders';
-
-interface ISeedConfig {
-  counts: Record<string, number>;      // Per-entity counts
-  order: string[];                     // Preferred seeding order
-  skipEntities: string[];              // Entities to skip
-  locale: string;                      // Faker locale
-  respectSoftDelete: boolean;          // Default clear behavior
-}
-
-// Configure before running seeders
-configureSeedConfig({
-  counts: { User: 50, Product: 100, Order: 200 },
-  order: ['User', 'Company', 'Product', 'Order'],
-  skipEntities: ['migrations', 'typeorm_metadata', 'Migration'],
-  locale: 'en',
-  respectSoftDelete: true,
-});
-```
-
-### SeedRunner
-
-The main orchestrator for seed operations:
-
-```typescript
-import { SeedRunner, ISeedOptions, ISeedResult } from '@flusys/nestjs-core/seeders';
-
-const runner = new SeedRunner(dataSource, logger?);
-
-// Custom seeder management
-runner.registerCustomSeeder('User', new UserSeeder(dataSource));  // Register
-runner.unregisterCustomSeeder('User');                             // Unregister
-runner.hasCustomSeeder('User');                                    // Check: boolean
-
-// Run all entities in dependency order
-const results: ISeedResult[] = await runner.runAll({
-  count: 50,               // Records per entity
-  clear: true,             // Clear before seeding
-  entity: 'User',          // Seed specific entity only
-  respectSoftDelete: true, // Use soft delete when clearing
-  skipIfExists: false,     // Skip if data exists
-  dryRun: false,           // Preview without executing
-  continueOnError: true,   // Continue on failures
-  batchSize: 1000,         // Batch size for bulk inserts
-  onProgress: (current, total, entity) => { },
-});
-
-// Run single entity
-const result: ISeedResult = await runner.runSingle('User', options);
-
-// Clear all data (reverse dependency order)
-const results = await runner.clearAll(hard?, continueOnError?);
+### BaseSeeder
 
-// Get status
-const status = await runner.getStatus();
-// Returns: [{ entity, tableName, count, isEmpty, hasSoftDelete }]
-```
-
-### Custom Seeders
-
-Extend `BaseSeeder<T>` for entity-specific seeding logic:
+Extend `BaseSeeder` to create custom seeders:
 
 ```typescript
-import { BaseSeeder, DataGenerator } from '@flusys/nestjs-core/seeders';
-
-// BaseSeeder provides:
-// - repository: Repository<T>     - TypeORM repository
-// - metadata: EntityMetadata      - Entity metadata
-// - generate(count): Promise<T[]> - Abstract (must implement)
-// - clear(hard?): Promise<void>   - Clear entity data
-// - count(includeDeleted?): Promise<number>
-// - isEmpty(): Promise<boolean>
-// - getEntityName(): string
-// - withTransaction(fn): Promise<R>
-
-class UserSeeder extends BaseSeeder<User> {
-  private generator: DataGenerator;
-
-  constructor(ds: DataSource) {
-    super(ds, User);
-    this.generator = new DataGenerator('en');
+import { BaseSeeder, SeedRunner } from '@flusys/nestjs-core';
+import { DataSource } from 'typeorm';
+
+export class UserSeeder extends BaseSeeder {
+  name = 'UserSeeder';
+  order = 1; // Lower runs first (topological sort by dependencies)
+  dependencies = []; // Seeder names this depends on
+
+  async run(dataSource: DataSource): Promise<void> {
+    const repo = dataSource.getRepository(User);
+    await repo.save([
+      { email: 'admin@example.com', name: 'Admin User' },
+    ]);
   }
 
-  async generate(count: number): Promise<User[]> {
-    const users: User[] = [];
-    for (let i = 0; i < count; i++) {
-      users.push(this.repository.create({
-        email: faker.internet.email(),
-        name: faker.person.fullName(),
-        password: await bcrypt.hash('password123', 12),
-      }));
-    }
-    return this.repository.save(users);
+  async clear(dataSource: DataSource): Promise<void> {
+    await dataSource.getRepository(User).delete({});
   }
 }
-
-// Register before running
-const runner = new SeedRunner(dataSource);
-runner.registerCustomSeeder('User', new UserSeeder(dataSource));
-await runner.runAll({ count: 50, clear: true });
 ```
 
-### Seeder Interfaces
+### SeedRunner
 
 ```typescript
-interface ISeedResult {
-  entity: string;
-  success: boolean;
-  count: number;
-  error?: string;
-  dryRun?: boolean;
-  skipped?: boolean;
-}
+import { SeedRunner, seedConfig } from '@flusys/nestjs-core';
 
-interface IEntityInfo {
-  name: string;
-  tableName: string;
-  columns: IColumnInfo[];
-  relations: IRelationInfo[];
-  hasSoftDelete: boolean;
-  hasCompany: boolean;
-}
+// Register seeders
+seedConfig.register([UserSeeder, RoleSeeder, PermissionSeeder]);
 
-interface IColumnInfo {
-  name: string;
-  propertyName: string;
-  type: string;
-  length?: number | string;
-  isNullable: boolean;
-  isUnique: boolean;
-  isPrimary: boolean;
-  isGenerated: boolean;
-  default?: any;
-  enum?: any[];
-  precision?: number;
-  scale?: number;
-}
+// Run all seeders (respects order and dependencies)
+const runner = new SeedRunner(dataSource);
+const result = await runner.run();
+console.log(`Seeded ${result.count} records`);
 
-interface IRelationInfo {
-  propertyName: string;
-  type: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
-  targetEntity: string;
-  isNullable: boolean;
-  joinColumnName?: string;
-}
+// Clear all seeded data (in reverse order)
+await runner.clear();
+
+// Check seeder status
+const status = await runner.status();
 ```
 
-### EntityReader
+### DataGenerator
 
-Extracts TypeORM metadata for intelligent seeding:
+Generates realistic test data from TypeORM entity metadata using Faker.js:
 
 ```typescript
-import { EntityReader, IEntityInfo, IColumnInfo } from '@flusys/nestjs-core/seeders';
-
-const reader = new EntityReader(dataSource);
-
-// Get all entities
-const entities = reader.getAllEntities();
+import { DataGenerator } from '@flusys/nestjs-core';
 
-// Get detailed entity info
-const info: IEntityInfo = reader.getEntityInfo('User');
+const generator = new DataGenerator(dataSource);
 
-// Get seeding order (topological sort by FK dependencies)
-const order: string[] = reader.getSeedingOrder(skipEntities?);
-// Independent entities first, then dependents
+// Auto-detect field types and generate appropriate data
+const fakeUser = generator.generate(User, {
+  overrides: { email: 'specific@email.com' },
+  count: 10, // generate 10 records
+});
 ```
 
-### DataGenerator
+**Automatic field pattern detection:**
 
-Generates realistic sample data using Faker.js:
+| Pattern | Generated value |
+|---------|----------------|
+| `email` | `faker.internet.email()` |
+| `name`, `title` | `faker.person.fullName()` |
+| `phone` | `faker.phone.number()` |
+| `address` | `faker.location.streetAddress()` |
+| `url`, `website` | `faker.internet.url()` |
+| `description`, `text` | `faker.lorem.paragraph()` |
+| `slug` | `faker.helpers.slugify()` |
+| `uuid`, `id` | `faker.string.uuid()` |
+| `boolean`, `isActive` | `faker.datatype.boolean()` |
+| `date`, `createdAt` | `faker.date.recent()` |
+| `number`, `price` | `faker.number.int()` |
 
-```typescript
-import { DataGenerator, IColumnInfo } from '@flusys/nestjs-core/seeders';
+### Seed CLI
 
-const generator = new DataGenerator('en');
-
-// Generate value for a column
-const value = generator.generateValue(columnInfo);
+```bash
+# Run all seeders
+npm run seed:run
 
-// Generate complete entity
-const entity = generator.generateEntity(columns);
+# Clear all seeded data
+npm run seed:clear
 
-// Relation helpers
-const relatedId = generator.generateRelationId(relatedEntities);
-const relatedIds = generator.generateRelationIds(relatedEntities, min?, max?);
+# Show seeder status
+npm run seed:status
 ```
 
 ---
 
-## Field Pattern Detection
+## Swagger Documentation
 
-Intelligent field pattern detection for realistic data generation.
+### setupSwaggerDocs
 
-### Supported Patterns
+Sets up a single global Swagger UI for the whole application:
 
 ```typescript
-import { detectFieldPattern } from '@flusys/nestjs-core/seeders';
-
-// Pattern detection returns one of 30 patterns:
-type FieldPatternType =
-  | 'skip'           // System fields (id, createdAt, etc.)
-  | 'null'           // Audit fields (createdById, etc.)
-  | 'boolean'        // Boolean fields with keywords
-  | 'token'          // Token fields
-  | 'firstName' | 'lastName' | 'fullName'
-  | 'email' | 'phone'
-  | 'address' | 'street' | 'city' | 'state' | 'country' | 'zipCode'
-  | 'url' | 'domain' | 'slug'
-  | 'description' | 'summary' | 'content' | 'title'
-  | 'username' | 'password'
-  | 'birthdate' | 'futureDate' | 'recentDateOrNull'
-  | 'serial' | 'company'
-  | 'emailProvider'   // smtp, sendgrid, mailgun, ses, postmark
-  | 'formAccessType'; // public, authenticated, permission
-
-// Detect pattern for a column
-const pattern = detectFieldPattern(column);
+import { setupSwaggerDocs } from '@flusys/nestjs-core/docs';
+
+setupSwaggerDocs(app, {
+  title: 'My API',
+  description: 'API documentation',
+  version: '1.0.0',
+  path: 'api/docs',           // default: 'api/docs'
+  bearerAuthEnabled: true,    // default: true
+  persistAuthorization: true, // default: true
+});
 ```
 
-### System Fields
+### setupModuleSwaggerDocs
 
-Automatically handled fields (public API exports `SYSTEM_FIELDS` only):
+Sets up module-scoped Swagger documentation at separate URLs — one per feature module:
 
 ```typescript
-import { SYSTEM_FIELDS, isSystemField } from '@flusys/nestjs-core/seeders';
-
-// Exported constant
-SYSTEM_FIELDS = ['id', 'createdAt', 'updatedAt', 'deletedAt', 'createdById', 'updatedById', 'deletedById'];
+import { setupModuleSwaggerDocs } from '@flusys/nestjs-core/docs';
 
-// Check if a field is a system field
-isSystemField('createdAt'); // true
-
-// Internal constants (not exported, for reference only):
-// AUDIT_FIELDS = ['createdbyid', 'updatedbyid', 'deletedbyid'];
-// IDENTITY_FIELDS = ['id', 'createdat', 'updatedat', 'deletedat'];
-// BOOLEAN_KEYWORDS = ['verified', 'active', 'enabled', 'public', 'readonly', 'valid'];
+setupModuleSwaggerDocs(app, [
+  {
+    title: 'Authentication API',
+    description: 'Auth endpoints',
+    version: '1.0.0',
+    path: 'api/docs/auth',
+    includeTags: ['Authentication', 'Users', 'Companies'],
+  },
+  {
+    title: 'IAM API',
+    description: 'Permissions and roles',
+    version: '1.0.0',
+    path: 'api/docs/iam',
+    includeTags: ['Roles', 'Actions', 'Permissions'],
+  },
+  {
+    title: 'Storage API',
+    description: 'File management',
+    version: '1.0.0',
+    path: 'api/docs/storage',
+    includeTags: ['Files', 'Folders'],
+  },
+]);
 ```
 
-### Type Category Detection
+### IModuleSwaggerOptions
 
 ```typescript
-import { detectTypeCategory } from '@flusys/nestjs-core/seeders';
-
-// Categorize database type
-const category = detectTypeCategory('varchar'); // 'string'
-// Categories: string | integer | decimal | boolean | date | timestamp | time | uuid | json | array | unknown
-
-// Internal utility (not exported): getStringLengthCategory()
-// String length categorization:
-// ≤ 50 chars → 'word'
-// ≤ 255 chars → 'sentence'
-// > 255 chars → 'paragraph'
+interface IModuleSwaggerOptions {
+  title: string;
+  description?: string;
+  version?: string;
+  path: string;
+  includeTags?: string[];       // Whitelist specific controller tags
+  excludeTags?: string[];       // Blacklist specific controller tags
+  includeSchemas?: string[];    // Whitelist specific DTO schemas
+  excludeSchemas?: string[];    // Blacklist specific DTO schemas
+  bearerAuthEnabled?: boolean;
+  persistAuthorization?: boolean;
+}
 ```
 
 ---
 
-## Swagger Documentation
-
-### Setup Functions
+## Database Utilities
 
 ```typescript
-import { setupSwaggerDocs, setupModuleSwaggerDocs, IModuleSwaggerOptions } from '@flusys/nestjs-core/docs';
+import { buildDataSourceOptions, getMigrationsFolderPath, getActiveTenants } from '@flusys/nestjs-core';
+
+// Build a TypeORM DataSourceOptions object
+const options = buildDataSourceOptions({
+  config: databaseConfig,
+  entities: [...authEntities, ...iamEntities],
+  migrationsPath: 'src/migrations',
+  migrationsTableName: 'migrations',
+});
 
-// Variadic API for multiple configs
-setupSwaggerDocs(app, authConfig, adminConfig, iamConfig);
+// Get migrations folder path (supports tenant-specific subdirectories)
+const migrationsPath = getMigrationsFolderPath('src/migrations', 'tenant-1');
 
-// Array API for module docs
-setupModuleSwaggerDocs(app, [
-  { title: 'Auth API', path: 'auth/docs', bearerAuth: true },
-  { title: 'Admin API', path: 'admin/docs', excludeTags: ['public'] },
-]);
+// Get all active tenant configs
+const tenants = getActiveTenants(migrationConfig);
 ```
 
-### Configuration Options
+---
+
+## Core Interfaces
+
+These interfaces are used as contracts across all FLUSYS feature modules:
 
 ```typescript
-interface IModuleSwaggerOptions {
-  modules?: Type<unknown>[];              // Include specific modules
-  title: string;
-  description: string;
-  version?: string;                       // Default: '1.0'
-  path: string;                           // Swagger UI path
-  bearerAuth?: boolean;                   // Add JWT auth
-  globalHeaders?: ISwaggerGlobalHeader[];
-  excludeTags?: string[];                 // Hide endpoints by tag
-  excludeSchemaProperties?: ISchemaPropertyExclusion[];
-  excludeQueryParameters?: IQueryParameterExclusion[];
-  excludeExamples?: IExampleExclusion[];
-}
+// Entity contracts
+interface IIdentity { id: string; createdAt: Date; updatedAt: Date; deletedAt?: Date | null; }
 
-interface ISchemaPropertyExclusion {
-  schemaName: string;
-  properties: string[];
+// Bootstrap configuration (fixed at startup)
+interface IBootstrapAppConfig {
+  databaseMode: 'single' | 'multi-tenant';
+  enableCompanyFeature: boolean;
+  enableEmailVerification?: boolean;
+  permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
 }
 
-interface IQueryParameterExclusion {
-  pathPattern: string;   // Supports wildcards: /iam/permissions/*
-  method?: string;       // Optional: 'post', 'get', etc.
-  parameters: string[];
+// DataSource configuration
+interface IDatabaseConfig {
+  type: 'postgres' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql';
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  database: string;
 }
 
-interface ISwaggerGlobalHeader {
-  name: string;
-  description: string;
-  required?: boolean;
-  example?: string;
+// Multi-tenant config
+interface ITenantDatabaseConfig extends IDatabaseConfig { id: string; }
+
+// Module options for dynamic modules
+interface IDynamicModuleConfig {
+  global?: boolean;
+  includeController?: boolean;
 }
 
-interface IExampleExclusion {
-  pathPattern: string;   // Supports wildcards: /auth/*
-  method?: string;       // Optional: 'post', 'get', etc.
-  examples: string[];    // Example names to exclude
+// DataSource service options (base for all module configs)
+interface IDataSourceServiceOptions {
+  defaultDatabaseConfig?: IDatabaseConfig;
+  tenantDefaultDatabaseConfig?: IDatabaseConfig;
+  tenants?: ITenantDatabaseConfig[];
 }
 ```
 
-### Conditional Schema Exclusion
+---
+
+## Injection Tokens & Constants
 
 ```typescript
-setupModuleSwaggerDocs(app, [{
-  title: 'Auth API',
-  path: 'auth/docs',
-  bearerAuth: true,
-  excludeSchemaProperties: enableCompanyFeature ? undefined : [
-    { schemaName: 'LoginResponseDto', properties: ['company', 'branch'] },
-    { schemaName: 'UserDto', properties: ['companyId'] },
-  ],
-  excludeTags: enableCompanyFeature ? undefined : ['Companies', 'Branches'],
-}]);
+import {
+  MIGRATION_CONFIG_TOKEN,
+  SEED_CONFIG_TOKEN,
+  DATASOURCE_TOKEN,
+} from '@flusys/nestjs-core';
 ```
 
 ---
 
-## API Reference
+## Multi-Tenant Support
 
-### Interfaces
+`nestjs-core` provides the foundation for multi-tenant architectures:
 
 ```typescript
-import {
-  // Database
-  IDatabaseConfig,
-  ITenantDatabaseConfig,
-  IDataSourceBuildOptions,
-  // App Config
-  IBootstrapAppConfig,
-  IDynamicModuleConfig,
-  IDataSourceServiceOptions,
-  IModuleOptionsFactory,
-  IAsyncModuleOptions,
-  // Migration
-  IMigrationConfig,
-  IMigrationResult,
-  EntityResolver,
-  // Entity Contracts
-  IBaseEntity,
-  ISoftDeletable,
-  ITimestampable,
-  IOrderable,
-  ICompanyOwned,
-  IMetadata,
-} from '@flusys/nestjs-core';
-```
+import { buildDataSourceOptions, getDatabaseForTenant, getActiveTenants } from '@flusys/nestjs-core';
 
-### Constants
+// Get database config for a specific tenant
+const tenantDb = getDatabaseForTenant(migrationConfig, 'tenant-id');
 
-```typescript
-import { MODULE_OPTIONS, DEFAULT_TENANT_HEADER } from '@flusys/nestjs-core';
+// Build a DataSource for that tenant
+const dsOptions = buildDataSourceOptions({
+  config: tenantDb,
+  entities: [...allEntities],
+  migrationsPath: getMigrationsFolderPath('src/migrations', 'tenant-id'),
+});
+
+// Run migrations for all configured tenants
+await runForAllTenants(migrationConfig, async (dataSource) => {
+  await runMigrations(dataSource);
+});
 ```
 
-### Config
+---
 
-```typescript
-import { envConfig } from '@flusys/nestjs-core/config';
-```
+## Troubleshooting
 
-### Utils
+**`Cannot find migration config file`**
 
-```typescript
-import {
-  buildDataSourceOptions,
-  getDatabaseForTenant,
-  resolveEntities,
-  getActiveTenants,
-  getMigrationsFolderPath,
-  getMigrationsGlobPattern,
-} from '@flusys/nestjs-core/utils';
-```
+Ensure `migration.config.ts` exists at the project root and exports a default `IMigrationConfig` object. The CLI looks for it relative to the current working directory.
 
-### Migration
+---
 
-```typescript
-import {
-  createMigrationDataSource,
-  initializeDataSource,
-  runMigrationCli,
-  generateMigration,
-  runMigrations,
-  revertMigration,
-  migrationStatus,
-  runForAllTenants,
-  ensureMigrationsFolder,
-} from '@flusys/nestjs-core/migration';
-```
+**`RESTRICTED_KEY` error from `tryGetValue`**
 
-### Seeders
+You are trying to access a sensitive key (DB credentials, JWT secrets) via the generic accessor. Use the typed method instead:
 
 ```typescript
-import {
-  // Classes
-  BaseSeeder,
-  SeedRunner,
-  EntityReader,
-  DataGenerator,
-  // Interfaces
-  ISeedResult,
-  ISeedOptions,
-  ISeederLogger,
-  IEntityInfo,
-  IColumnInfo,
-  IRelationInfo,
-  ISeedConfig,
-  // Functions
-  defaultLogger,
-  seedConfig,
-  configureSeedConfig,
-  runSeedCli,
-  getEntityCount,
-  shouldSkipEntity,
-  getSeedingOrder,
-  // Field pattern functions
-  detectFieldPattern,
-  detectTypeCategory,
-  isSystemField,
-  // Constants
-  SYSTEM_FIELDS,
-} from '@flusys/nestjs-core/seeders';
+// Wrong
+envConfig.tryGetValue('JWT_SECRET')   // throws RestrictedKeyError
+
+// Correct
+envConfig.getJwtConfig().secret
 ```
 
-> **Note:** The following are internal utilities in `field-patterns.ts` not exported from the public API: `FieldPatternType` (type), `ColumnTypeCategory` (type), `AUDIT_FIELDS`, `IDENTITY_FIELDS`, `BOOLEAN_KEYWORDS`, `getStringLengthCategory`, `getTokenLength`.
+---
+
+**`SnakeNamingStrategy` column name mismatch**
 
-### Swagger
+All columns use `snake_case` by default. A TypeScript property `createdAt` maps to column `created_at`. If your existing schema uses camelCase, override the naming strategy in `buildDataSourceOptions`.
+
+---
+
+**Seeder runs out of order**
+
+Set explicit `order` numbers or use `dependencies` to declare which seeders must run before yours:
 
 ```typescript
-import {
-  setupSwaggerDocs,
-  setupModuleSwaggerDocs,
-  IModuleSwaggerOptions,
-  ISchemaPropertyExclusion,
-  IQueryParameterExclusion,
-  ISwaggerGlobalHeader,
-  IExampleExclusion,
-} from '@flusys/nestjs-core/docs';
+export class ProductSeeder extends BaseSeeder {
+  name = 'ProductSeeder';
+  dependencies = ['CategorySeeder']; // CategorySeeder must run first
+}
 ```
 
 ---
 
-## Dependencies
+## License
 
-- `dotenv` - Environment variable loading
-- `typeorm` - Migration/seeder utilities (DataSource, EntityMetadata)
-- `@faker-js/faker` - Seed data generation
-- `@nestjs/common`, `@nestjs/swagger` - Swagger documentation setup only
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-25
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-core",
-  "version": "4.0.2",
+  "version": "4.1.1",
   "description": "Core types, interfaces, and constants for Flusys NestJS packages",
   "main": "cjs/index.js",
   "module": "fesm/index.js",