@quanticjs/events-core 6.0.0

package/dist/DomainEvent.d.ts

@@ -0,0 +1,14 @@
+export interface DomainEventPayload {
+    [key: string]: unknown;
+}
+export declare class DomainEvent {
+    readonly eventType: string;
+    readonly aggregateId: string;
+    readonly payload: DomainEventPayload;
+    readonly organizationId?: string | undefined;
+    readonly routingKey?: string | undefined;
+    readonly eventId: string;
+    readonly occurredAt: Date;
+    constructor(eventType: string, aggregateId: string, payload: DomainEventPayload, organizationId?: string | undefined, routingKey?: string | undefined);
+    get topic(): string;
+}

package/dist/DomainEvent.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DomainEvent = void 0;
+const uuid_1 = require("uuid");
+class DomainEvent {
+    eventType;
+    aggregateId;
+    payload;
+    organizationId;
+    routingKey;
+    eventId;
+    occurredAt;
+    constructor(eventType, aggregateId, payload, organizationId, routingKey) {
+        this.eventType = eventType;
+        this.aggregateId = aggregateId;
+        this.payload = payload;
+        this.organizationId = organizationId;
+        this.routingKey = routingKey;
+        this.eventId = (0, uuid_1.v4)();
+        this.occurredAt = new Date();
+    }
+    get topic() {
+        const category = this.eventType.split('.')[0];
+        const base = `arex.events.${category}s`;
+        return this.routingKey ? `${base}.${this.routingKey}` : base;
+    }
+}
+exports.DomainEvent = DomainEvent;

package/dist/IEventPublisher.d.ts

@@ -0,0 +1,6 @@
+import { DomainEvent } from './DomainEvent';
+export interface IEventPublisher {
+    publish(event: DomainEvent): Promise<void>;
+    publishToDestination(destination: string, fields: Record<string, string>): Promise<string | null>;
+}
+export declare const EVENT_PUBLISHER: unique symbol;

package/dist/IEventPublisher.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_PUBLISHER = void 0;
+exports.EVENT_PUBLISHER = Symbol('EVENT_PUBLISHER');

package/dist/OutboxCleanupService.d.ts

@@ -0,0 +1,7 @@
+import { DataSource } from 'typeorm';
+export declare class OutboxCleanupService {
+    private readonly dataSource;
+    private readonly logger;
+    constructor(dataSource: DataSource);
+    cleanup(): Promise<void>;
+}

package/dist/OutboxCleanupService.js

@@ -0,0 +1,64 @@
+"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 OutboxCleanupService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxCleanupService = void 0;
+const common_1 = require("@nestjs/common");
+const schedule_1 = require("@nestjs/schedule");
+const typeorm_1 = require("typeorm");
+const OutboxEvent_entity_1 = require("./OutboxEvent.entity");
+const BATCH_SIZE = 1000;
+const BATCH_PAUSE_MS = 100;
+const RETENTION_DAYS = 7;
+let OutboxCleanupService = OutboxCleanupService_1 = class OutboxCleanupService {
+    dataSource;
+    logger = new common_1.Logger(OutboxCleanupService_1.name);
+    constructor(dataSource) {
+        this.dataSource = dataSource;
+    }
+    async cleanup() {
+        const repo = this.dataSource.getRepository(OutboxEvent_entity_1.OutboxEvent);
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - RETENTION_DAYS);
+        let totalDeleted = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const batch = await repo.find({
+                where: {
+                    status: OutboxEvent_entity_1.OutboxEventStatus.Published,
+                    publishedAt: (0, typeorm_1.LessThan)(cutoff),
+                },
+                take: BATCH_SIZE,
+            });
+            if (batch.length === 0)
+                break;
+            await repo.remove(batch);
+            totalDeleted += batch.length;
+            if (batch.length < BATCH_SIZE)
+                break;
+            await new Promise((resolve) => setTimeout(resolve, BATCH_PAUSE_MS));
+        }
+        if (totalDeleted > 0) {
+            this.logger.log(`Cleaned up ${totalDeleted} published outbox events`);
+        }
+    }
+};
+exports.OutboxCleanupService = OutboxCleanupService;
+__decorate([
+    (0, schedule_1.Cron)('0 3 * * *'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], OutboxCleanupService.prototype, "cleanup", null);
+exports.OutboxCleanupService = OutboxCleanupService = OutboxCleanupService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [typeorm_1.DataSource])
+], OutboxCleanupService);

