@owox/backend 0.0.0

package/README.md

@@ -0,0 +1,144 @@
+# 🧭 Architecture Guidelines for Backend Application
+
+These guidelines define how to structure and organize the backend architecture for the project using NestJS, TypeORM, and clean layering principles.
+
+---
+
+This document also includes the conventions for organizing the application structure, including module layout, naming rules, and folder hierarchy.
+
+[modular monolith conventions](./MODULAR_CONVENTIONS.md).
+
+---
+
+## 🧱 Project Layers
+
+### 1. **Entity Layer**
+
+* Contains ORM entities (TypeORM `@Entity()` classes).
+* Entities model the database structure.
+* Only internal logic; **no external dependencies** like DTOs.
+
+### 2. **DTO Layer**
+
+#### a) **Domain DTOs**
+
+* Used within use-cases and services.
+* Belong to application/domain layer.
+* **Must not depend on API/CLI DTOs**.
+* **May depend on Entities**, but not on presentation-level DTOs.
+* Mapping into Domain DTOs is done via **non-static mappers**, not `fromEntity()` inside DTO.
+
+#### b) **API/CLI DTOs (Presentation DTOs)**
+
+* Presentation-specific output format (API, CLI, etc).
+* Belong to the presentation layer.
+* Can be mapped via **presentation mappers** (non-static).
+* Lower layers **may depend on upper layers**, but the domain layer must never depend on higher-level concerns.
+
+### 3. **Entity Service Layer**
+
+* Contains logic for a single entity (e.g., `UserService`).
+* Should interact only with the **corresponding repository**.
+* Can return both:
+
+    * `Entity` — for use-case services
+    * `Domain DTO` — for API/CLI usage (only if simple)
+* **Must not depend on other services or use-cases**.
+
+### 4. **Use-Case Service Layer**
+
+* Represents a single business scenario (e.g., `CreateUserService`, `GetUserWithPostsService`).
+* Should typically expose only one public method — usually named `run(...)`.
+* In more complex cases where multiple related operations are needed, it is acceptable to define several clearly named public methods instead of using `run(...)`.
+* Can depend on multiple entity services, repositories, or infrastructure services.
+* Returns a **Domain DTO**.
+* Does **not** return Entity directly.
+
+### 5. **Presentation Layer (Controller, CLI)**
+
+* Depends only on **use-case services** or entity services (for simple reads).
+* Receives or returns **presentation-specific DTOs**.
+* Must never operate on Entity directly.
+* Performs mapping to and from presentation DTOs using **non-static mappers**.
+
+### 6. **Infrastructure Layer**
+
+* Services to interact with email, queues, external APIs, files, etc.
+* Can be injected into use-case services.
+
+---
+
+## 📦 Mapping Conventions
+
+| Source     | Target      | How                  |
+| ---------- | ----------- | -------------------- |
+| Entity     | Domain DTO  | via dedicated mapper |
+| Domain DTO | API/CLI DTO | via dedicated mapper |
+
+> 📌 **Do not place `fromEntity()` or `fromDomain()` inside DTOs**, and avoid doing mapping inside services as well.
+> Use dedicated **mapper classes** to convert between layers.
+
+> 🧩 Naming and grouping of mappers (e.g., one vs many) — left to the team's discretion.
+
+---
+
+## ✅ Best Practices
+
+* Keep **Entity Services** focused per entity.
+* Use **Use-Case Services** for all orchestrations across domains.
+* Structure code to allow **reuse across API, CLI, cron, etc.**
+* Prefer **explicit DTOs** at every boundary.
+* Maintain **one scenario = one use-case service** with a single `.run()` method.
+* Avoid returning Entity from any service that crosses layers.
+* Domain DTOs may depend on Entity, but never on presentation DTOs.
+* API/CLI DTOs may depend on Domain DTOs, but never the other way around.
+* Entity Services **must not depend** on Use-Case Services or other Entity Services.
+* Use-case services **can depend** on multiple Entity Services and Repositories.
+* Controllers and CLI commands must **never see Entities**.
+* Use **dedicated mapper classes** instead of placing logic inside DTOs.
+
+---
+
+## 📁 Suggested Folder Structure
+
+```
+src/
+  users/
+    entities/
+      user.entity.ts
+    services/
+      user.service.ts
+    use-cases/
+      get-user.service.ts
+    dto/
+      domain/                # Domain DTOs (used in use-cases)
+        user-domain.dto.ts
+      presentation/          # API/CLI DTOs
+        user-api-response.dto.ts
+        user-cli-response.dto.ts
+    mappers/
+      user.mapper.ts         # Contains conversion logic between layers
+    enums/
+      user-role.enum.ts
+    controllers/
+      user.controller.ts
+```
+
+### 📌 Notes:
+
+* Domain DTOs are stored under `dto/domain/` — they are part of the application layer.
+* Presentation-layer DTOs are stored under `dto/presentation/` — used in API/CLI.
+* Each module (e.g., `users/`) is a self-contained feature with clearly organized responsibilities.
+* Mapping logic is implemented in `mappers/` folder per feature.
+
+---
+
+## 🔚 Summary
+
+This architecture encourages:
+
+* Separation of concerns
+* Clear ownership of logic
+* Readable, testable, and maintainable code
+
+Following these guidelines will help create a codebase that is easy to extend, open to the community, and maintainable in the long term.

