@flusys/nestjs-core 1.1.0-beta → 1.1.0

package/cjs/seeders/seed-config.js

@@ -1,9 +1,4 @@
-/**
- * Seed Configuration
- *
- * Configuration for seed data generation.
- * Customize record counts, seeding order, and behavior.
- */ "use strict";
+"use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
 });
@@ -14,6 +9,9 @@ function _export(target, all) {
     });
 }
 _export(exports, {
+    get configureSeedConfig () {
+        return configureSeedConfig;
+    },
     get getEntityCount () {
         return getEntityCount;
     },
@@ -28,55 +26,20 @@ _export(exports, {
     }
 });
 const seedConfig = {
-    // Default record counts per entity
-    counts: {
-        // Auth entities
-        Company: 10,
-        CompanyBranch: 25,
-        User: 50,
-        // IAM entities
-        Role: 8,
-        Permission: 45,
-        Action: 30,
-        Menu: 20,
-        UserIAMPermission: 50,
-        UserCompanyPermission: 100,
-        // Storage entities
-        StorageConfig: 5,
-        Folder: 20,
-        FileManager: 100
-    },
-    // Entity seeding order (respects FK constraints)
-    // Parent entities must come before child entities
-    order: [
-        // Auth - foundational
-        'Company',
-        'CompanyBranch',
-        'User',
-        // IAM - permissions system
-        'Action',
-        'Role',
-        'Permission',
-        'Menu',
-        'UserIAMPermission',
-        'UserCompanyPermission',
-        // Storage - file system
-        'StorageConfig',
-        'Folder',
-        'FileManager'
-    ],
-    // Skip these entities (system tables, migrations)
+    counts: {},
+    order: [],
     skipEntities: [
         'migrations',
         'typeorm_metadata',
         'Migration',
         'Typeorm_Metadata'
     ],
-    // Faker locale (en, ar, es, fr, de, etc.)
     locale: 'en',
-    // Respect soft delete when clearing data
     respectSoftDelete: true
 };
+function configureSeedConfig(config) {
+    Object.assign(seedConfig, config);
+}
 function getEntityCount(entityName, config = seedConfig) {
     return config.counts[entityName] || 10;
 }
@@ -85,13 +48,11 @@ function shouldSkipEntity(entityName, config = seedConfig) {
 }
 function getSeedingOrder(availableEntities, config = seedConfig) {
     const ordered = [];
-    // Add entities in configured order
     for (const entityName of config.order){
         if (availableEntities.includes(entityName) && !shouldSkipEntity(entityName, config)) {
             ordered.push(entityName);
         }
     }
-    // Add remaining entities not in order configuration
     for (const entityName of availableEntities){
         if (!ordered.includes(entityName) && !shouldSkipEntity(entityName, config)) {
             ordered.push(entityName);

package/cjs/seeders/seed-runner.js

@@ -58,6 +58,12 @@ let SeedRunner = class SeedRunner {
    */ hasCustomSeeder(entityName) {
         return this.customSeeders.has(entityName);
     }
+    getSeeder(entityName, entity, dataSource, entityInfo, batchSize) {
+        if (this.customSeeders.has(entityName)) {
+            return this.customSeeders.get(entityName);
+        }
+        return new GenericSeeder(dataSource, entity, this.dataGenerator, entityInfo, batchSize);
+    }
     /**
    * Run seeds for all entities
    * @param options Seeding options
@@ -122,13 +128,7 @@ let SeedRunner = class SeedRunner {
             if (!entity) {
                 throw new Error(`Entity ${entityName} not found`);
             }
-            // Get seeder (custom or generic)
-            let seeder;
-            if (this.customSeeders.has(entityName)) {
-                seeder = this.customSeeders.get(entityName);
-            } else {
-                seeder = new GenericSeeder(queryRunner.manager.connection, entity, this.dataGenerator, entityInfo, options.batchSize);
-            }
+            const seeder = this.getSeeder(entityName, entity, queryRunner.manager.connection, entityInfo, options.batchSize);
             // Dry run mode - preview without executing
             if (options.dryRun) {
                 const count = options.count ?? (0, _seedconfig.getEntityCount)(entityName);
@@ -200,13 +200,7 @@ let SeedRunner = class SeedRunner {
                 if (!entity) {
                     throw new Error(`Entity ${entityName} not found`);
                 }
-                // Use custom seeder if available, otherwise generic
-                let seeder;
-                if (this.customSeeders.has(entityName)) {
-                    seeder = this.customSeeders.get(entityName);
-                } else {
-                    seeder = new GenericSeeder(this.dataSource, entity, this.dataGenerator, this.entityReader.getEntityInfo(entityName));
-                }
+                const seeder = this.getSeeder(entityName, entity, this.dataSource, this.entityReader.getEntityInfo(entityName));
                 const countBefore = await seeder.count(true);
                 // Skip if already empty
                 if (countBefore === 0) {

package/cjs/utils/datasource-config.builder.js

@@ -12,9 +12,6 @@ _export(exports, {
     get buildDataSourceOptions () {
         return buildDataSourceOptions;
     },
-    get buildTenantDatabaseConfig () {
-        return buildTenantDatabaseConfig;
-    },
     get getActiveTenants () {
         return getActiveTenants;
     },
@@ -70,7 +67,8 @@ function getDatabaseForTenant(config, tenantId) {
     const defaultTenantConfig = {
         id: 'default',
         database: config.defaultDatabaseConfig.database || 'default',
-        enableCompanyFeature: config.bootstrapAppConfig?.enableCompanyFeature ?? false
+        enableCompanyFeature: config.bootstrapAppConfig?.enableCompanyFeature ?? false,
+        permissionMode: config.bootstrapAppConfig?.permissionMode ?? 'FULL'
     };
     return {
         database: defaultTenantConfig.database,
@@ -83,16 +81,6 @@ function resolveEntities(config, tenantConfig) {
     }
     return config.entities;
 }
-function buildTenantDatabaseConfig(baseConfig, tenant) {
-    return {
-        type: baseConfig.type,
-        host: tenant.host ?? baseConfig.host,
-        port: tenant.port ?? baseConfig.port,
-        username: tenant.username ?? baseConfig.username,
-        password: tenant.password ?? baseConfig.password,
-        database: tenant.database
-    };
-}
 function getActiveTenants(config) {
     return config.tenants || [];
 }

package/docs/docs.config.d.ts

@@ -14,6 +14,11 @@ export interface IQueryParameterExclusion {
     method?: string;
     parameters: string[];
 }
+export interface IExampleExclusion {
+    pathPattern: string;
+    method?: string;
+    examples: string[];
+}
 export interface IModuleSwaggerOptions {
     modules?: Type<unknown>[];
     title: string;
@@ -25,5 +30,7 @@ export interface IModuleSwaggerOptions {
     excludeTags?: string[];
     excludeSchemaProperties?: ISchemaPropertyExclusion[];
     excludeQueryParameters?: IQueryParameterExclusion[];
+    excludeExamples?: IExampleExclusion[];
 }
 export declare function setupModuleSwaggerDocs(app: INestApplication, configs: IModuleSwaggerOptions[]): void;
+export declare function setupSwaggerDocs(app: INestApplication, ...modules: IModuleSwaggerOptions[]): void;

package/docs/index.d.ts

@@ -1,2 +1 @@
 export * from './docs.config';
-export * from './docs.setup';

package/fesm/config/env-config.service.js

@@ -34,7 +34,7 @@ let EnvConfigService = class EnvConfigService {
         return this.getValue(key, throwOnMissing).toLowerCase() === 'true';
     }
     getPort() {
-        return this.getNumber('PORT', false);
+        return this.getNumber('PORT', false) || 3000;
     }
     isProduction() {
         return this.getValue('MODE', false).toUpperCase() !== 'DEV';

package/fesm/docs/docs.config.js

@@ -84,6 +84,65 @@ import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
         paths: filteredPaths
     };
 }
+/**
+ * Filter OpenAPI document to exclude examples from endpoint responses
+ */ function filterExamples(document, exclusions) {
+    if (!exclusions?.length || !document.paths) {
+        return document;
+    }
+    const filteredPaths = {};
+    for (const [path, pathItem] of Object.entries(document.paths)){
+        const filteredPathItem = {};
+        for (const [method, operation] of Object.entries(pathItem)){
+            // Skip non-operation properties
+            if (!operation || typeof operation !== 'object') {
+                filteredPathItem[method] = operation;
+                continue;
+            }
+            // Check if this endpoint matches any exclusion pattern
+            const matchingExclusions = exclusions.filter((exclusion)=>{
+                const pathMatches = pathMatchesPattern(path, exclusion.pathPattern);
+                const methodMatches = !exclusion.method || exclusion.method === method;
+                return pathMatches && methodMatches;
+            });
+            if (matchingExclusions.length > 0) {
+                // Collect all examples to exclude
+                const examplesToExclude = new Set();
+                matchingExclusions.forEach((exclusion)=>{
+                    exclusion.examples.forEach((example)=>examplesToExclude.add(example));
+                });
+                // Deep clone the operation to avoid mutating original
+                const filteredOperation = JSON.parse(JSON.stringify(operation));
+                // Filter examples from responses
+                if (filteredOperation.responses) {
+                    for (const [statusCode, response] of Object.entries(filteredOperation.responses)){
+                        const responseObj = response;
+                        if (responseObj?.content) {
+                            const content = responseObj.content;
+                            for (const [mediaType, mediaTypeObj] of Object.entries(content)){
+                                const media = mediaTypeObj;
+                                if (media?.examples && typeof media.examples === 'object') {
+                                    const examples = media.examples;
+                                    for (const exampleName of examplesToExclude){
+                                        delete examples[exampleName];
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+                filteredPathItem[method] = filteredOperation;
+            } else {
+                filteredPathItem[method] = operation;
+            }
+        }
+        filteredPaths[path] = filteredPathItem;
+    }
+    return {
+        ...document,
+        paths: filteredPaths
+    };
+}
 /**
  * Check if a path matches a pattern (supports wildcards)
  */ function pathMatchesPattern(path, pattern) {
@@ -179,6 +238,15 @@ import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
         if (config.excludeQueryParameters?.length) {
             document = filterQueryParameters(document, config.excludeQueryParameters);
         }
+        // Filter out excluded examples
+        if (config.excludeExamples?.length) {
+            document = filterExamples(document, config.excludeExamples);
+        }
         SwaggerModule.setup(config.path, app, document);
     });
 }
+/**
+ * Setup Swagger docs with variadic module configs
+ */ export function setupSwaggerDocs(app, ...modules) {
+    setupModuleSwaggerDocs(app, modules);
+}

package/fesm/docs/index.js

@@ -1,2 +1 @@
 export * from './docs.config';
-export * from './docs.setup';

package/fesm/interfaces/app-config.interfaces.js

@@ -1,3 +1 @@
-/**
- * Async module options - common pattern for NestJS async module registration
- */ export { };
+/** Async module options pattern */ export { };

package/fesm/interfaces/base-entity.interface.js

@@ -1,6 +1,6 @@
 /**
- * Base Entity Interface
- * All entities should implement this for consistency
- */ /**
- * Entity with metadata
- */ export { };
+ * Entity Contract Interfaces
+ *
+ * These interfaces define the standard fields that entities should have.
+ * Use them as contracts when implementing new entities.
+ */ /** Base entity with UUID, timestamps, and soft delete */ /** Entity with company relation (for multi-company support) */ export { };

package/fesm/interfaces/database.interface.js

@@ -1,5 +1 @@
-/**
- * Supported database types
- */ /**
- * DataSource build options for TypeORM
- */ export { };
+export { };

package/fesm/migration/cli.js

@@ -1,24 +1,5 @@
 #!/usr/bin/env node
-/**
- * Migration CLI Entry Point
- *
- * Main executable for running TypeORM migrations via npm scripts.
- *
- * Usage (via package.json scripts):
- * - npm run migration generate --name=CreateUsers
- * - npm run migration run
- * - npm run migration revert
- * - npm run migration status
- * - npm run migration run:all (multi-tenant)
- * - npm run migration revert:all (multi-tenant)
- * - npm run migration status:all (multi-tenant)
- *
- * Environment Variables:
- * - TENANT_ID: Target specific tenant (optional)
- *
- * This file is the executable entry point referenced in package.json.
- * The actual CLI logic is in migration.cli.ts (runMigrationCli function).
- */ import { runMigrationCli } from './migration.cli';
+import { runMigrationCli } from './migration.cli';
 runMigrationCli().catch((err)=>{
     console.error('CLI Error:', err.message);
     process.exit(1);

package/fesm/migration/datasource.factory.js

@@ -1,20 +1,12 @@
 import { DataSource } from 'typeorm';
 import { SnakeNamingStrategy } from 'typeorm-naming-strategies';
 import { buildDataSourceOptions, getDatabaseForTenant, getMigrationsGlobPattern, resolveEntities } from '../utils/datasource-config.builder';
-/**
- * Create a DataSource for migrations
- *
- * @param options - Configuration options
- * @param options.config - Migration configuration
- * @param options.tenantId - Optional tenant ID for multi-tenant mode
- * @returns DataSource instance (not initialized)
- */ export function createMigrationDataSource(options) {
+export function createMigrationDataSource(options) {
     const { config, tenantId } = options;
     const { database, tenant, tenantConfig } = getDatabaseForTenant(config, tenantId);
-    // Log target info
     console.log(`\n📦 Database: ${database}${tenant ? ` [${tenant.name}]` : ' [default]'}`);
     console.log(`📁 Migrations: migrations/${tenantId || 'default'}/`);
-    if (config.bootstrapAppConfig?.databaseMode == 'multi-tenant' && !tenantId && config.tenants && config.tenants.length > 0) {
+    if (config.bootstrapAppConfig?.databaseMode === 'multi-tenant' && !tenantId && config.tenants && config.tenants.length > 0) {
         console.log(`\n💡 Multi-tenant mode. Available tenants:`);
         config.tenants.forEach((t)=>console.log(`   - TENANT_ID=${t.id} → ${t.database}`));
     }
@@ -29,7 +21,6 @@ import { buildDataSourceOptions, getDatabaseForTenant, getMigrationsGlobPattern,
         ...config.defaultDatabaseConfig,
         database
     };
-    // Resolve entities based on tenant config
     const entities = resolveEntities(config, tenantConfig);
     const dsOptions = buildDataSourceOptions(dbConfig, entities, getMigrationsGlobPattern(config.migrationsPath, tenantId), config.migrationsTableName);
     return new DataSource({
@@ -37,15 +28,7 @@ import { buildDataSourceOptions, getDatabaseForTenant, getMigrationsGlobPattern,
         namingStrategy: new SnakeNamingStrategy()
     });
 }
-/**
- * Initialize and return a DataSource
- *
- * Creates a DataSource and initializes the connection.
- * The connection should be destroyed after use with `ds.destroy()`.
- *
- * @param options - Configuration options
- * @returns Initialized DataSource instance
- */ export async function initializeDataSource(options) {
+export async function initializeDataSource(options) {
     const ds = createMigrationDataSource(options);
     await ds.initialize();
     return ds;

package/fesm/migration/index.js

@@ -1,17 +1,3 @@
-/**
- * Migration Module Exports
- *
- * Public API for TypeORM migration management in single and multi-tenant databases.
- *
- * Main exports:
- * - createMigrationDataSource: Create DataSource for migrations
- * - initializeDataSource: Create and initialize DataSource
- * - runMigrationCli: Programmatic CLI execution
- *
- * The CLI entry point is at ./cli.ts (used by npm scripts)
- */ // DataSource factory for migration config files
 export { createMigrationDataSource, initializeDataSource } from './datasource.factory';
-// CLI service for programmatic usage
 export { runMigrationCli } from './migration.cli';
-// Migration runner functions (optional, for advanced usage)
 export { generateMigration, runMigrations, revertMigration, migrationStatus, runForAllTenants, ensureMigrationsFolder } from './migration.runner';

package/fesm/migration/migration.cli.js

@@ -2,23 +2,7 @@ import * as path from 'path';
 import { envConfig } from '../config';
 import { getDatabaseForTenant, getMigrationsFolderPath } from '../utils';
 import { generateMigration, migrationStatus, revertMigration, runForAllTenants, runMigrations } from './migration.runner';
-/**
- * Migration CLI Service
- *
- * Handles migration command execution for single and multi-tenant databases.
- *
- * Commands:
- * - generate: Create new migration
- * - run: Execute pending migrations
- * - revert: Rollback last migration
- * - status: Check migration status
- * - run:all/revert:all/status:all: Batch operations for all tenants
- *
- * Configuration:
- * - TENANT_ID: Target tenant (optional, defaults to default database)
- * - --config=<path>: Migration config file path
- * - --datasource=<path>: DataSource file path for TypeORM CLI
- */ function showHelp() {
+function showHelp() {
     console.log(`
 Migration CLI
 

package/fesm/migration/migration.runner.js

@@ -4,26 +4,37 @@ import * as path from 'path';
 import { envConfig } from '../config';
 import { getActiveTenants, getDatabaseForTenant, getMigrationsFolderPath } from '../utils';
 import { initializeDataSource } from './datasource.factory';
-/**
- * Migration Runner Functions
- *
- * Core functions for executing migration operations.
- * Supports both single and multi-tenant database configurations.
- *
- * Functions:
- * - ensureMigrationsFolder: Create migrations directory
- * - generateMigration: Create new migration file
- * - runMigrations: Execute pending migrations
- * - revertMigration: Rollback last migration
- * - migrationStatus: Check migration status
- * - runForAllTenants: Batch operations for all tenants
- */ /**
- * Ensure migrations folder exists
- *
- * @param basePath - Base migrations path
- * @param tenantId - Optional tenant ID
- * @returns Full path to migrations folder
- */ export function ensureMigrationsFolder(basePath, tenantId) {
+function getLabel(tenantId) {
+    return tenantId ? `[${tenantId}]` : '[default]';
+}
+async function withDataSource(config, tenantId, operation) {
+    const { database } = getDatabaseForTenant(config, tenantId);
+    const label = getLabel(tenantId);
+    try {
+        const ds = await initializeDataSource({
+            config,
+            tenantId
+        });
+        const partial = await operation(ds, label);
+        await ds.destroy();
+        return {
+            tenantId,
+            database,
+            success: true,
+            ...partial
+        };
+    } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`${label} ✗ Failed: ${errorMessage}`);
+        return {
+            tenantId,
+            database,
+            success: false,
+            error: errorMessage
+        };
+    }
+}
+export function ensureMigrationsFolder(basePath, tenantId) {
     const folder = getMigrationsFolderPath(basePath, tenantId);
     if (!fs.existsSync(folder)) {
         fs.mkdirSync(folder, {
@@ -33,16 +44,7 @@ import { initializeDataSource } from './datasource.factory';
     }
     return folder;
 }
-/**
- * Generate a new migration file
- *
- * Uses TypeORM CLI to generate migration based on entity changes.
- *
- * @param config - Migration configuration
- * @param name - Migration name (e.g., "CreateUsers")
- * @param tenantId - Optional tenant ID for multi-tenant mode
- * @param datasourcePath - Optional path to datasource file
- */ export async function generateMigration(config, name, tenantId, datasourcePath) {
+export async function generateMigration(config, name, tenantId, datasourcePath) {
     const label = tenantId ? `[${tenantId}]` : '[default]';
     const folder = ensureMigrationsFolder(config.migrationsPath, tenantId);
     console.log(`${label} Generating migration: ${name}`);
@@ -72,24 +74,9 @@ function findDatasourcePath() {
     }
     throw new Error('Could not find datasource file. Specify with --datasource=<path>');
 }
-/**
- * Run pending migrations
- *
- * Executes all pending migrations for the specified tenant or default database.
- *
- * @param config - Migration configuration
- * @param tenantId - Optional tenant ID for multi-tenant mode
- * @returns Migration result with success status
- */ export async function runMigrations(config, tenantId) {
-    const { database } = getDatabaseForTenant(config, tenantId);
-    const label = tenantId ? `[${tenantId}]` : '[default]';
-    try {
-        const ds = await initializeDataSource({
-            config,
-            tenantId
-        });
+export async function runMigrations(config, tenantId) {
+    return withDataSource(config, tenantId, async (ds, label)=>{
         const migrations = await ds.runMigrations();
-        await ds.destroy();
         if (migrations.length === 0) {
             console.log(`${label} No pending migrations.`);
         } else {
@@ -97,105 +84,29 @@ function findDatasourcePath() {
             migrations.forEach((m)=>console.log(`   - ${m.name}`));
         }
         return {
-            tenantId,
-            database,
-            success: true,
             migrationsRun: migrations.map((m)=>m.name)
         };
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        console.error(`${label} ✗ Failed: ${errorMessage}`);
-        return {
-            tenantId,
-            database,
-            success: false,
-            error: errorMessage
-        };
-    }
+    });
 }
-/**
- * Revert last migration
- *
- * Rolls back the most recently executed migration.
- *
- * @param config - Migration configuration
- * @param tenantId - Optional tenant ID for multi-tenant mode
- * @returns Migration result with success status
- */ export async function revertMigration(config, tenantId) {
-    const { database } = getDatabaseForTenant(config, tenantId);
-    const label = tenantId ? `[${tenantId}]` : '[default]';
-    try {
-        const ds = await initializeDataSource({
-            config,
-            tenantId
-        });
+export async function revertMigration(config, tenantId) {
+    return withDataSource(config, tenantId, async (ds, label)=>{
         await ds.undoLastMigration();
-        await ds.destroy();
         console.log(`${label} ✓ Reverted!`);
-        return {
-            tenantId,
-            database,
-            success: true
-        };
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        console.error(`${label} ✗ Failed: ${errorMessage}`);
-        return {
-            tenantId,
-            database,
-            success: false,
-            error: errorMessage
-        };
-    }
+        return {};
+    });
 }
-/**
- * Check migration status
- *
- * Shows whether there are pending migrations to run.
- *
- * @param config - Migration configuration
- * @param tenantId - Optional tenant ID for multi-tenant mode
- * @returns Migration result with status information
- */ export async function migrationStatus(config, tenantId) {
-    const { database } = getDatabaseForTenant(config, tenantId);
-    const label = tenantId ? `[${tenantId}]` : '[default]';
-    try {
-        const ds = await initializeDataSource({
-            config,
-            tenantId
-        });
+export async function migrationStatus(config, tenantId) {
+    return withDataSource(config, tenantId, async (ds, label)=>{
         const hasPending = await ds.showMigrations();
-        await ds.destroy();
         console.log(`${label} Pending: ${hasPending ? 'Yes' : 'No'}`);
         return {
-            tenantId,
-            database,
-            success: true,
             migrationsRun: [
                 hasPending ? 'Has pending' : 'Up to date'
             ]
         };
-    } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        console.error(`${label} ✗ Failed: ${errorMessage}`);
-        return {
-            tenantId,
-            database,
-            success: false,
-            error: errorMessage
-        };
-    }
+    });
 }
-/**
- * Run migration command for all tenants
- *
- * Executes the specified command for all active tenants in batch mode.
- * Only works in multi-tenant database mode.
- *
- * @param config - Migration configuration
- * @param command - Command to run: 'run', 'revert', or 'status'
- * @returns Array of migration results for each tenant
- */ export async function runForAllTenants(config, command) {
+export async function runForAllTenants(config, command) {
     const tenants = getActiveTenants(config);
     console.log(`\n🔄 Running '${command}' for ${tenants.length} tenant(s)...\n`);
     const results = [];