package/dist/OutboxEvent.entity.d.ts

@@ -0,0 +1,18 @@
+export declare enum OutboxEventStatus {
+    Pending = "Pending",
+    Published = "Published",
+    Failed = "Failed"
+}
+export declare class OutboxEvent {
+    id: string;
+    eventType: string;
+    aggregateId: string;
+    topic: string;
+    payload: Record<string, unknown>;
+    organizationId: string | null;
+    status: OutboxEventStatus;
+    publishAttempts: number;
+    lastError: string | null;
+    createdAt: Date;
+    publishedAt: Date | null;
+}

package/dist/OutboxEvent.entity.js

@@ -0,0 +1,87 @@
+"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.OutboxEvent = exports.OutboxEventStatus = void 0;
+const typeorm_1 = require("typeorm");
+var OutboxEventStatus;
+(function (OutboxEventStatus) {
+    OutboxEventStatus["Pending"] = "Pending";
+    OutboxEventStatus["Published"] = "Published";
+    OutboxEventStatus["Failed"] = "Failed";
+})(OutboxEventStatus || (exports.OutboxEventStatus = OutboxEventStatus = {}));
+let OutboxEvent = class OutboxEvent {
+    id;
+    eventType;
+    aggregateId;
+    topic;
+    payload;
+    organizationId;
+    status;
+    publishAttempts;
+    lastError;
+    createdAt;
+    publishedAt;
+};
+exports.OutboxEvent = OutboxEvent;
+__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    __metadata("design:type", String)
+], OutboxEvent.prototype, "id", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'varchar' }),
+    __metadata("design:type", String)
+], OutboxEvent.prototype, "eventType", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'varchar' }),
+    __metadata("design:type", String)
+], OutboxEvent.prototype, "aggregateId", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'varchar' }),
+    __metadata("design:type", String)
+], OutboxEvent.prototype, "topic", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'jsonb' }),
+    __metadata("design:type", Object)
+], OutboxEvent.prototype, "payload", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'uuid', nullable: true }),
+    __metadata("design:type", Object)
+], OutboxEvent.prototype, "organizationId", void 0);
+__decorate([
+    (0, typeorm_1.Column)({
+        type: 'enum',
+        enum: OutboxEventStatus,
+        default: OutboxEventStatus.Pending,
+    }),
+    __metadata("design:type", String)
+], OutboxEvent.prototype, "status", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'int', default: 0 }),
+    __metadata("design:type", Number)
+], OutboxEvent.prototype, "publishAttempts", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'varchar', nullable: true }),
+    __metadata("design:type", Object)
+], OutboxEvent.prototype, "lastError", void 0);
+__decorate([
+    (0, typeorm_1.CreateDateColumn)({ type: 'timestamptz' }),
+    __metadata("design:type", Date)
+], OutboxEvent.prototype, "createdAt", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'timestamptz', nullable: true }),
+    __metadata("design:type", Object)
+], OutboxEvent.prototype, "publishedAt", void 0);
+exports.OutboxEvent = OutboxEvent = __decorate([
+    (0, typeorm_1.Entity)('outbox_events'),
+    (0, typeorm_1.Index)('idx_outbox_pending', ['status', 'createdAt'], {
+        where: `"status" = 'Pending'`,
+    })
+], OutboxEvent);

package/dist/OutboxPublisherService.d.ts

