@flusys/nestjs-core 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Core Package Guide
 
 > **Package:** `@flusys/nestjs-core`
+> **Version:** 3.0.0
 > **Type:** Pure TypeScript foundation (zero NestJS dependencies)
 
 Foundation layer providing type-safe configuration, database utilities, migration CLI, seeders with intelligent pattern detection, and Swagger setup.
@@ -29,7 +30,7 @@ nestjs-core/src/
 ├── interfaces/
 │   ├── app-config.interfaces.ts    # IBootstrapAppConfig, IDynamicModuleConfig
 │   ├── base-entity.interface.ts    # IBaseEntity, ISoftDeletable, ITimestampable
-│   ├── database.interface.ts       # IDatabaseConfig, ITenantDatabaseConfig
+│   ├── database.interface.ts       # IDatabaseConfig, ITenantDatabaseConfig, IDataSourceBuildOptions
 │   └── migration.interface.ts      # IMigrationConfig, IMigrationResult
 ├── utils/
 │   └── datasource-config.builder.ts # DataSource utilities
@@ -45,8 +46,7 @@ nestjs-core/src/
 │   ├── 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
+│   └── field-patterns.ts           # Intelligent field pattern detection
 ├── docs/
 │   └── docs.config.ts              # Swagger setup utilities
 └── index.ts
@@ -64,8 +64,7 @@ import { envConfig } from '@flusys/nestjs-core/config';
 
 | Method | Description |
 |--------|-------------|
-| `tryGetValue(key)` | Get env value (throws for restricted keys) |
-| `getValue(key, throwOnMissing?)` | Raw string access |
+| `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) |
@@ -73,13 +72,13 @@ import { envConfig } from '@flusys/nestjs-core/config';
 | `getFrontendUrl()` | Get FRONTEND_URL |
 | `getOrigins()` | Get ALLOW_ORIGINS as comma-separated array |
 | `getTypeOrmConfig()` | Get database config |
-| `getJwtConfig()` | Get JWT secret + expiration |
+| `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 configuration |
-| `getEnv()` | Get all env vars as Record |
+| `getLogConfig()` | Get logging config `{ dir, level, maxSize, maxFiles }` |
+| `getEnv()` | Get all env vars as `Record<string, string>` |
 
 ### Restricted Keys
 
@@ -121,6 +120,7 @@ interface ITenantDatabaseConfig {
   username?: string;
   password?: string;
   enableCompanyFeature?: boolean;
+  enableEmailVerification?: boolean;
   permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
 }
 
@@ -128,6 +128,21 @@ 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;
 }
 ```
 
@@ -151,7 +166,7 @@ interface ITimestampable {
 }
 
 interface IOrderable {
-  serial?: number;
+  serial?: number | null;
 }
 
 interface IMetadata {
@@ -289,13 +304,17 @@ import { SeedRunner, ISeedOptions, ISeedResult } from '@flusys/nestjs-core/seede
 
 const runner = new SeedRunner(dataSource, logger?);
 
-// Register custom seeders (take precedence over generic)
-runner.registerCustomSeeder('User', new UserSeeder(dataSource));
+// 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
@@ -316,9 +335,21 @@ const status = await runner.getStatus();
 
 ### Custom Seeders
 
+Extend `BaseSeeder<T>` for entity-specific seeding logic:
+
 ```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;
 
@@ -346,6 +377,51 @@ runner.registerCustomSeeder('User', new UserSeeder(dataSource));
 await runner.runAll({ count: 50, clear: true });
 ```
 
+### Seeder Interfaces
+
+```typescript
+interface ISeedResult {
+  entity: string;
+  success: boolean;
+  count: number;
+  error?: string;
+  dryRun?: boolean;
+  skipped?: boolean;
+}
+
+interface IEntityInfo {
+  name: string;
+  tableName: string;
+  columns: IColumnInfo[];
+  relations: IRelationInfo[];
+  hasSoftDelete: boolean;
+  hasCompany: boolean;
+}
+
+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;
+}
+
+interface IRelationInfo {
+  propertyName: string;
+  type: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+  targetEntity: string;
+  isNullable: boolean;
+  joinColumnName?: string;
+}
+```
+
 ### EntityReader
 
 Extracts TypeORM metadata for intelligent seeding:
@@ -360,7 +436,6 @@ 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?);
@@ -396,11 +471,14 @@ Intelligent field pattern detection for realistic data generation.
 ### Supported Patterns
 
 ```typescript