package/dist/app.module.js

@@ -0,0 +1,39 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppModule = void 0;
+const path = require("path");
+const common_1 = require("@nestjs/common");
+const typeorm_1 = require("@nestjs/typeorm");
+const config_1 = require("@nestjs/config");
+const schedule_1 = require("@nestjs/schedule");
+const database_config_1 = require("./config/database.config");
+const data_marts_module_1 = require("./data-marts/data-marts.module");
+const common_module_1 = require("./common/common.module");
+let AppModule = class AppModule {
+};
+exports.AppModule = AppModule;
+exports.AppModule = AppModule = __decorate([
+    (0, common_1.Module)({
+        imports: [
+            config_1.ConfigModule.forRoot({
+                isGlobal: true,
+                envFilePath: path.resolve(__dirname, '../../../.env'),
+            }),
+            typeorm_1.TypeOrmModule.forRootAsync({
+                imports: [config_1.ConfigModule],
+                inject: [config_1.ConfigService],
+                useFactory: database_config_1.getDatabaseConfig,
+            }),
+            schedule_1.ScheduleModule.forRoot(),
+            data_marts_module_1.DataMartsModule,
+            common_module_1.CommonModule,
+        ],
+    })
+], AppModule);
+//# sourceMappingURL=app.module.js.map

package/dist/common/authorization-context/authorization.context.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthContext = void 0;
+const common_1 = require("@nestjs/common");
+exports.AuthContext = (0, common_1.createParamDecorator)((data, ctx) => {
+    const fillStub = process.env.FILL_AUTH_CONTEXT === undefined || process.env.FILL_AUTH_CONTEXT === '1';
+    if (fillStub) {
+        return { projectId: '0', userId: '0' };
+    }
+    const request = ctx.switchToHttp().getRequest();
+    const projectId = request.headers['x-project'];
+    const userId = request.headers['x-user'];
+    if (!userId) {
+        throw new common_1.BadRequestException('Missing X-User header');
+    }
+    if (!projectId) {
+        throw new common_1.BadRequestException('Missing X-Project header');
+    }
+    return { projectId, userId };
+});
+//# sourceMappingURL=authorization.context.js.map

package/dist/common/common.module.js

@@ -0,0 +1,21 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommonModule = void 0;
+const common_1 = require("@nestjs/common");
+const scheduler_module_1 = require("./scheduler/scheduler.module");
+let CommonModule = class CommonModule {
+};
+exports.CommonModule = CommonModule;
+exports.CommonModule = CommonModule = __decorate([
+    (0, common_1.Module)({
+        imports: [scheduler_module_1.SchedulerModule],
+        exports: [scheduler_module_1.SchedulerModule],
+    })
+], CommonModule);
+//# sourceMappingURL=common.module.js.map

