@flusys/nestjs-shared 0.1.0-beta.2 → 1.0.0-beta

package/README.md

@@ -32,8 +32,8 @@ This comprehensive guide covers the shared package - the shared NestJS infrastru
 - **Generic CRUD** - Standardized API controller and service patterns
 - **Permission System** - Role and permission-based access control
 - **Caching** - In-memory + Redis hybrid caching
-- **Request Correlation** - AsyncLocalStorage-based request tracking (NEW)
-- **Middleware** - Logging, correlation, and performance monitoring (NEW)
+- **Request Correlation** - AsyncLocalStorage-based request tracking
+- **Middleware** - Logging, correlation, and performance monitoring
 - **Interceptors** - Response metadata, idempotency, auto field setting
 - **Multi-Tenancy** - Dynamic database connection management
 - **Error Handling** - Centralized error handling utilities
@@ -462,23 +462,52 @@ export class ReportsController {
 }
 ```
 
-### @RequireAllPermissions
+### @RequirePermissionCondition
 
-Require all listed permissions:
+Build complex permission conditions with nested AND/OR logic:
 
 ```typescript
-import { RequireAllPermissions } from '@flusys/nestjs-shared/decorators';
+import { RequirePermissionCondition } from '@flusys/nestjs-shared/decorators';
 
 @Controller('sensitive')
 export class SensitiveController {
-  @RequireAllPermissions('admin.access', 'security.clearance')
-  @Get()
-  getSensitiveData() {
-    // Requires BOTH permissions
-  }
+  // Simple: User needs 'admin' OR 'manager'
+  @RequirePermissionCondition({
+    operator: 'or',
+    permissions: ['admin', 'manager'],
+  })
+  @Get('simple')
+  getSimpleData() {}
+
+  // Complex: User needs 'users.read' AND ('admin' OR 'manager')
+  @RequirePermissionCondition({
+    operator: 'and',
+    permissions: ['users.read'],
+    children: [
+      { operator: 'or', permissions: ['admin', 'manager'] }
+    ]
+  })
+  @Get('complex')
+  getComplexData() {}
+
+  // Very complex: (A AND B) OR (C AND D)
+  @RequirePermissionCondition({
+    operator: 'or',
+    children: [
+      { operator: 'and', permissions: ['finance.read', 'finance.write'] },
+      { operator: 'and', permissions: ['admin.full', 'reports.access'] }
+    ]
+  })
+  @Get('very-complex')
+  getVeryComplexData() {}
 }
 ```
 
+**Note:** For simple "require ALL permissions" use case, use `@RequirePermission` which defaults to AND logic:
+```typescript
+@RequirePermission('admin.access', 'security.clearance')  // User needs BOTH
+```
+
 ---
 
 ## Guards
@@ -586,7 +615,7 @@ PermissionModule.forRoot({
 
 ## Middleware
 
-### LoggerMiddleware (NEW - 2026-01-12, Enhanced - 2026-01-14)
+### LoggerMiddleware
 
 **Location:** `@flusys/nestjs-shared/middlewares/logger.middleware.ts`
 
@@ -1235,11 +1264,12 @@ import {
   Public,
   RequirePermission,
   RequireAnyPermission,
-  RequireAllPermissions,
+  RequirePermissionCondition,
 } from '@flusys/nestjs-shared/decorators';
 
 // Guards
 import {
+  JwtAuthGuard,
   PermissionGuard,
 } from '@flusys/nestjs-shared/guards';
 
@@ -1375,25 +1405,17 @@ async getPermissions(userId: string) {
 
 The `@flusys/nestjs-shared` package provides:
 
-✅ **Generic CRUD** - Consistent API patterns
-✅ **Permission System** - Flexible access control
-✅ **Caching** - High-performance data access
-✅ **Multi-Tenancy** - Database isolation
-✅ **Request Correlation** - AsyncLocalStorage-based tracking (NEW)
-✅ **Middleware** - Logging and performance monitoring (NEW)
-✅ **Interceptors** - Request/response processing
-✅ **Error Handling** - Centralized error management
+- **Generic CRUD** - Consistent API patterns
+- **Permission System** - Flexible access control
+- **Caching** - High-performance data access
+- **Multi-Tenancy** - Database isolation
+- **Request Correlation** - AsyncLocalStorage-based tracking
+- **Middleware** - Logging and performance monitoring
+- **Interceptors** - Request/response processing
+- **Error Handling** - Centralized error management
 
 This is the shared infrastructure layer used by all other Flusys packages.
 
 ---
 
-**Last Updated:** 2026-02-07
-**Recent Improvements:**
-- 2026-02-07: Documentation cleanup - removed outdated JWT configuration section, updated package architecture to match actual structure
-- 2026-01-14: Enhanced `LoggerMiddleware` with complete request/response details (URL, path, query, headers, user context)
-- 2026-01-14: Added multiple response hooks (send, json, end) for reliable response capture
-- 2026-01-14: Improved error logging with stack traces
-- 2026-01-12: Added `LoggerMiddleware` for request correlation and structured logging
-- 2026-01-12: Added AsyncLocalStorage-based request context (requestId, tenantId, userId, companyId)
-- 2026-01-13: Removed JWT config/constants (moved to auth-specific packages)
+**Last Updated:** 2026-02-16

package/cjs/classes/api-controller.class.js

@@ -117,9 +117,6 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
         delete: isGlobalSecurity ? defaultSecurity : normalizeSecurity(securityConfig?.delete)
     };
     let ApiController = class ApiController {
-        // =========================================================================
-        // INSERT (Single Item) - With Idempotency Support
-        // =========================================================================
         async insert(addDto, user) {
             const entity = await this.service.insert(addDto, user);
             const data = (0, _classtransformer.plainToInstance)(responseDtoClass, entity);
@@ -129,9 +126,6 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
                 data
             };
         }
-        // =========================================================================
-        // INSERT MANY (Bulk) - With Idempotency Support
-        // =========================================================================
         async insertMany(addDto, user) {
             const entities = await this.service.insertMany(addDto, user);
             const data = entities.map((item)=>(0, _classtransformer.plainToInstance)(responseDtoClass, item));
@@ -146,9 +140,6 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
                 }
             };
         }
-        // =========================================================================
-        // GET BY ID (Single Item)
-        // =========================================================================
         async getById(id, body, user) {
             const entity = await this.service.findById(id, user, body?.select);
             const data = (0, _classtransformer.plainToInstance)(responseDtoClass, entity);
@@ -158,9 +149,6 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
                 data
             };
         }
-        // =========================================================================
-        // UPDATE (Single Item)
-        // =========================================================================
         async update(updateDto, user) {
             const entity = await this.service.update(updateDto, user);
             const data = (0, _classtransformer.plainToInstance)(responseDtoClass, entity);
@@ -170,9 +158,6 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
                 data
             };
         }
-        // =========================================================================
-        // UPDATE MANY (Bulk)
-        // =========================================================================
         async updateMany(updateDtos, user) {
             const entities = await this.service.updateMany(updateDtos, user);
             const data = (0, _classtransformer.plainToInstance)(responseDtoClass, entities);
@@ -187,9 +172,6 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
                 }
             };
         }
-        // =========================================================================
-        // GET ALL (Paginated List)
-        // =========================================================================
         async getAll(filterAndPaginationDto, user, search) {
             const result = await this.service.getAll(search ?? '', filterAndPaginationDto, user);
             const data = (0, _classtransformer.plainToInstance)(responseDtoClass, result.data);
@@ -210,9 +192,6 @@ function createApiController(createDtoClass, updateDtoClass, responseDtoClass, o
                 }
             };
         }
-        // =========================================================================
-        // DELETE (Soft/Restore/Permanent)
-        // =========================================================================
         async delete(deleteDto, user) {
             await this.service.delete(deleteDto, user);
             const count = Array.isArray(deleteDto.id) ? deleteDto.id.length : 1;

package/cjs/classes/api-service.class.js

@@ -25,9 +25,6 @@ function _define_property(obj, key, value) {
     return obj;
 }
 let ApiService = class ApiService {
-    // ---------------------------------------------------------------------
-    // INSERT SINGLE ENTITY
-    // ---------------------------------------------------------------------
     async insert(dto, user) {
         await this.ensureRepositoryInitialized();
         const qr = this.repository.manager.connection.createQueryRunner();
@@ -54,9 +51,6 @@ let ApiService = class ApiService {
             await qr.release();
         }
     }
-    // ---------------------------------------------------------------------
-    // INSERT MULTIPLE ENTITIES
-    // ---------------------------------------------------------------------
     async insertMany(dtos, user) {
         await this.ensureRepositoryInitialized();
         const qr = this.repository.manager.connection.createQueryRunner();
@@ -87,9 +81,6 @@ let ApiService = class ApiService {
             await qr.release();
         }
     }
-    // ---------------------------------------------------------------------
-    // UPDATE SINGLE ENTITY
-    // ---------------------------------------------------------------------
     async update(dto, user) {
         await this.ensureRepositoryInitialized();
         const qr = this.repository.manager.connection.createQueryRunner();
@@ -116,9 +107,6 @@ let ApiService = class ApiService {
             await qr.release();
         }
     }
-    // ---------------------------------------------------------------------
-    // UPDATE MULTIPLE ENTITIES
-    // ---------------------------------------------------------------------
     async updateMany(dtos, user) {
         await this.ensureRepositoryInitialized();
         const qr = this.repository.manager.connection.createQueryRunner();
@@ -149,9 +137,6 @@ let ApiService = class ApiService {
             await qr.release();
         }
     }
-    // ---------------------------------------------------------------------
-    // FIND BY IDS
-    // ---------------------------------------------------------------------
     async findByIds(ids, user) {
         await this.ensureRepositoryInitialized();
         try {
@@ -176,9 +161,6 @@ let ApiService = class ApiService {
             this.handleError(error, 'findByIds');
         }
     }
-    // ---------------------------------------------------------------------
-    // FIND BY ID
-    // ---------------------------------------------------------------------
     async findById(id, user, select) {
         await this.ensureRepositoryInitialized();
         try {
@@ -217,9 +199,6 @@ let ApiService = class ApiService {
             this.handleError(error, 'findById');
         }
     }
-    // ---------------------------------------------------------------------
-    // GET ALL (WITH FILTER, SORT, SEARCH, PAGINATION & CACHING)
-    // ---------------------------------------------------------------------
     async getAll(search, filterAndPaginationDto, user) {
         await this.ensureRepositoryInitialized();
         try {
@@ -318,9 +297,6 @@ let ApiService = class ApiService {
             this.handleError(error, 'getAll');
         }
     }
-    // ---------------------------------------------------------------------
-    // DELETE / RESTORE / HARD DELETE
-    // ---------------------------------------------------------------------
     async delete(option, user) {
         await this.ensureRepositoryInitialized();
         const queryRunner = this.repository.manager.connection.createQueryRunner();
@@ -363,9 +339,7 @@ let ApiService = class ApiService {
             await queryRunner.release();
         }
     }
-    // ---------------------------------------------------------------------
-    // CACHING HELPERS
-    // ---------------------------------------------------------------------
+    // Caching
     async clearCacheForAll() {
         await this.utilsService.clearCache(this.entityName, this.cacheManager);
     }
@@ -380,17 +354,8 @@ let ApiService = class ApiService {
         });
         _errorhandlerutil.ErrorHandler.rethrowError(error);
     }
-    // ---------------------------------------------------------------------
-    // HOOKS / HELPERS (OVERRIDE IN CHILD CLASSES)
-    // ---------------------------------------------------------------------
-    /**
-   * Hook called before ANY repository access
-   * CRITICAL: Override this in REQUEST-scoped services that use lazy repository initialization
-   * Example use case: DataSource Provider pattern where repository is set dynamically
-   */ async ensureRepositoryInitialized() {
-    // Default: no-op - repository is already initialized in constructor
-    // Override in child classes that need lazy initialization
-    }
+    // Hooks (override in child classes)
+    async ensureRepositoryInitialized() {}
     async beforeInsertOperation(_dto, _user, _queryRunner) {}
     async afterInsertOperation(_entity, _user, _queryRunner) {}
     async beforeUpdateOperation(_dto, _user, _queryRunner) {}
@@ -439,9 +404,7 @@ let ApiService = class ApiService {
             isRaw: false
         };
     }
-    // ---------------------------------------------------------------------
-    // DTO <-> ENTITY CONVERSION
-    // ---------------------------------------------------------------------
+    // DTO conversion
     async convertRequestDtoToEntity(dto, user) {
         return Array.isArray(dto) ? await this.convertArrayDtoToEntities(dto, user) : [
             await this.convertSingleDtoToEntity(dto, user)

package/cjs/classes/request-scoped-api.service.js

@@ -30,18 +30,7 @@ function _ts_decorate(decorators, target, key, desc) {
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
 let RequestScopedApiService = class RequestScopedApiService extends _apiserviceclass.ApiService {
-    /**
-   * Ensures repository is initialized before any database access
-   * CRITICAL: Automatically called by ApiService before all CRUD operations
-   *
-   * This method:
-   * 1. Calls resolveEntity() to get the entity class
-   * 2. Calls getDataSourceProvider() to get the provider
-   * 3. Loads the repository from the provider
-   * 4. Marks initialization as complete
-   *
-   * @internal - Called automatically, do not call manually
-   */ async ensureRepositoryInitialized() {
+    async ensureRepositoryInitialized() {
         if (!this.repositoryInitialized) {
             const entity = this.resolveEntity();
             const provider = this.getDataSourceProvider();
@@ -49,26 +38,7 @@ let RequestScopedApiService = class RequestScopedApiService extends _apiservicec
             this.repositoryInitialized = true;
         }
     }
-    /**
-   * Helper method to initialize additional repositories
-   * Useful when service needs multiple repositories beyond the primary entity repository
-   *
-   * @param entities - Array of entity classes to load repositories for
-   * @returns Array of initialized repositories in the same order as entities
-   *
-   * @example
-   * ```typescript
-   * protected override async ensureRepositoryInitialized(): Promise<void> {
-   *   await super.ensureRepositoryInitialized();
-   *
-   *   if (this.configService.isCompanyFeatureEnabled() && !this.permissionRepository) {
-   *     [this.permissionRepository] = await this.initializeAdditionalRepositories([
-   *       UserCompanyPermission
-   *     ]);
-   *   }
-   * }
-   * ```
-   */ async initializeAdditionalRepositories(entities) {
+    /** Initialize additional repositories beyond the primary entity */ async initializeAdditionalRepositories(entities) {
         const provider = this.getDataSourceProvider();
         const repositories = [];
         for (const entity of entities){
@@ -76,31 +46,12 @@ let RequestScopedApiService = class RequestScopedApiService extends _apiservicec
         }
         return repositories;
     }
-    /**
-   * Helper method to get the DataSource
-   * Useful when service needs direct DataSource access for transactions or custom queries
-   *
-   * @returns DataSource instance
-   *
-   * @example
-   * ```typescript
-   * protected override async ensureRepositoryInitialized(): Promise<void> {
-   *   await super.ensureRepositoryInitialized();
-   *
-   *   if (!this.dataSource) {
-   *     this.dataSource = await this.getDataSourceForService();
-   *   }
-   * }
-   * ```
-   */ async getDataSourceForService() {
+    /** Get DataSource for direct access (transactions, custom queries) */ async getDataSourceForService() {
         const provider = this.getDataSourceProvider();
         return await provider.getDataSource();
     }
     constructor(...args){
-        super(...args), /**
-   * Tracks whether repository has been initialized
-   * Automatically managed by ensureRepositoryInitialized()
-   */ _define_property(this, "repositoryInitialized", false);
+        super(...args), _define_property(this, "repositoryInitialized", false);
     }
 };
 RequestScopedApiService = _ts_decorate([

package/cjs/classes/winston.logger.class.js

@@ -70,9 +70,7 @@ function _interop_require_wildcard(obj, nodeInterop) {
 }
 const Transport = _winstontransport.default || _winstontransport;
 const DailyRotateFile = _winstondailyrotatefile.default || _winstondailyrotatefile;
-// =============================================================================
-// CONFIGURATION (from envConfig)
-// =============================================================================
+// Configuration
 const logConfig = _config.envConfig.getLogConfig();
 const LOG_DIR = logConfig.dir;
 const LOG_LEVEL = logConfig.level;
@@ -85,9 +83,7 @@ if (!(0, _fs.existsSync)(LOG_DIR)) {
         recursive: true
     });
 }
-// =============================================================================
-// CUSTOM FORMATS
-// =============================================================================
+// Custom Formats
 /**
  * Custom format for structured logging
  * Includes: timestamp, level, context, requestId, userId, message, metadata
@@ -117,9 +113,7 @@ if (!(0, _fs.existsSync)(LOG_DIR)) {
     const stackTrace = stack ? `\n${stack}` : '';
     return `${timestamp} [${level.toUpperCase().padEnd(7)}] [${ctx}]${endpoint}${status}${time}${reqId}${user} ${message}${stackTrace}`;
 });
-// =============================================================================
-// TRANSPORTS
-// =============================================================================
+// Transports
 /**
  * Daily rotating file transport for all logs
  */ const combinedRotateTransport = new DailyRotateFile({
@@ -140,9 +134,7 @@ if (!(0, _fs.existsSync)(LOG_DIR)) {
     maxFiles: LOG_MAX_FILES,
     level: 'error'
 });
-// =============================================================================
-// TENANT-AWARE TRANSPORT
-// =============================================================================
+// Tenant-Aware Transport
 /**
  * Cache for tenant-specific transports
  * Avoids creating new transport instances for each log entry
@@ -208,9 +200,7 @@ if (!(0, _fs.existsSync)(LOG_DIR)) {
         stack: true
     }), devConsoleFormat)
 });
-// =============================================================================
-// LOGGER INSTANCES
-// =============================================================================
+// Logger Instances
 /**
  * Development logger configuration
  * - Console output with colors

package/cjs/constants/index.js

@@ -1,14 +1,5 @@
-/**
- * Constants for the common module
- *
- * This file centralizes all constants used across the module:
- * - Metadata keys for decorators
- * - Injection tokens for DI
- * - Header names
- */ // =============================================================================
-// METADATA KEYS (used with @SetMetadata decorator)
-// =============================================================================
-/** Metadata key for public routes (skip authentication) */ "use strict";
+// Metadata keys
+"use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
 });