@flusys/nestjs-core 1.1.0-beta → 1.1.0

package/README.md

@@ -1,70 +1,126 @@
 # Core Package Guide
 
 > **Package:** `@flusys/nestjs-core`
-> **Type:** Pure TypeScript utilities (Zero NestJS dependencies)
+> **Version:** 1.1.0
+> **Type:** Pure TypeScript foundation (zero NestJS dependencies)
 
-Foundation layer providing type-safe configuration, database utilities, migration CLI, seeders, and Swagger setup.
+Foundation layer providing type-safe configuration, database utilities, migration CLI, seeders with intelligent pattern detection, and Swagger setup.
+
+## Table of Contents
+
+- [Package Architecture](#package-architecture)
+- [Environment Configuration](#environment-configuration)
+- [Database Interfaces](#database-interfaces)
+- [Migration System](#migration-system)
+- [Seed System](#seed-system)
+- [Field Pattern Detection](#field-pattern-detection)
+- [Swagger Documentation](#swagger-documentation)
+- [API Reference](#api-reference)
+
+---
 
 ## Package Architecture
 
 ```
 nestjs-core/src/
 ├── config/
-│   └── env-config.service.ts    # Environment configuration singleton
+│   └── env-config.service.ts       # Environment configuration singleton
 ├── constants/
-│   └── database.constants.ts    # MODULE_OPTIONS, DEFAULT_TENANT_HEADER
+│   └── 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
-│   └── migration.interface.ts   # IMigrationConfig, IMigrationResult
+│   ├── app-config.interfaces.ts    # IBootstrapAppConfig, IDynamicModuleConfig
+│   ├── base-entity.interface.ts    # IBaseEntity, ISoftDeletable, ITimestampable
+│   ├── database.interface.ts       # IDatabaseConfig, ITenantDatabaseConfig
+│   └── migration.interface.ts      # IMigrationConfig, IMigrationResult
 ├── utils/
-│   └── datasource-config.builder.ts
+│   └── datasource-config.builder.ts # DataSource utilities
 ├── migration/
-│   ├── cli.ts, migration.cli.ts, datasource.factory.ts, migration.runner.ts
+│   ├── cli.ts                      # CLI entry point
+│   ├── migration.cli.ts            # Migration CLI commands
+│   ├── datasource.factory.ts       # DataSource factory
+│   └── migration.runner.ts         # Migration execution
 ├── seeders/
-│   ├── cli.ts, base-seeder.ts, seed-runner.ts, seed-config.ts
-│   ├── entity-reader.ts, data-generator.ts, template-generator.ts
+│   ├── 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
+│   └── template-generator.ts       # Seeder template generation
 ├── docs/
-│   ├── docs.config.ts, docs.setup.ts
+│   └── docs.config.ts              # Swagger setup utilities
 └── index.ts
 ```
 
+---
+
 ## Environment Configuration
 
 ```typescript
 import { envConfig } from '@flusys/nestjs-core/config';
 ```
 
+### Available Methods
+
 | Method | Description |
 |--------|-------------|
 | `tryGetValue(key)` | Get env value (throws for restricted keys) |
-| `getNumber(key)` | Get env value as number |
-| `getBoolean(key)` | Get env value as boolean |
+| `getValue(key, throwOnMissing?)` | Raw string access |
+| `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 array |
+| `getOrigins()` | Get ALLOW_ORIGINS as comma-separated array |
 | `getTypeOrmConfig()` | Get database config |
-| `getJwtConfig()` | Get JWT config |
-| `getRedisUrl()` | Get Redis connection URL |
-| `getMailConfig()` | Get mail configuration |
+| `getJwtConfig()` | Get JWT secret + expiration |
+| `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 configuration |
 | `getEnv()` | Get all env vars as Record |
 
+### Restricted Keys
+
+The following keys require using specific methods (prevents misuse):
+
+| Key | Use Instead |
+|-----|-------------|
+| `FRONTEND_URL` | `getFrontendUrl()` |
+| `ALLOW_ORIGINS` | `getOrigins()` |
+| `PORT` | `getPort()` |
+| `MODE` | `isProduction()` |
+| `DB_HOST/PORT/USER/PASSWORD` | `getTypeOrmConfig()` |
+
+---
+
 ## Database Interfaces
 
+### Core Interfaces
+
 ```typescript
+type DatabaseType = 'mysql' | 'postgres' | 'mariadb' | 'sqlite' | 'mssql';
+type DatabaseMode = 'single' | 'multi-tenant';
+
 interface IDatabaseConfig {
-  type: 'mysql' | 'postgres' | 'mariadb' | 'sqlite' | 'mssql';
-  host?: string; port?: number; username?: string; password?: string; database?: string;
+  type: DatabaseType;
+  host?: string;
+  port?: number;
+  username?: string;
+  password?: string;
+  database?: string;
 }
 
 interface ITenantDatabaseConfig {
-  id: string; database: string; name?: string;
-  host?: string; port?: number; username?: string; password?: string;
+  id: string;
+  database: string;
+  name?: string;
+  host?: string;
+  port?: number;
+  username?: string;
+  password?: string;
   enableCompanyFeature?: boolean;
   permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
 }
@@ -76,122 +132,508 @@ interface IBootstrapAppConfig {
 }
 ```
 
-## Migration CLI
+### Entity Interfaces
+
+```typescript
+interface IBaseEntity {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt?: Date | null;
+}
+
+interface ISoftDeletable {
+  deletedAt?: Date | null;
+}
+
+interface ITimestampable {
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+interface IOrderable {
+  serial?: number;
+}
+
+interface IMetadata {
+  metadata?: Record<string, any> | null;
+}
+
+interface ICompanyOwned {
+  companyId?: string | null;
+}
+```
+
+---
+
+## Migration System
+
+### CLI Commands
 
 ```bash
-npm run migration:generate --name=CreateUsers
-npm run migration:run
-npm run migration:revert
-npm run migration:status
-TENANT_ID=tenant1 npm run migration:run  # specific tenant
-npm run migration:run:all                 # all tenants
+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
+```
+
+### Migration Configuration
+
+```typescript
+import { IMigrationConfig } from '@flusys/nestjs-core';
+
+const migrationConfig: IMigrationConfig = {
+  defaultDatabaseConfig: {
+    type: 'postgres',
+    host: 'localhost',
+    port: 5432,
+    username: 'user',
+    password: 'password',
+    database: 'app_db',
+  },
+  bootstrapAppConfig: {
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
+  },
+  tenants: [
+    { id: 'tenant1', database: 'tenant1_db' },
+    { id: 'tenant2', database: 'tenant2_db', host: 'different-server.com' },
+  ],
+  migrationsPath: './src/persistence/migrations',
+  entities: (tenantConfig) => {
+    // Dynamic entity resolution per tenant
+    return tenantConfig?.enableCompanyFeature
+      ? [UserWithCompany, RoleWithCompany]
+      : [User, Role];
+  },
+  migrationsTableName: 'typeorm_migrations',
+};
 ```
 
+### Core Functions
+
 ```typescript
-import { runMigrationCli, createMigrationDataSource } from '@flusys/nestjs-core/migration';
+import {
+  generateMigration,
+  runMigrations,
+  revertMigration,
+  migrationStatus,
+  runForAllTenants,
+  createMigrationDataSource,
+} from '@flusys/nestjs-core/migration';
+
+// Generate new migration
+await generateMigration(config, 'CreateUsersTable', tenantId?);
+
+// Run pending migrations
+const result: IMigrationResult = await runMigrations(config, tenantId?);
+
+// Revert last migration
+const result: IMigrationResult = await revertMigration(config, tenantId?);
+
+// Check status
+await migrationStatus(config, tenantId?);
+
+// Multi-tenant operations
+const results: IMigrationResult[] = await runForAllTenants(config, 'run');
 ```
 
+---
+
 ## Seed System
 
+### CLI Commands
+
 ```bash
-npm run seed:generate
-npm run seed:run -- --entity=User --count=100
-npm run seed:clear
-npm run seed:status
+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?);
+
+// Register custom seeders (take precedence over generic)
+runner.registerCustomSeeder('User', new UserSeeder(dataSource));
+
+// Run all entities in dependency order
+const results: ISeedResult[] = await runner.runAll({
+  count: 50,               // Records per entity
+  clear: true,             // Clear before seeding
+  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?);
+
+// Get status
+const status = await runner.getStatus();
+// Returns: [{ entity, tableName, count, isEmpty, hasSoftDelete }]
+```
+
+### Custom Seeders
+
 ```typescript
-import { BaseSeeder, SeedRunner } from '@flusys/nestjs-core/seeders';
+import { BaseSeeder, DataGenerator } from '@flusys/nestjs-core/seeders';
 
 class UserSeeder extends BaseSeeder<User> {
-  constructor(ds: DataSource) { super(ds, User); }
+  private generator: DataGenerator;
+
+  constructor(ds: DataSource) {
+    super(ds, User);
+    this.generator = new DataGenerator('en');
+  }
+
   async generate(count: number): Promise<User[]> {
-    const users = [];
+    const users: User[] = [];
     for (let i = 0; i < count; i++) {
-      users.push(this.repository.create({ email: faker.internet.email() }));
+      users.push(this.repository.create({
+        email: faker.internet.email(),
+        name: faker.person.fullName(),
+        password: await bcrypt.hash('password123', 12),
+      }));
     }
     return this.repository.save(users);
   }
 }
 
+// Register before running
 const runner = new SeedRunner(dataSource);
 runner.registerCustomSeeder('User', new UserSeeder(dataSource));
 await runner.runAll({ count: 50, clear: true });
 ```
 
+### EntityReader
+
+Extracts TypeORM metadata for intelligent seeding:
+
+```typescript
+import { EntityReader, IEntityInfo, IColumnInfo } from '@flusys/nestjs-core/seeders';
+
+const reader = new EntityReader(dataSource);
+
+// Get all entities
+const entities = reader.getAllEntities();
+
+// Get detailed entity info
+const info: IEntityInfo = reader.getEntityInfo('User');
+// Returns: { name, tableName, columns, relations, hasSoftDelete, hasCompany }
+
+// Get seeding order (topological sort by FK dependencies)
+const order: string[] = reader.getSeedingOrder(skipEntities?);
+// Independent entities first, then dependents
+```
+
+### DataGenerator
+
+Generates realistic sample data using Faker.js:
+
+```typescript
+import { DataGenerator, IColumnInfo } from '@flusys/nestjs-core/seeders';
+
+const generator = new DataGenerator('en');
+
+// Generate value for a column
+const value = generator.generateValue(columnInfo);
+
+// Generate complete entity
+const entity = generator.generateEntity(columns);
+
+// Relation helpers
+const relatedId = generator.generateRelationId(relatedEntities);
+const relatedIds = generator.generateRelationIds(relatedEntities, min?, max?);
+```
+
+---
+
+## Field Pattern Detection
+
+Intelligent field pattern detection for realistic data generation.
+
+### Supported Patterns
+
+```typescript
+import { detectFieldPattern, FieldPatternType } from '@flusys/nestjs-core/seeders';
+
+// Pattern detection returns one of 58 patterns:
+type FieldPatternType =
+  | 'skip' | 'null' | 'boolean' | 'token'
+  | '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'
+  | /* ...more */;
+
+// Detect pattern for a column
+const pattern = detectFieldPattern(column);
+```
+
+### System Fields
+
+Automatically handled fields:
+
+```typescript
+import { SYSTEM_FIELDS, AUDIT_FIELDS, IDENTITY_FIELDS, BOOLEAN_KEYWORDS } from '@flusys/nestjs-core/seeders';
+
+SYSTEM_FIELDS = ['id', 'createdAt', 'updatedAt', 'deletedAt', ...];
+AUDIT_FIELDS = ['createdbyid', 'updatedbyid', 'deletedbyid'];
+IDENTITY_FIELDS = ['id', 'createdat', 'updatedat', 'deletedat'];
+BOOLEAN_KEYWORDS = ['verified', 'active', 'enabled', 'public', 'readonly', 'valid'];
+```
+
+### Type Category Detection
+
+```typescript
+import { detectTypeCategory, getStringLengthCategory } 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
+
+// String length categorization
+const lengthCategory = getStringLengthCategory(255); // 'sentence'
+// ≤ 50 chars → 'word'
+// ≤ 255 chars → 'sentence'
+// > 255 chars → 'paragraph'
+```
+
+---
+
 ## Swagger Documentation
 
+### Setup Functions
+
 ```typescript
-import { setupSwaggerDocs, setupModuleSwaggerDocs } from '@flusys/nestjs-core/docs';
+import { setupSwaggerDocs, setupModuleSwaggerDocs, IModuleSwaggerOptions } from '@flusys/nestjs-core/docs';
 
+// Variadic API for multiple configs
+setupSwaggerDocs(app, authConfig, adminConfig, iamConfig);
+
+// Array API for module docs
 setupModuleSwaggerDocs(app, [
   { title: 'Auth API', path: 'auth/docs', bearerAuth: true },
   { title: 'Admin API', path: 'admin/docs', excludeTags: ['public'] },
 ]);
 ```
 
+### Configuration Options
+
+```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[];
+}
+
+interface ISchemaPropertyExclusion {
+  schemaName: string;
+  properties: string[];
+}
+
+interface IQueryParameterExclusion {
+  pathPattern: string;   // Supports wildcards: /iam/permissions/*
+  method?: string;       // Optional: 'post', 'get', etc.
+  parameters: string[];
+}
+```
+
 ### Conditional Schema Exclusion
 
 ```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'],
 }]);
 ```
 
+---
+
 ## API Reference
 
+### Interfaces
+
 ```typescript
-// Interfaces
 import {
-  IDatabaseConfig, ITenantDatabaseConfig, IBootstrapAppConfig,
-  IDynamicModuleConfig, IDataSourceServiceOptions,
-  IMigrationConfig, IMigrationResult,
-  IBaseEntity, ISoftDeletable, ITimestampable, IOrderable,
+  IDatabaseConfig,
+  ITenantDatabaseConfig,
+  IBootstrapAppConfig,
+  IDynamicModuleConfig,
+  IDataSourceServiceOptions,
+  IModuleOptionsFactory,
+  IAsyncModuleOptions,
+  IMigrationConfig,
+  IMigrationResult,
+  IBaseEntity,
+  ISoftDeletable,
+  ITimestampable,
+  IOrderable,
+  ICompanyOwned,
+  IMetadata,
 } from '@flusys/nestjs-core';
+```
 
-// Constants
+### Constants
+
+```typescript
 import { MODULE_OPTIONS, DEFAULT_TENANT_HEADER } from '@flusys/nestjs-core';
+```
+
+### Config
 
-// Config
+```typescript
 import { envConfig } from '@flusys/nestjs-core/config';
+```
+
+### Utils
 
-// Utils
+```typescript
 import {
-  buildDataSourceOptions, getDatabaseForTenant,
-  resolveEntities, getActiveTenants,
+  buildDataSourceOptions,
+  getDatabaseForTenant,
+  resolveEntities,
+  getActiveTenants,
+  getMigrationsFolderPath,
+  getMigrationsGlobPattern,
 } from '@flusys/nestjs-core/utils';
+```
 
-// Migration
+### Migration
+
+```typescript
 import {
-  createMigrationDataSource, initializeDataSource, runMigrationCli,
-  generateMigration, runMigrations, revertMigration, migrationStatus,
+  createMigrationDataSource,
+  initializeDataSource,
+  runMigrationCli,
+  generateMigration,
+  runMigrations,
+  revertMigration,
+  migrationStatus,
+  runForAllTenants,
+  ensureMigrationsFolder,
 } from '@flusys/nestjs-core/migration';
+```
+
+### Seeders
 
-// Seeders
+```typescript
 import {
-  BaseSeeder, SeedRunner, EntityReader, DataGenerator,
-  seedConfig, runSeedCli,
+  // 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';
+```
+
+> **Note:** `FieldPatternType`, `AUDIT_FIELDS`, `IDENTITY_FIELDS`, `BOOLEAN_KEYWORDS`, `getStringLengthCategory`, and `getTokenLength` are internal utilities available in `field-patterns.ts` but not exported from the public API.
+
+### Swagger
 
-// Swagger
+```typescript
 import {
-  setupSwaggerDocs, setupModuleSwaggerDocs,
-  IModuleSwaggerOptions, ISchemaPropertyExclusion,
+  setupSwaggerDocs,
+  setupModuleSwaggerDocs,
+  IModuleSwaggerOptions,
+  ISchemaPropertyExclusion,
+  IQueryParameterExclusion,
+  ISwaggerGlobalHeader,
+  IExampleExclusion,
 } from '@flusys/nestjs-core/docs';
 ```
 
+---
+
 ## Dependencies
 
 - `dotenv` - Environment variable loading
-- `typeorm` - Migration/seeder utilities
+- `typeorm` - Migration/seeder utilities (DataSource, EntityMetadata)
 - `@faker-js/faker` - Seed data generation
-
-**No NestJS dependencies** - Can be used in any TypeScript project.
+- `@nestjs/common`, `@nestjs/swagger` - Swagger documentation setup only
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-21