package/dist/common/exceptions/access-validation.exception.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessValidationException = void 0;
+const business_violation_exception_1 = require("./business-violation.exception");
+class AccessValidationException extends business_violation_exception_1.BusinessViolationException {
+    message;
+    errorDetails;
+    constructor(message, errorDetails) {
+        super(message, errorDetails);
+        this.message = message;
+        this.errorDetails = errorDetails;
+    }
+}
+exports.AccessValidationException = AccessValidationException;
+//# sourceMappingURL=access-validation.exception.js.map

package/dist/common/exceptions/base-exception.filter.js

@@ -0,0 +1,30 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseExceptionFilter = void 0;
+const common_1 = require("@nestjs/common");
+const business_violation_exception_1 = require("./business-violation.exception");
+let BaseExceptionFilter = class BaseExceptionFilter {
+    catch(exception, host) {
+        const ctx = host.switchToHttp();
+        const response = ctx.getResponse();
+        const request = ctx.getRequest();
+        response.status(common_1.HttpStatus.BAD_REQUEST).json({
+            statusCode: common_1.HttpStatus.BAD_REQUEST,
+            timestamp: new Date().toISOString(),
+            path: request.url,
+            message: exception.message,
+            errorDetails: exception.errorDetails,
+        });
+    }
+};
+exports.BaseExceptionFilter = BaseExceptionFilter;
+exports.BaseExceptionFilter = BaseExceptionFilter = __decorate([
+    (0, common_1.Catch)(business_violation_exception_1.BusinessViolationException)
+], BaseExceptionFilter);
+//# sourceMappingURL=base-exception.filter.js.map

package/dist/common/exceptions/base.exception.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=base.exception.js.map

package/dist/common/exceptions/business-violation.exception.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BusinessViolationException = void 0;
+class BusinessViolationException extends Error {
+    message;
+    errorDetails;
+    constructor(message, errorDetails) {
+        super(message);
+        this.message = message;
+        this.errorDetails = errorDetails;
+    }
+}
+exports.BusinessViolationException = BusinessViolationException;
+//# sourceMappingURL=business-violation.exception.js.map

package/dist/common/resolver/type-resolver.js

@@ -0,0 +1,33 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeResolver = void 0;
+const common_1 = require("@nestjs/common");
+let TypeResolver = class TypeResolver {
+    map = new Map();
+    constructor(components) {
+        for (const c of components) {
+            this.map.set(c.type, c);
+        }
+    }
+    resolve(type) {
+        const component = this.map.get(type);
+        if (!component)
+            throw new Error(`No component found for type: ${type}`);
+        return component;
+    }
+};
+exports.TypeResolver = TypeResolver;
+exports.TypeResolver = TypeResolver = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Array])
+], TypeResolver);
+//# sourceMappingURL=type-resolver.js.map

package/dist/common/resolver/typed-component.resolver.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=typed-component.resolver.js.map

package/dist/common/scheduler/facades/scheduler-facade.impl.js

