@flusys/nestjs-core 4.1.0 → 5.0.0

package/README.md

@@ -1,92 +1,9 @@
 # @flusys/nestjs-core
 
-> Foundation infrastructure for NestJS applications — type-safe environment configuration, TypeORM migration CLI, intelligent data seeding, and modular Swagger documentation.
+Foundation infrastructure for NestJS applications — environment config, TypeORM migrations, 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
-
-- [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)
-  - [BaseSeeder](#baseseeder)
-  - [SeedRunner](#seedrunner)
-  - [DataGenerator](#datagenerator)
-  - [Seed CLI](#seed-cli)
-- [Swagger Documentation](#swagger-documentation)
-  - [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)
-
----
-
-## Overview
-
-`@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.
-
----
-
-## Features
-
-- **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
-```
-
-`nestjs-core` is the only FLUSYS package with no upstream FLUSYS dependencies. All other packages depend on it.
-
----
-
-## Compatibility
-
-| 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` |
 
 ---
 
@@ -94,549 +11,161 @@ auth | iam | storage | email | form-builder | event-manager | notification | loc
 
 ```bash
 npm install @flusys/nestjs-core
-```
-
-```bash
-# Peer dependencies
-npm install typeorm typeorm-naming-strategies @faker-js/faker dotenv
-
-# For migration and seed CLIs
+npm install typeorm typeorm-naming-strategies dotenv
 npm install -D ts-node tsconfig-paths
-
-# For Swagger (docs/ module only)
-npm install @nestjs/common @nestjs/swagger
 ```
 
 ---
 
-## 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
-```
+## 1. Environment Config
 
----
-
-## Quick Start
-
-### Environment Config
+Access typed environment variables via the `envConfig` singleton — no class instantiation needed.
 
 ```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);
-```
-
-### 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"
-  }
-}
-```
-
-### Setup Swagger
-
-```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);
-}
+const port    = envConfig.getPort();           // number
+const db      = envConfig.getTypeOrmConfig();  // { host, port, username, password, database }
+const jwt     = envConfig.getJwtConfig();      // { secret, expiration, refreshSecret, ... }
+const origins = envConfig.getOrigins();        // string[]
+const isProd  = envConfig.isProduction();      // boolean
+ public tryGetValue(key: string, throwOnMissing = false): string // get env value
 ```
 
 ---
 
-## EnvConfigService
-
-A singleton pre-instantiated as `envConfig`. Loads `.env` on import via `dotenv`.
-
-### Restricted Keys
+## 2. Migrations
 
-The following keys cannot be accessed via `tryGetValue()` — use their dedicated typed methods instead:
+### Create `src/persistence/migration.config.ts`
 
-`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 CLI
-
-### Migration Config File
+```typescript
+import { createMigrationDataSource, IMigrationConfig } from '@flusys/nestjs-core';
+import { envConfig } from '@flusys/nestjs-core/config';
+import { getAuthEntitiesByConfig } from '@flusys/nestjs-auth';
+import { getIAMEntitiesByConfig } from '@flusys/nestjs-iam';
 
-Create `migration.config.ts` in your project root:
+const bootstrapConfig = {
+  databaseMode: 'single' as const,
+  enableCompanyFeature: true,
+  permissionMode: 'FULL' as const,
+};
 
-```typescript
-import { IMigrationConfig } from '@flusys/nestjs-core';
-import { AuthModule } from '@flusys/nestjs-auth';
-import { IAMModule } from '@flusys/nestjs-iam';
-
-const config: IMigrationConfig = {
-  defaultDatabaseConfig: {
-    type: 'postgres',
-    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',
-  },
+export const migrationConfig: IMigrationConfig = {
+  defaultDatabaseConfig: envConfig.getTypeOrmConfig(),
+  bootstrapAppConfig: bootstrapConfig,
+  migrationsPath: `${__dirname}/migrations`,
+  migrationsTableName: 'migrations',
   entities: [
-    ...AuthModule.getEntities({ enableCompanyFeature: true, enableEmailVerification: true }),
-    ...IAMModule.getEntities({ enableCompanyFeature: true, permissionMode: 'FULL' }),
-    // ... other module entities
+    ...getAuthEntitiesByConfig(bootstrapConfig),
+    ...getIAMEntitiesByConfig(bootstrapConfig),
   ],
-  migrationsPath: 'src/migrations',
-  migrationsTableName: 'migrations',
 };
 
-export default config;
-```
-
-### 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 {
-  createMigrationDataSource,
-  runMigrations,
-  revertMigration,
-  migrationStatus,
-  generateMigration,
-  runForAllTenants,
-} from '@flusys/nestjs-core';
-
-// Create a DataSource for migration operations
-const dataSource = await createMigrationDataSource(config, tenantId);
-
-// Run pending migrations
-await runMigrations(dataSource);
-
-// Revert last migration
-await revertMigration(dataSource);
-
-// Check status
-const status = await migrationStatus(dataSource);
-
-// Generate a new migration file
-await generateMigration(config, 'MigrationName');
-
-// Multi-tenant: run for all configured tenants
-await runForAllTenants(config, runMigrations);
+// Required for TypeORM CLI
+export default createMigrationDataSource({
+  config: migrationConfig,
+  tenantId: process.env.TENANT_ID,
+});
 ```
 
----
-
-## Seed System
-
-### BaseSeeder
-
-Extend `BaseSeeder` to create custom seeders:
+### Add scripts to `package.json`
 
-```typescript
-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 clear(dataSource: DataSource): Promise<void> {
-    await dataSource.getRepository(User).delete({});
+```json
+{
+  "scripts": {
+    "migration":          "ts-node -r tsconfig-paths/register ./node_modules/@flusys/nestjs-core/migration/cli --config=src/persistence/migration.config.ts",
+    "migration:generate": "npm run migration -- generate",
+    "migration:run":      "npm run migration -- run",
+    "migration:revert":   "npm run migration -- revert",
+    "migration:status":   "npm run migration -- status",
+    "migration:run:all":    "npm run migration -- run:all",
+    "migration:revert:all": "npm run migration -- revert:all",
+    "migration:status:all": "npm run migration -- status:all"
   }
 }
 ```
 
-### SeedRunner
-
-```typescript
-import { SeedRunner, seedConfig } from '@flusys/nestjs-core';
-
-// Register seeders
-seedConfig.register([UserSeeder, RoleSeeder, PermissionSeeder]);
-
-// Run all seeders (respects order and dependencies)
-const runner = new SeedRunner(dataSource);
-const result = await runner.run();
-console.log(`Seeded ${result.count} records`);
-
-// Clear all seeded data (in reverse order)
-await runner.clear();
-
-// Check seeder status
-const status = await runner.status();
-```
-
-### DataGenerator
-
-Generates realistic test data from TypeORM entity metadata using Faker.js:
-
-```typescript
-import { DataGenerator } from '@flusys/nestjs-core';
-
-const generator = new DataGenerator(dataSource);
-
-// Auto-detect field types and generate appropriate data
-const fakeUser = generator.generate(User, {
-  overrides: { email: 'specific@email.com' },
-  count: 10, // generate 10 records
-});
-```
-
-**Automatic field pattern detection:**
-
-| 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()` |
-
-### Seed CLI
+### Run
 
 ```bash
-# Run all seeders
-npm run seed:run
-
-# Clear all seeded data
-npm run seed:clear
-
-# Show seeder status
-npm run seed:status
-```
-
----
-
-## Swagger Documentation
-
-### setupSwaggerDocs
-
-Sets up a single global Swagger UI for the whole application:
-
-```typescript
-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
-});
-```
-
-### setupModuleSwaggerDocs
-
-Sets up module-scoped Swagger documentation at separate URLs — one per feature module:
-
-```typescript
-import { setupModuleSwaggerDocs } from '@flusys/nestjs-core/docs';
-
-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'],
-  },
-]);
-```
-
-### IModuleSwaggerOptions
-
-```typescript
-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;
-}
-```
-
----
-
-## Database Utilities
-
-```typescript
-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',
-});
-
-// Get migrations folder path (supports tenant-specific subdirectories)
-const migrationsPath = getMigrationsFolderPath('src/migrations', 'tenant-1');
-
-// Get all active tenant configs
-const tenants = getActiveTenants(migrationConfig);
-```
-
----
-
-## Core Interfaces
-
-These interfaces are used as contracts across all FLUSYS feature modules:
-
-```typescript
-// Entity contracts
-interface IIdentity { id: string; createdAt: Date; updatedAt: Date; deletedAt?: Date | null; }
-
-// Bootstrap configuration (fixed at startup)
-interface IBootstrapAppConfig {
-  databaseMode: 'single' | 'multi-tenant';
-  enableCompanyFeature: boolean;
-  enableEmailVerification?: boolean;
-  permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
-}
-
-// DataSource configuration
-interface IDatabaseConfig {
-  type: 'postgres' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql';
-  host: string;
-  port: number;
-  username: string;
-  password: string;
-  database: string;
-}
-
-// Multi-tenant config
-interface ITenantDatabaseConfig extends IDatabaseConfig { id: string; }
-
-// Module options for dynamic modules
-interface IDynamicModuleConfig {
-  global?: boolean;
-  includeController?: boolean;
-}
-
-// DataSource service options (base for all module configs)
-interface IDataSourceServiceOptions {
-  defaultDatabaseConfig?: IDatabaseConfig;
-  tenantDefaultDatabaseConfig?: IDatabaseConfig;
-  tenants?: ITenantDatabaseConfig[];
-}
-```
-
----
-
-## Injection Tokens & Constants
-
-```typescript
-import {
-  MIGRATION_CONFIG_TOKEN,
-  SEED_CONFIG_TOKEN,
-  DATASOURCE_TOKEN,
-} from '@flusys/nestjs-core';
-```
-
----
-
-## Multi-Tenant Support
-
-`nestjs-core` provides the foundation for multi-tenant architectures:
-
-```typescript
-import { buildDataSourceOptions, getDatabaseForTenant, getActiveTenants } from '@flusys/nestjs-core';
-
-// Get database config for a specific tenant
-const tenantDb = getDatabaseForTenant(migrationConfig, 'tenant-id');
+# Single database
+npm run migration:generate -- --name=CreateUsersTable
+npm run migration:run
+npm run migration:revert
+npm run migration:status
 
-// Build a DataSource for that tenant
-const dsOptions = buildDataSourceOptions({
-  config: tenantDb,
-  entities: [...allEntities],
-  migrationsPath: getMigrationsFolderPath('src/migrations', 'tenant-id'),
-});
+# Tenant-specific (prefix with TENANT_ID)
+TENANT_ID=tenant-1 npm run migration:generate -- --name=CreateUsersTable
+TENANT_ID=tenant-1 npm run migration:run
+TENANT_ID=tenant-1 npm run migration:revert
+TENANT_ID=tenant-1 npm run migration:status
 
-// Run migrations for all configured tenants
-await runForAllTenants(migrationConfig, async (dataSource) => {
-  await runMigrations(dataSource);
-});
+# All tenants at once
+npm run migration:run:all
+npm run migration:revert:all
+npm run migration:status:all
 ```
 
 ---
 
-## Troubleshooting
-
-**`Cannot find migration config file`**
-
-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.
-
----
-
-**`RESTRICTED_KEY` error from `tryGetValue`**
+## 3. Swagger
 
-You are trying to access a sensitive key (DB credentials, JWT secrets) via the generic accessor. Use the typed method instead:
+`setupSwaggerDocs` and `setupModuleSwaggerDocs` accept the same `IModuleSwaggerOptions` shape.
 
 ```typescript
-// Wrong
-envConfig.tryGetValue('JWT_SECRET')   // throws RestrictedKeyError
-
-// Correct
-envConfig.getJwtConfig().secret
-```
-
----
-
-**`SnakeNamingStrategy` column name mismatch**
-
-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`.
-
----
+import { NestFactory } from '@nestjs/core';
+import { setupSwaggerDocs, setupModuleSwaggerDocs } from '@flusys/nestjs-core/docs';
+import { AuthModule } from '@flusys/nestjs-auth';
 
-**Seeder runs out of order**
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
 
-Set explicit `order` numbers or use `dependencies` to declare which seeders must run before yours:
+  // All available options (one entry showing every field)
+  setupModuleSwaggerDocs(app, [
+    {
+      title: 'Auth API',               // required
+      description: 'Auth endpoints',   // required
+      version: '1.0',                  // optional, default '1.0'
+      path: 'api/docs/auth',           // required — URL where docs are served
+      bearerAuth: true,                // adds Authorization header to Swagger UI
+      modules: [AuthModule],           // scope to specific NestJS modules only
+
+      // Exclude controllers by @ApiTags name
+      excludeTags: ['Internal', 'Health'],
+
+      // Exclude specific paths (supports * and ** wildcards)
+      excludePaths: ['/api/auth/internal/*', '/api/health'],
+
+      // Exclude properties from a DTO schema
+      excludeSchemaProperties: [
+        { schemaName: 'CreateUserDto', properties: ['passwordHash', 'salt'] },
+      ],
+
+      // Exclude query parameters from specific endpoints
+      excludeQueryParameters: [
+        { pathPattern: '/api/auth/*', method: 'post', parameters: ['debug'] },
+      ],
+
+      // Exclude named examples from responses
+      excludeExamples: [
+        { pathPattern: '/api/auth/login', examples: ['AdminExample'] },
+      ],
+
+      // Add a custom header to every request in Swagger UI
+      globalHeaders: [
+        { name: 'x-tenant-id', description: 'Tenant identifier', required: false, example: 'tenant-1' },
+      ],
+    },
+
+    // Minimal entry
+    { title: 'IAM API', description: 'Roles and permissions', path: 'api/docs/iam' },
+  ]);
 
-```typescript
-export class ProductSeeder extends BaseSeeder {
-  name = 'ProductSeeder';
-  dependencies = ['CategorySeeder']; // CategorySeeder must run first
+  await app.listen(3000);
 }
 ```
 
----
 
 ## License
 
 MIT © FLUSYS
-
----
-
-> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.