@flusys/nestjs-core 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,193 @@
+# Core Package Guide
+
+> **Package:** `@flusys/nestjs-core`
+> **Type:** Pure TypeScript utilities (Zero NestJS dependencies)
+
+Foundation layer providing type-safe configuration, database utilities, migration CLI, seeders, and Swagger setup.
+
+## Package Architecture
+
+```
+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
+│   └── migration.interface.ts   # IMigrationConfig, IMigrationResult
+├── utils/
+│   └── datasource-config.builder.ts
+├── migration/
+│   ├── cli.ts, migration.cli.ts, datasource.factory.ts, migration.runner.ts
+├── seeders/
+│   ├── cli.ts, base-seeder.ts, seed-runner.ts, seed-config.ts
+│   ├── entity-reader.ts, data-generator.ts, template-generator.ts
+├── docs/
+│   ├── docs.config.ts, docs.setup.ts
+└── index.ts
+```
+
+## Environment Configuration
+
+```typescript
+import { envConfig } from '@flusys/nestjs-core/config';
+```
+
+| 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 |
+| `getPort()` | Get PORT (default: 3000) |
+| `isProduction()` | Check if MODE !== 'DEV' |
+| `getFrontendUrl()` | Get FRONTEND_URL |
+| `getOrigins()` | Get ALLOW_ORIGINS as array |
+| `getTypeOrmConfig()` | Get database config |
+| `getJwtConfig()` | Get JWT config |
+| `getRedisUrl()` | Get Redis connection URL |
+| `getMailConfig()` | Get mail configuration |
+| `getTenantId()` | Get TENANT_ID |
+| `useTenantMode()` | Check USE_TENANT_MODE |
+| `getLogConfig()` | Get logging configuration |
+| `getEnv()` | Get all env vars as Record |
+
+## Database Interfaces
+
+```typescript
+interface IDatabaseConfig {
+  type: 'mysql' | 'postgres' | 'mariadb' | 'sqlite' | 'mssql';
+  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;
+  enableCompanyFeature?: boolean;
+  permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
+}
+
+interface IBootstrapAppConfig {
+  databaseMode: 'single' | 'multi-tenant';
+  enableCompanyFeature: boolean;
+  permissionMode?: 'FULL' | 'RBAC' | 'DIRECT';
+}
+```
+
+## Migration CLI
+
+```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
+```
+
+```typescript
+import { runMigrationCli, createMigrationDataSource } from '@flusys/nestjs-core/migration';
+```
+
+## Seed System
+
+```bash
+npm run seed:generate
+npm run seed:run -- --entity=User --count=100
+npm run seed:clear
+npm run seed:status
+```
+
+```typescript
+import { BaseSeeder, SeedRunner } from '@flusys/nestjs-core/seeders';
+
+class UserSeeder extends BaseSeeder<User> {
+  constructor(ds: DataSource) { super(ds, User); }
+  async generate(count: number): Promise<User[]> {
+    const users = [];
+    for (let i = 0; i < count; i++) {
+      users.push(this.repository.create({ email: faker.internet.email() }));
+    }
+    return this.repository.save(users);
+  }
+}
+
+const runner = new SeedRunner(dataSource);
+runner.registerCustomSeeder('User', new UserSeeder(dataSource));
+await runner.runAll({ count: 50, clear: true });
+```
+
+## Swagger Documentation
+
+```typescript
+import { setupSwaggerDocs, setupModuleSwaggerDocs } from '@flusys/nestjs-core/docs';
+
+setupModuleSwaggerDocs(app, [
+  { title: 'Auth API', path: 'auth/docs', bearerAuth: true },
+  { title: 'Admin API', path: 'admin/docs', excludeTags: ['public'] },
+]);
+```
+
+### Conditional Schema Exclusion
+
+```typescript
+setupModuleSwaggerDocs(app, [{
+  title: 'Auth API',
+  path: 'auth/docs',
+  excludeSchemaProperties: enableCompanyFeature ? undefined : [
+    { schemaName: 'LoginResponseDto', properties: ['company', 'branch'] },
+  ],
+}]);
+```
+
+## API Reference
+
+```typescript
+// Interfaces
+import {
+  IDatabaseConfig, ITenantDatabaseConfig, IBootstrapAppConfig,
+  IDynamicModuleConfig, IDataSourceServiceOptions,
+  IMigrationConfig, IMigrationResult,
+  IBaseEntity, ISoftDeletable, ITimestampable, IOrderable,
+} from '@flusys/nestjs-core';
+
+// Constants
+import { MODULE_OPTIONS, DEFAULT_TENANT_HEADER } from '@flusys/nestjs-core';
+
+// Config
+import { envConfig } from '@flusys/nestjs-core/config';
+
+// Utils
+import {
+  buildDataSourceOptions, getDatabaseForTenant,
+  resolveEntities, getActiveTenants,
+} from '@flusys/nestjs-core/utils';
+
+// Migration
+import {
+  createMigrationDataSource, initializeDataSource, runMigrationCli,
+  generateMigration, runMigrations, revertMigration, migrationStatus,
+} from '@flusys/nestjs-core/migration';
+
+// Seeders
+import {
+  BaseSeeder, SeedRunner, EntityReader, DataGenerator,
+  seedConfig, runSeedCli,
+} from '@flusys/nestjs-core/seeders';
+
+// Swagger
+import {
+  setupSwaggerDocs, setupModuleSwaggerDocs,
+  IModuleSwaggerOptions, ISchemaPropertyExclusion,
+} from '@flusys/nestjs-core/docs';
+```
+
+## Dependencies
+
+- `dotenv` - Environment variable loading
+- `typeorm` - Migration/seeder utilities
+- `@faker-js/faker` - Seed data generation
+
+**No NestJS dependencies** - Can be used in any TypeScript project.

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

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "envConfig", {
+    enumerable: true,
+    get: function() {
+        return envConfig;
+    }
+});
+const _dotenv = /*#__PURE__*/ _interop_require_wildcard(require("dotenv"));
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+_dotenv.config();
+let EnvConfigService = class EnvConfigService {
+    getValue(key, throwOnMissing = true) {
+        const value = this.env[key];
+        if (!value && throwOnMissing) {
+            throw new Error(`Config error - missing env.${key}`);
+        }
+        return value ?? '';
+    }
+    tryGetValue(key, throwOnMissing = false) {
+        if (this.restrictedKeys[key]) {
+            throw new Error(`Access denied for env key "${key}". Use the method \`${this.restrictedKeys[key]}()\` instead.`);
+        }
+        return this.getValue(key, throwOnMissing);
+    }
+    getNumber(key, throwOnMissing = true) {
+        return Number(this.getValue(key, throwOnMissing));
+    }
+    getBoolean(key, throwOnMissing = true) {
+        return this.getValue(key, throwOnMissing).toLowerCase() === 'true';
+    }
+    getPort() {
+        return this.getNumber('PORT', false);
+    }
+    isProduction() {
+        return this.getValue('MODE', false).toUpperCase() !== 'DEV';
+    }
+    getFrontendUrl() {
+        return this.getValue('FRONTEND_URL');
+    }
+    getOrigins() {
+        const origins = this.getValue('ALLOW_ORIGINS');
+        return origins ? origins.split(',').map((o)=>o.trim()) : [];
+    }
+    getTypeOrmConfig() {
+        return {
+            host: this.getValue('DB_HOST'),
+            port: this.getNumber('DB_PORT'),
+            username: this.getValue('DB_USER'),
+            password: this.getValue('DB_PASSWORD')
+        };
+    }
+    getJwtConfig() {
+        return {
+            secret: this.getValue('JWT_SECRET'),
+            expiration: this.getValue('JWT_EXPIRATION', false) || '1h',
+            refreshSecret: this.getValue('REFRESH_TOKEN_SECRET'),
+            refreshExpiration: this.getValue('REFRESH_TOKEN_EXPIRATION', false) || '7d'
+        };
+    }
+    getRedisUrl() {
+        return this.getValue('REDIS_URL', false) || 'redis://localhost:6379';
+    }
+    getMailConfig() {
+        return {
+            MAIL_FROM: this.getValue('MAIL_FROM', false) || '',
+            MAIL_APP_PASSWORD: this.getValue('MAIL_APP_PASSWORD', false) || ''
+        };
+    }
+    getTenantId() {
+        return this.getValue('TENANT_ID', false) || null;
+    }
+    useTenantMode() {
+        return this.getValue('USE_TENANT_MODE', false).toLowerCase() === 'true';
+    }
+    getLogConfig() {
+        return {
+            dir: this.getValue('LOG_DIR', false) || 'logs',
+            level: this.getValue('LOG_LEVEL', false) || (this.isProduction() ? 'info' : 'debug'),
+            maxSize: this.getValue('LOG_MAX_SIZE', false) || '20m',
+            maxFiles: this.getValue('LOG_MAX_FILES', false) || '14d'
+        };
+    }
+    getEnv() {
+        return process.env;
+    }
+    constructor(env){
+        _define_property(this, "env", void 0);
+        _define_property(this, "restrictedKeys", void 0);
+        this.env = env;
+        this.restrictedKeys = {
+            FRONTEND_URL: 'getFrontendUrl',
+            ALLOW_ORIGINS: 'getOrigins',
+            PORT: 'getPort',
+            MODE: 'isProduction',
+            DB_HOST: 'getTypeOrmConfig',
+            DB_PORT: 'getTypeOrmConfig',
+            DB_USER: 'getTypeOrmConfig',
+            DB_PASSWORD: 'getTypeOrmConfig'
+        };
+    }
+};
+const envConfig = new EnvConfigService(process.env);