@@ -0,0 +1,55 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var SchedulerFacadeImpl_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulerFacadeImpl = void 0;
+const common_1 = require("@nestjs/common");
+const schedule_1 = require("@nestjs/schedule");
+const cron_1 = require("cron");
+const system_time_service_1 = require("../services/system-time.service");
+const config_1 = require("@nestjs/config");
+const trigger_runner_factory_1 = require("../services/runners/trigger-runner.factory");
+const time_based_trigger_fetcher_factory_1 = require("../services/fetchers/time-based-trigger-fetcher.factory");
+let SchedulerFacadeImpl = SchedulerFacadeImpl_1 = class SchedulerFacadeImpl {
+    schedulerRegistry;
+    configService;
+    triggerFetcherFactory;
+    triggerRunnerFactory;
+    systemTimeService;
+    logger = new common_1.Logger(SchedulerFacadeImpl_1.name);
+    defaultTimezone = 'UTC';
+    constructor(schedulerRegistry, configService, triggerFetcherFactory, triggerRunnerFactory, systemTimeService) {
+        this.schedulerRegistry = schedulerRegistry;
+        this.configService = configService;
+        this.triggerFetcherFactory = triggerFetcherFactory;
+        this.triggerRunnerFactory = triggerRunnerFactory;
+        this.systemTimeService = systemTimeService;
+    }
+    async registerTimeBasedTriggerHandler(triggerHandler) {
+        const runner = await this.triggerRunnerFactory.createRunner(triggerHandler, this.systemTimeService);
+        const fetcher = this.triggerFetcherFactory.createFetcher(triggerHandler.getTriggerRepository(), this.systemTimeService);
+        const timezone = this.configService.get('SCHEDULER_TIMEZONE', this.defaultTimezone);
+        const job = new cron_1.CronJob(triggerHandler.processingCronExpression(), () => fetcher.fetchTriggersReadyForProcessing().then(triggers => runner.runTriggers(triggers)), null, false, timezone);
+        this.schedulerRegistry.addCronJob(triggerHandler.constructor.name, job);
+        job.start();
+        this.logger.log(`Time-based trigger handler '${triggerHandler.constructor.name}' initialized '${triggerHandler.processingCronExpression()}' ${timezone}`);
+    }
+};
+exports.SchedulerFacadeImpl = SchedulerFacadeImpl;
+exports.SchedulerFacadeImpl = SchedulerFacadeImpl = SchedulerFacadeImpl_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [schedule_1.SchedulerRegistry,
+        config_1.ConfigService,
+        time_based_trigger_fetcher_factory_1.TimeBasedTriggerFetcherFactory,
+        trigger_runner_factory_1.TriggerRunnerFactory,
+        system_time_service_1.SystemTimeService])
+], SchedulerFacadeImpl);
+//# sourceMappingURL=scheduler-facade.impl.js.map

package/dist/common/scheduler/scheduler.module.js

@@ -0,0 +1,32 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulerModule = void 0;
+const common_1 = require("@nestjs/common");
+const scheduler_facade_impl_1 = require("./facades/scheduler-facade.impl");
+const scheduler_facade_1 = require("./shared/scheduler.facade");
+const trigger_runner_factory_1 = require("./services/runners/trigger-runner.factory");
+const system_time_service_1 = require("./services/system-time.service");
+const time_based_trigger_fetcher_factory_1 = require("./services/fetchers/time-based-trigger-fetcher.factory");
+const graceful_shutdown_service_1 = require("./services/graceful-shutdown.service");
+let SchedulerModule = class SchedulerModule {
+};
+exports.SchedulerModule = SchedulerModule;
+exports.SchedulerModule = SchedulerModule = __decorate([
+    (0, common_1.Module)({
+        providers: [
+            { provide: scheduler_facade_1.SCHEDULER_FACADE, useClass: scheduler_facade_impl_1.SchedulerFacadeImpl },
+            time_based_trigger_fetcher_factory_1.TimeBasedTriggerFetcherFactory,
+            trigger_runner_factory_1.TriggerRunnerFactory,
+            system_time_service_1.SystemTimeService,
+            graceful_shutdown_service_1.GracefulShutdownService,
+        ],
+        exports: [scheduler_facade_1.SCHEDULER_FACADE],
+    })
+], SchedulerModule);
+//# sourceMappingURL=scheduler.module.js.map

package/dist/common/scheduler/services/fetchers/time-based-trigger-fetcher.factory.js