@@ -0,0 +1,14 @@
+import { OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { IEventPublisher } from './IEventPublisher';
+export declare class OutboxPublisherService implements OnModuleInit, OnModuleDestroy {
+    private readonly dataSource;
+    private readonly publisher;
+    private readonly logger;
+    private timer;
+    private processing;
+    constructor(dataSource: DataSource, publisher: IEventPublisher);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    private pollAndPublish;
+}

package/dist/OutboxPublisherService.js

@@ -0,0 +1,107 @@
+"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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var OutboxPublisherService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutboxPublisherService = void 0;
+const common_1 = require("@nestjs/common");
+const typeorm_1 = require("typeorm");
+const OutboxEvent_entity_1 = require("./OutboxEvent.entity");
+const IEventPublisher_1 = require("./IEventPublisher");
+const POLL_INTERVAL_MS = 100;
+const BATCH_SIZE = 50;
+const MAX_PUBLISH_ATTEMPTS = 5;
+const DLQ_DESTINATION = 'arex.events.dlq';
+let OutboxPublisherService = OutboxPublisherService_1 = class OutboxPublisherService {
+    dataSource;
+    publisher;
+    logger = new common_1.Logger(OutboxPublisherService_1.name);
+    timer = null;
+    processing = false;
+    constructor(dataSource, publisher) {
+        this.dataSource = dataSource;
+        this.publisher = publisher;
+    }
+    onModuleInit() {
+        this.timer = setInterval(() => this.pollAndPublish(), POLL_INTERVAL_MS);
+        this.logger.log(`Outbox publisher started (${POLL_INTERVAL_MS}ms poll interval)`);
+    }
+    onModuleDestroy() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.logger.log('Outbox publisher stopped');
+    }
+    async pollAndPublish() {
+        if (this.processing)
+            return;
+        this.processing = true;
+        try {
+            const repo = this.dataSource.getRepository(OutboxEvent_entity_1.OutboxEvent);
+            const events = await repo.find({
+                where: { status: OutboxEvent_entity_1.OutboxEventStatus.Pending },
+                order: { createdAt: 'ASC' },
+                take: BATCH_SIZE,
+            });
+            for (const event of events) {
+                try {
+                    await this.publisher.publishToDestination(event.topic, {
+                        eventId: event.id,
+                        eventType: event.eventType,
+                        aggregateId: event.aggregateId,
+                        organizationId: event.organizationId || '',
+                        payload: JSON.stringify(event.payload),
+                        occurredAt: event.createdAt.toISOString(),
+                    });
+                    event.status = OutboxEvent_entity_1.OutboxEventStatus.Published;
+                    event.publishedAt = new Date();
+                    await repo.save(event);
+                }
+                catch (error) {
+                    event.publishAttempts += 1;
+                    event.lastError = error.message;
+                    if (event.publishAttempts >= MAX_PUBLISH_ATTEMPTS) {
+                        event.status = OutboxEvent_entity_1.OutboxEventStatus.Failed;
+                        this.logger.error(`Event ${event.id} exceeded max attempts, routing to DLQ`);
+                        try {
+                            await this.publisher.publishToDestination(DLQ_DESTINATION, {
+                                eventId: event.id,
+                                eventType: event.eventType,
+                                aggregateId: event.aggregateId,
+                                error: event.lastError || 'unknown',
+                                payload: JSON.stringify(event.payload),
+                            });
+                        }
+                        catch {
+                            this.logger.error(`Failed to route event ${event.id} to DLQ`);
+                        }
+                    }
+                    await repo.save(event);
+                }
+            }
+        }
+        catch (error) {
+            this.logger.error('Outbox poll cycle failed', error.stack);
+        }
+        finally {
+            this.processing = false;
+        }
+    }
+};
+exports.OutboxPublisherService = OutboxPublisherService;
+exports.OutboxPublisherService = OutboxPublisherService = OutboxPublisherService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(IEventPublisher_1.EVENT_PUBLISHER)),
+    __metadata("design:paramtypes", [typeorm_1.DataSource, Object])
+], OutboxPublisherService);

package/dist/QuanticEventsCoreModule.d.ts

@@ -0,0 +1,4 @@
+import { DynamicModule } from '@nestjs/common';
+export declare class QuanticEventsCoreModule {
+    static forRoot(): DynamicModule;
+}