-import { detectFieldPattern, FieldPatternType } from '@flusys/nestjs-core/seeders';
+import { detectFieldPattern } from '@flusys/nestjs-core/seeders';
 
-// Pattern detection returns one of 58 patterns:
+// Pattern detection returns one of 30 patterns:
 type FieldPatternType =
-  | 'skip' | 'null' | 'boolean' | 'token'
+  | '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'
@@ -409,7 +487,8 @@ type FieldPatternType =
   | 'username' | 'password'
   | 'birthdate' | 'futureDate' | 'recentDateOrNull'
   | 'serial' | 'company'
-  | /* ...more */;
+  | 'emailProvider'   // smtp, sendgrid, mailgun, ses, postmark
+  | 'formAccessType'; // public, authenticated, permission
 
 // Detect pattern for a column
 const pattern = detectFieldPattern(column);
@@ -417,28 +496,34 @@ const pattern = detectFieldPattern(column);
 
 ### System Fields
 
-Automatically handled fields:
+Automatically handled fields (public API exports `SYSTEM_FIELDS` only):
 
 ```typescript
-import { SYSTEM_FIELDS, AUDIT_FIELDS, IDENTITY_FIELDS, BOOLEAN_KEYWORDS } from '@flusys/nestjs-core/seeders';
+import { SYSTEM_FIELDS, isSystemField } from '@flusys/nestjs-core/seeders';
+
+// Exported constant
+SYSTEM_FIELDS = ['id', 'createdAt', 'updatedAt', 'deletedAt', 'createdById', 'updatedById', 'deletedById'];
+
+// Check if a field is a system field
+isSystemField('createdAt'); // true
 
-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'];
+// 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'];
 ```
 
 ### Type Category Detection
 
 ```typescript
-import { detectTypeCategory, getStringLengthCategory } from '@flusys/nestjs-core/seeders';
+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
 
-// String length categorization
-const lengthCategory = getStringLengthCategory(255); // 'sentence'
+// Internal utility (not exported): getStringLengthCategory()
+// String length categorization:
 // ≤ 50 chars → 'word'
 // ≤ 255 chars → 'sentence'
 // > 255 chars → 'paragraph'
@@ -490,6 +575,19 @@ interface IQueryParameterExclusion {
   method?: string;       // Optional: 'post', 'get', etc.
   parameters: string[];
 }
+
+interface ISwaggerGlobalHeader {
+  name: string;
+  description: string;
+  required?: boolean;
+  example?: string;
+}
+
+interface IExampleExclusion {
+  pathPattern: string;   // Supports wildcards: /auth/*
+  method?: string;       // Optional: 'post', 'get', etc.
+  examples: string[];    // Example names to exclude
+}
 ```
 
 ### Conditional Schema Exclusion