@@ -0,0 +1,24 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var TimeBasedTriggerFetcherFactory_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeBasedTriggerFetcherFactory = void 0;
+const common_1 = require("@nestjs/common");
+const time_based_trigger_fetcher_service_1 = require("./time-based-trigger-fetcher.service");
+let TimeBasedTriggerFetcherFactory = TimeBasedTriggerFetcherFactory_1 = class TimeBasedTriggerFetcherFactory {
+    logger = new common_1.Logger(TimeBasedTriggerFetcherFactory_1.name);
+    createFetcher(repository, systemTimeService) {
+        this.logger.log(`[${repository.metadata.name}] Creating TimeBasedTriggerFetcherService`);
+        return new time_based_trigger_fetcher_service_1.TimeBasedTriggerFetcherService(repository, systemTimeService);
+    }
+};
+exports.TimeBasedTriggerFetcherFactory = TimeBasedTriggerFetcherFactory;
+exports.TimeBasedTriggerFetcherFactory = TimeBasedTriggerFetcherFactory = TimeBasedTriggerFetcherFactory_1 = __decorate([
+    (0, common_1.Injectable)()
+], TimeBasedTriggerFetcherFactory);
+//# sourceMappingURL=time-based-trigger-fetcher.factory.js.map

package/dist/common/scheduler/services/fetchers/time-based-trigger-fetcher.service.js

@@ -0,0 +1,82 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var TimeBasedTriggerFetcherService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeBasedTriggerFetcherService = void 0;
+const common_1 = require("@nestjs/common");
+const time_based_trigger_entity_1 = require("../../shared/entities/time-based-trigger.entity");
+const system_time_service_1 = require("../system-time.service");
+const typeorm_1 = require("typeorm");
+let TimeBasedTriggerFetcherService = TimeBasedTriggerFetcherService_1 = class TimeBasedTriggerFetcherService {
+    repository;
+    systemClock;
+    logger = new common_1.Logger(TimeBasedTriggerFetcherService_1.name);
+    entityName;
+    constructor(repository, systemClock) {
+        this.repository = repository;
+        this.systemClock = systemClock;
+        this.entityName = this.repository.metadata.name;
+    }
+    async fetchTriggersReadyForProcessing() {
+        this.logger.debug(`[${this.entityName}] Fetching triggers ready for processing.`);
+        const startTime = this.systemClock.now();
+        try {
+            const triggers = await this.findTriggersReadyForProcessing(startTime);
+            return await this.markTriggersAsReady(triggers);
+        }
+        catch (error) {
+            this.logCriticalFailure(error);
+        }
+        return [];
+    }
+    async markTriggersAsReady(triggers) {
+        const triggersToProcess = [];
+        for (let i = 0; i < triggers.length; i++) {
+            const trigger = triggers[i];
+            try {
+                trigger.status = time_based_trigger_entity_1.TriggerStatus.READY;
+                await this.repository.save(trigger);
+                triggersToProcess.push(trigger);
+            }
+            catch (error) {
+                if (error instanceof typeorm_1.OptimisticLockVersionMismatchError) {
+                    this.logger.log(`[${this.entityName}] Optimistic lock conflict for trigger ${trigger.id}. Skipping as likely processed by another instance.`);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        return triggersToProcess;
+    }
+    async findTriggersReadyForProcessing(currentTime) {
+        return this.repository
+            .createQueryBuilder('t')
+            .where('t.nextRunTimestamp IS NOT NULL')
+            .andWhere('t.nextRunTimestamp <= :currentTime', { currentTime })
+            .andWhere('t.isActive = true')
+            .andWhere('t.status = :status', { status: time_based_trigger_entity_1.TriggerStatus.IDLE })
+            .orderBy('t.nextRunTimestamp', 'ASC')
+            .getMany();
+    }
+    logCriticalFailure(error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        const errorStack = error instanceof Error ? error.stack : undefined;
+        this.logger.error(`[${this.entityName}] Critical failure in dispatcher: ${errorMessage}`, errorStack);
+    }
+};
+exports.TimeBasedTriggerFetcherService = TimeBasedTriggerFetcherService;
+exports.TimeBasedTriggerFetcherService = TimeBasedTriggerFetcherService = TimeBasedTriggerFetcherService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [typeorm_1.Repository,
+        system_time_service_1.SystemTimeService])
+], TimeBasedTriggerFetcherService);
+//# sourceMappingURL=time-based-trigger-fetcher.service.js.map