package/dist/QuanticEventsCoreModule.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 QuanticEventsCoreModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticEventsCoreModule = void 0;
+const common_1 = require("@nestjs/common");
+const OutboxPublisherService_1 = require("./OutboxPublisherService");
+const OutboxCleanupService_1 = require("./OutboxCleanupService");
+let QuanticEventsCoreModule = QuanticEventsCoreModule_1 = class QuanticEventsCoreModule {
+    static forRoot() {
+        return {
+            module: QuanticEventsCoreModule_1,
+            providers: [
+                OutboxPublisherService_1.OutboxPublisherService,
+                OutboxCleanupService_1.OutboxCleanupService,
+            ],
+            exports: [
+                OutboxPublisherService_1.OutboxPublisherService,
+                OutboxCleanupService_1.OutboxCleanupService,
+            ],
+        };
+    }
+};
+exports.QuanticEventsCoreModule = QuanticEventsCoreModule;
+exports.QuanticEventsCoreModule = QuanticEventsCoreModule = QuanticEventsCoreModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], QuanticEventsCoreModule);

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { DomainEvent } from './DomainEvent';
+export type { DomainEventPayload } from './DomainEvent';
+export { OutboxEvent, OutboxEventStatus } from './OutboxEvent.entity';
+export { IEventPublisher, EVENT_PUBLISHER } from './IEventPublisher';
+export { OutboxPublisherService } from './OutboxPublisherService';
+export { OutboxCleanupService } from './OutboxCleanupService';
+export { QuanticEventsCoreModule } from './QuanticEventsCoreModule';
+export { RenameStreamKeyToTopic1717700000000 } from './migrations/1717700000000-RenameStreamKeyToTopic';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenameStreamKeyToTopic1717700000000 = exports.QuanticEventsCoreModule = exports.OutboxCleanupService = exports.OutboxPublisherService = exports.EVENT_PUBLISHER = exports.OutboxEventStatus = exports.OutboxEvent = exports.DomainEvent = void 0;
+var DomainEvent_1 = require("./DomainEvent");
+Object.defineProperty(exports, "DomainEvent", { enumerable: true, get: function () { return DomainEvent_1.DomainEvent; } });
+var OutboxEvent_entity_1 = require("./OutboxEvent.entity");
+Object.defineProperty(exports, "OutboxEvent", { enumerable: true, get: function () { return OutboxEvent_entity_1.OutboxEvent; } });
+Object.defineProperty(exports, "OutboxEventStatus", { enumerable: true, get: function () { return OutboxEvent_entity_1.OutboxEventStatus; } });
+var IEventPublisher_1 = require("./IEventPublisher");
+Object.defineProperty(exports, "EVENT_PUBLISHER", { enumerable: true, get: function () { return IEventPublisher_1.EVENT_PUBLISHER; } });
+var OutboxPublisherService_1 = require("./OutboxPublisherService");
+Object.defineProperty(exports, "OutboxPublisherService", { enumerable: true, get: function () { return OutboxPublisherService_1.OutboxPublisherService; } });
+var OutboxCleanupService_1 = require("./OutboxCleanupService");
+Object.defineProperty(exports, "OutboxCleanupService", { enumerable: true, get: function () { return OutboxCleanupService_1.OutboxCleanupService; } });
+var QuanticEventsCoreModule_1 = require("./QuanticEventsCoreModule");
+Object.defineProperty(exports, "QuanticEventsCoreModule", { enumerable: true, get: function () { return QuanticEventsCoreModule_1.QuanticEventsCoreModule; } });
+var _1717700000000_RenameStreamKeyToTopic_1 = require("./migrations/1717700000000-RenameStreamKeyToTopic");
+Object.defineProperty(exports, "RenameStreamKeyToTopic1717700000000", { enumerable: true, get: function () { return _1717700000000_RenameStreamKeyToTopic_1.RenameStreamKeyToTopic1717700000000; } });

package/dist/migrations/1717700000000-RenameStreamKeyToTopic.d.ts

@@ -0,0 +1,6 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+export declare class RenameStreamKeyToTopic1717700000000 implements MigrationInterface {
+    name: string;
+    up(queryRunner: QueryRunner): Promise<void>;
+    down(queryRunner: QueryRunner): Promise<void>;
+}

package/dist/migrations/1717700000000-RenameStreamKeyToTopic.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenameStreamKeyToTopic1717700000000 = void 0;
+class RenameStreamKeyToTopic1717700000000 {
+    name = 'RenameStreamKeyToTopic1717700000000';
+    async up(queryRunner) {
+        await queryRunner.query(`ALTER TABLE outbox_events RENAME COLUMN stream_key TO topic`);
+        await queryRunner.query(`UPDATE outbox_events SET topic = REPLACE(topic, ':', '.')`);
+    }
+    async down(queryRunner) {
+        await queryRunner.query(`UPDATE outbox_events SET topic = REPLACE(topic, '.', ':')`);
+        await queryRunner.query(`ALTER TABLE outbox_events RENAME COLUMN topic TO stream_key`);
+    }
+}
+exports.RenameStreamKeyToTopic1717700000000 = RenameStreamKeyToTopic1717700000000;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@quanticjs/events-core",
+  "version": "6.0.0",
+  "description": "Transport-agnostic domain event abstractions — DomainEvent, OutboxEvent, IEventPublisher, outbox services",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "jest --passWithNoTests",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@quanticjs/core": "^6.0.0",
+    "uuid": "^11.1.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/schedule": "^5.0.0",
+    "typeorm": "^0.3.20"
+  }
+}