package/cjs/config/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./env-config.service"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/cjs/constants/database.constants.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get DEFAULT_TENANT_HEADER () {
+        return DEFAULT_TENANT_HEADER;
+    },
+    get MODULE_OPTIONS () {
+        return MODULE_OPTIONS;
+    }
+});
+const MODULE_OPTIONS = Symbol('MODULE_OPTIONS');
+const DEFAULT_TENANT_HEADER = 'x-tenant-id';

package/cjs/constants/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./database.constants"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/cjs/docs/docs.config.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "setupModuleSwaggerDocs", {
+    enumerable: true,
+    get: function() {
+        return setupModuleSwaggerDocs;
+    }
+});
+const _swagger = require("@nestjs/swagger");
+/**
+ * Filter OpenAPI document to exclude schema properties
+ */ function filterSchemaProperties(document, exclusions) {
+    if (!exclusions?.length || !document.components?.schemas) {
+        return document;
+    }
+    const schemas = {
+        ...document.components.schemas
+    };
+    for (const exclusion of exclusions){
+        const schema = schemas[exclusion.schemaName];
+        if (schema && typeof schema === 'object' && 'properties' in schema) {
+            const filteredProperties = {
+                ...schema.properties
+            };
+            for (const prop of exclusion.properties){
+                delete filteredProperties[prop];
+            }
+            // Also remove from required array if present
+            const filteredRequired = schema.required?.filter((r)=>!exclusion.properties.includes(r));
+            schemas[exclusion.schemaName] = {
+                ...schema,
+                properties: filteredProperties,
+                ...filteredRequired?.length ? {
+                    required: filteredRequired
+                } : {}
+            };
+        }
+    }
+    return {
+        ...document,
+        components: {
+            ...document.components,
+            schemas
+        }
+    };
+}
+/**
+ * Filter OpenAPI document to exclude query parameters from specific endpoints
+ */ function filterQueryParameters(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 parameters to exclude
+                const paramsToExclude = new Set();
+                matchingExclusions.forEach((exclusion)=>{
+                    exclusion.parameters.forEach((param)=>paramsToExclude.add(param));
+                });
+                // Filter out excluded query parameters
+                const filteredOperation = {
+                    ...operation
+                };
+                if (Array.isArray(filteredOperation.parameters)) {
+                    filteredOperation.parameters = filteredOperation.parameters.filter((param)=>{
+                        return !(param.in === 'query' && paramsToExclude.has(param.name));
+                    });
+                }
+                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) {
+    // Convert wildcard pattern to regex
+    const regexPattern = pattern.replace(/\*/g, '[^/]+') // * matches any characters except /
+    .replace(/\*\*/g, '.*'); // ** matches any characters including /
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(path);
+}
+/**
+ * Filter OpenAPI document to exclude paths and tags based on excludeTags
+ */ function filterDocumentByTags(document, excludeTags) {
+    if (!excludeTags?.length) {
+        return document;
+    }
+    const excludeTagsSet = new Set(excludeTags.map((tag)=>tag.toLowerCase()));
+    // Filter out paths that have any of the excluded tags
+    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 like 'parameters'
+            if (!operation || typeof operation !== 'object' || !('tags' in operation)) {
+                filteredPathItem[method] = operation;
+                continue;
+            }
+            const operationTags = operation.tags || [];
+            const hasExcludedTag = operationTags.some((tag)=>excludeTagsSet.has(tag.toLowerCase()));
+            if (!hasExcludedTag) {
+                filteredPathItem[method] = operation;
+            }
+        }
+        // Only include path if it has at least one operation
+        const hasOperations = Object.keys(filteredPathItem).some((key)=>[
+                'get',
+                'post',
+                'put',
+                'patch',
+                'delete',
+                'options',
+                'head'
+            ].includes(key));
+        if (hasOperations) {
+            filteredPaths[path] = filteredPathItem;
+        }
+    }
+    // Filter out excluded tags from the tags array
+    const filteredTags = document.tags?.filter((tag)=>!excludeTagsSet.has(tag.name.toLowerCase()));
+    return {
+        ...document,
+        paths: filteredPaths,
+        tags: filteredTags
+    };
+}
+function setupModuleSwaggerDocs(app, configs) {
+    configs.forEach((config)=>{
+        const builder = new _swagger.DocumentBuilder().setTitle(config.title).setDescription(config.description).setVersion(config.version || '1.0');
+        // Add bearer auth
+        if (config.bearerAuth) {
+            builder.addBearerAuth();
+        }
+        // Add custom global headers
+        if (config.globalHeaders?.length) {
+            config.globalHeaders.forEach((header)=>{
+                builder.addGlobalParameters({
+                    name: header.name,
+                    in: 'header',
+                    description: header.description,
+                    required: header.required ?? false,
+                    schema: {
+                        type: 'string',
+                        example: header.example || ''
+                    }
+                });
+            });
+        }
+        // Only filter by modules if specified
+        const createDocOptions = config.modules?.length ? {
+            include: config.modules
+        } : {};
+        let document = _swagger.SwaggerModule.createDocument(app, builder.build(), createDocOptions);
+        // Filter out excluded tags
+        if (config.excludeTags?.length) {
+            document = filterDocumentByTags(document, config.excludeTags);
+        }
+        // Filter out excluded schema properties
+        if (config.excludeSchemaProperties?.length) {
+            document = filterSchemaProperties(document, config.excludeSchemaProperties);
+        }
+        // Filter out excluded query parameters
+        if (config.excludeQueryParameters?.length) {
+            document = filterQueryParameters(document, config.excludeQueryParameters);
+        }
+        _swagger.SwaggerModule.setup(config.path, app, document);
+    });
+}

package/cjs/docs/docs.setup.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "setupSwaggerDocs", {
+    enumerable: true,
+    get: function() {
+        return setupSwaggerDocs;
+    }
+});
+const _docsconfig = require("./docs.config");
+function setupSwaggerDocs(app, ...modules) {
+    (0, _docsconfig.setupModuleSwaggerDocs)(app, modules);
+}

package/cjs/docs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./docs.config"), exports);
+_export_star(require("./docs.setup"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}