package/dist/common/scheduler/services/graceful-shutdown.service.js

@@ -0,0 +1,96 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var GracefulShutdownService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GracefulShutdownService = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+let GracefulShutdownService = GracefulShutdownService_1 = class GracefulShutdownService {
+    configService;
+    logger = new common_1.Logger(GracefulShutdownService_1.name);
+    isShuttingDown = false;
+    shutdownPromise = null;
+    shutdownResolve = null;
+    activeProcesses = new Map();
+    shutdownTimeoutMinutes;
+    constructor(configService) {
+        this.configService = configService;
+        this.shutdownTimeoutMinutes = this.configService.get('SCHEDULER_GRACEFUL_SHUTDOWN_TIMEOUT_MINUTES', 15);
+        this.logger.log(`Graceful shutdown timeout set to ${this.shutdownTimeoutMinutes}m`);
+    }
+    isInShutdownMode() {
+        return this.isShuttingDown;
+    }
+    registerActiveProcess(processId) {
+        this.activeProcesses.set(processId, {
+            id: processId,
+            startTime: new Date(),
+        });
+        this.logger.debug(`Registered active process: ${processId}. Total active: ${this.activeProcesses.size}`);
+        return processId;
+    }
+    unregisterActiveProcess(processId) {
+        if (this.activeProcesses.has(processId)) {
+            this.activeProcesses.delete(processId);
+            this.logger.debug(`Unregistered process: ${processId}. Remaining active: ${this.activeProcesses.size}`);
+            if (this.isShuttingDown && this.activeProcesses.size === 0) {
+                this.logger.log('All active processes completed, finalizing shutdown');
+                this.completeShutdown();
+            }
+        }
+    }
+    async initiateShutdown() {
+        if (this.isShuttingDown) {
+            return this.shutdownPromise;
+        }
+        this.isShuttingDown = true;
+        this.logger.log(`Graceful shutdown initiated. Active processes: ${this.activeProcesses.size}`);
+        if (this.activeProcesses.size === 0) {
+            this.logger.log('No active processes, completing shutdown immediately');
+            this.shutdownPromise = Promise.resolve();
+            return this.shutdownPromise;
+        }
+        this.shutdownPromise = new Promise(resolve => {
+            this.shutdownResolve = resolve;
+            setTimeout(() => {
+                if (this.isShuttingDown && this.shutdownResolve) {
+                    const remainingProcesses = this.activeProcesses.size;
+                    if (remainingProcesses > 0) {
+                        this.logger.warn(`Forcing shutdown after timeout of ${this.shutdownTimeoutMinutes}m. ${remainingProcesses} processes still active.`);
+                        this.activeProcesses.forEach((process, id) => {
+                            const durationMs = new Date().getTime() - process.startTime.getTime();
+                            const durationMinutes = Math.round((durationMs / 60000) * 10) / 10;
+                            this.logger.warn(`Process ${id} has been running for ${durationMinutes}m`);
+                        });
+                    }
+                    this.shutdownResolve();
+                }
+            }, this.shutdownTimeoutMinutes * 60 * 1000);
+        });
+        return this.shutdownPromise;
+    }
+    completeShutdown() {
+        if (this.isShuttingDown && this.shutdownResolve) {
+            this.logger.log('Graceful shutdown completed');
+            this.shutdownResolve();
+            this.shutdownResolve = null;
+        }
+    }
+    async onModuleDestroy() {
+        await this.initiateShutdown();
+    }
+};
+exports.GracefulShutdownService = GracefulShutdownService;
+exports.GracefulShutdownService = GracefulShutdownService = GracefulShutdownService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [config_1.ConfigService])
+], GracefulShutdownService);
+//# sourceMappingURL=graceful-shutdown.service.js.map