@@ -515,15 +613,21 @@ setupModuleSwaggerDocs(app, [{
 
 ```typescript
 import {
+  // Database
   IDatabaseConfig,
   ITenantDatabaseConfig,
+  IDataSourceBuildOptions,
+  // App Config
   IBootstrapAppConfig,
   IDynamicModuleConfig,
   IDataSourceServiceOptions,
   IModuleOptionsFactory,
   IAsyncModuleOptions,
+  // Migration
   IMigrationConfig,
   IMigrationResult,
+  EntityResolver,
+  // Entity Contracts
   IBaseEntity,
   ISoftDeletable,
   ITimestampable,
@@ -578,39 +682,38 @@ import {
 
 ```typescript
 import {
+  // Classes
   BaseSeeder,
   SeedRunner,
   EntityReader,
   DataGenerator,
-  TemplateGenerator,
-  seedConfig,
-  ISeedConfig,
-  configureSeedConfig,
-  runSeedCli,
-  getEntityCount,
-  shouldSkipEntity,
-  getSeedingOrder,
+  // Interfaces
   ISeedResult,
   ISeedOptions,
   ISeederLogger,
-  defaultLogger,
   IEntityInfo,
   IColumnInfo,
   IRelationInfo,
-  // Field patterns
+  ISeedConfig,
+  // Functions
+  defaultLogger,
+  seedConfig,
+  configureSeedConfig,
+  runSeedCli,
+  getEntityCount,
+  shouldSkipEntity,
+  getSeedingOrder,
+  // Field pattern functions
   detectFieldPattern,
   detectTypeCategory,
-  getStringLengthCategory,
   isSystemField,
-  getTokenLength,
-  FieldPatternType,
+  // Constants
   SYSTEM_FIELDS,
-  AUDIT_FIELDS,
-  IDENTITY_FIELDS,
-  BOOLEAN_KEYWORDS,
 } from '@flusys/nestjs-core/seeders';
 ```
 
+> **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`.
+
 ### Swagger
 
 ```typescript
@@ -636,4 +739,4 @@ import {
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25

package/cjs/seeders/data-generator.js

@@ -111,6 +111,20 @@ let DataGenerator = class DataGenerator {
                 });
             case 'company':
                 return _faker.faker.company.name();
+            case 'emailProvider':
+                return _faker.faker.helpers.arrayElement([
+                    'smtp',
+                    'sendgrid',
+                    'mailgun',
+                    'ses',
+                    'postmark'
+                ]);
+            case 'formAccessType':
+                return _faker.faker.helpers.arrayElement([
+                    'public',
+                    'authenticated',
+                    'permission'
+                ]);
             default:
                 return undefined;
         }

package/cjs/seeders/field-patterns.js

@@ -116,6 +116,10 @@ function detectFieldPattern(column) {
     if (nameLower.includes('serial') || nameLower.includes('order')) return 'serial';
     // Company
     if (nameLower.includes('company') && !nameLower.includes('id')) return 'company';
+    // Email provider type
+    if (nameLower === 'provider' || nameLower === 'emailprovider') return 'emailProvider';
+    // Form access type
+    if (nameLower === 'accesstype' || nameLower === 'access_type') return 'formAccessType';
     return undefined;
 }
 function detectTypeCategory(type) {

package/fesm/seeders/data-generator.js

@@ -106,6 +106,20 @@ import { detectFieldPattern, detectTypeCategory, getStringLengthCategory, getTok
                 });
             case 'company':
                 return faker.company.name();
+            case 'emailProvider':
+                return faker.helpers.arrayElement([
+                    'smtp',
+                    'sendgrid',
+                    'mailgun',
+                    'ses',
+                    'postmark'
+                ]);
+            case 'formAccessType':
+                return faker.helpers.arrayElement([
+                    'public',
+                    'authenticated',
+                    'permission'
+                ]);
             default:
                 return undefined;
         }

package/fesm/seeders/field-patterns.js

@@ -79,6 +79,10 @@
     if (nameLower.includes('serial') || nameLower.includes('order')) return 'serial';
     // Company
     if (nameLower.includes('company') && !nameLower.includes('id')) return 'company';
+    // Email provider type
+    if (nameLower === 'provider' || nameLower === 'emailprovider') return 'emailProvider';
+    // Form access type
+    if (nameLower === 'accesstype' || nameLower === 'access_type') return 'formAccessType';
     return undefined;
 }
 /**

package/interfaces/app-config.interfaces.d.ts

@@ -3,6 +3,7 @@ export interface IBootstrapAppConfig {
     databaseMode: DatabaseMode;
     enableCompanyFeature: boolean;
     permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
+    enableEmailVerification?: boolean;
 }
 export interface IDynamicModuleConfig {
     global?: boolean;

package/interfaces/database.interface.d.ts

@@ -17,6 +17,7 @@ export interface ITenantDatabaseConfig {
     password?: string;
     database: string;
     enableCompanyFeature?: boolean;
+    enableEmailVerification?: boolean;
     permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
 }
 export interface IDataSourceBuildOptions {

package/package.json

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

package/seeders/field-patterns.d.ts

@@ -3,7 +3,7 @@ export declare const SYSTEM_FIELDS: string[];
 export declare const AUDIT_FIELDS: string[];
 export declare const IDENTITY_FIELDS: string[];
 export declare const BOOLEAN_KEYWORDS: string[];
-export 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';
+export 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' | 'emailProvider' | 'formAccessType';
 export type ColumnTypeCategory = 'string' | 'integer' | 'decimal' | 'boolean' | 'date' | 'timestamp' | 'time' | 'uuid' | 'json' | 'array' | 'unknown';
 export declare function detectFieldPattern(column: IColumnInfo): FieldPatternType | undefined;
 export declare function detectTypeCategory(type: string): ColumnTypeCategory;