@quanticjs/events-kafka 6.0.0

package/dist/KafkaEvent.d.ts

@@ -0,0 +1,13 @@
+export interface KafkaEvent {
+    id: string;
+    type: string;
+    version: number;
+    aggregateId: string;
+    organizationId?: string;
+    timestamp: string;
+    payload: Record<string, unknown>;
+}
+export interface KafkaEventsModuleOptions {
+    brokers: string[];
+    clientId: string;
+}

package/dist/KafkaEvent.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/KafkaEventConsumer.d.ts

@@ -0,0 +1,24 @@
+import { Logger, OnModuleInit, OnModuleDestroy, OnApplicationBootstrap } from '@nestjs/common';
+import { KafkaEvent } from './KafkaEvent';
+export declare abstract class KafkaEventConsumer implements OnModuleInit, OnModuleDestroy, OnApplicationBootstrap {
+    private readonly brokers;
+    private readonly clientId;
+    protected readonly logger: Logger;
+    abstract readonly topic: string;
+    abstract readonly groupId: string;
+    abstract handleMessage(event: KafkaEvent): Promise<void>;
+    protected shouldHandle(_event: KafkaEvent): boolean;
+    private readonly tracer;
+    private consumer;
+    private producer;
+    private kafka;
+    private heartbeatFn;
+    constructor(brokers: string[], clientId: string);
+    protected heartbeat(): void;
+    onModuleInit(): Promise<void>;
+    onApplicationBootstrap(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    private processMessage;
+    private processWithSpan;
+    private routeToDlq;
+}

package/dist/KafkaEventConsumer.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KafkaEventConsumer = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@quanticjs/core");
+const kafka_javascript_1 = require("@confluentinc/kafka-javascript");
+const MAX_RETRIES = 5;
+const MAX_BACKOFF_MS = 30000;
+class KafkaEventConsumer {
+    brokers;
+    clientId;
+    logger = new common_1.Logger(this.constructor.name);
+    shouldHandle(_event) {
+        return true;
+    }
+    tracer = (0, core_1.getTracer)('@quanticjs/events-kafka');
+    consumer = null;
+    producer = null;
+    kafka = null;
+    heartbeatFn = null;
+    constructor(brokers, clientId) {
+        this.brokers = brokers;
+        this.clientId = clientId;
+    }
+    heartbeat() {
+        this.heartbeatFn?.();
+    }
+    async onModuleInit() {
+        this.kafka = new kafka_javascript_1.KafkaJS.Kafka({
+            'bootstrap.servers': this.brokers.join(','),
+            'client.id': this.clientId,
+        });
+        this.consumer = this.kafka.consumer({
+            'group.id': this.groupId,
+            'session.timeout.ms': 45000,
+            'heartbeat.interval.ms': 5000,
+            'fetch.wait.max.ms': 1000,
+            'partition.assignment.strategy': 'roundrobin',
+            'enable.auto.commit': false,
+        });
+        this.producer = this.kafka.producer({
+            'compression.type': 'lz4',
+        });
+        await this.consumer.connect();
+        await this.producer.connect();
+        await this.consumer.subscribe({ topic: this.topic });
+        this.logger.log(`Subscribed to ${this.topic} as ${this.groupId}`);
+    }
+    async onApplicationBootstrap() {
+        if (!this.consumer)
+            return;
+        void this.consumer.run({
+            eachMessage: async ({ topic, partition, message, heartbeat }) => {
+                this.heartbeatFn = heartbeat;
+                try {
+                    await this.processMessage(topic, partition, message);
+                }
+                finally {
+                    this.heartbeatFn = null;
+                }
+            },
+        });
+        this.logger.log(`Consumer started for ${this.topic}`);
+    }
+    async onModuleDestroy() {
+        if (this.consumer) {
+            await this.consumer.disconnect();
+            this.consumer = null;
+        }
+        if (this.producer) {
+            await this.producer.disconnect();
+            this.producer = null;
+        }
+        this.logger.log(`Consumer disconnected from ${this.topic}`);
+    }
+    async processMessage(topic, partition, message) {
+        const raw = message.value?.toString();
+        if (!raw)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            this.logger.error(`Invalid JSON in message on ${topic}:${partition}`);
+            return;
+        }
+        const event = {
+            id: parsed.id || '',
+            type: parsed.type || '',
+            version: parsed.version ?? 1,
+            aggregateId: parsed.aggregateId || '',
+            organizationId: parsed.organizationId,
+            timestamp: parsed.timestamp || '',
+            payload: parsed.payload || {},
+        };
+        if (!this.shouldHandle(event))
+            return;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                await this.processWithSpan(topic, partition, message, event);
+                return;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                if (attempt < MAX_RETRIES) {
+                    const delay = Math.min(1000 * Math.pow(2, attempt) + Math.floor(Math.random() * 1000), MAX_BACKOFF_MS);
+                    this.logger.warn(`Retry ${attempt + 1}/${MAX_RETRIES} for ${event.type} on ${topic}:${partition} in ${delay}ms: ${err.message}`);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+                else {
+                    this.logger.error(`Dead-lettering ${event.type} on ${topic}:${partition} after ${MAX_RETRIES} retries: ${err.message}`);
+                    await this.routeToDlq(topic, partition, message, event, err);
+                }
+            }
+        }
+    }
+    async processWithSpan(topic, partition, message, event) {
+        if (!this.tracer) {
+            return this.handleMessage(event);
+        }
+        const spanName = `${topic} process`;
+        return this.tracer.startActiveSpan(spanName, async (span) => {
+            span.setAttribute('messaging.system', 'kafka');
+            span.setAttribute('messaging.destination', topic);
+            span.setAttribute('messaging.kafka.partition', partition);
+            span.setAttribute('messaging.message_id', event.id);
+            if (event.type)
+                span.setAttribute('messaging.event_type', event.type);
+            try {
+                await this.handleMessage(event);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                span.setStatus({ code: core_1.SPAN_STATUS_ERROR, message: err.message });
+                span.recordException(err);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    async routeToDlq(topic, partition, message, event, error) {
+        if (!this.producer)
+            return;
+        const dlqTopic = `${topic}.dlq`;
+        const dlqPayload = {
+            originalTopic: topic,
+            originalPartition: partition,
+            originalOffset: message.offset,
+            type: event.type,
+            payload: event.payload,
+            attempts: MAX_RETRIES,
+            lastError: error.message,
+            deadLetteredAt: new Date().toISOString(),
+        };
+        try {
+            await this.producer.send({
+                topic: dlqTopic,
+                messages: [
+                    {
+                        key: event.aggregateId || null,
+                        value: JSON.stringify(dlqPayload),
+                    },
+                ],
+            });
+            this.logger.log(`Routed ${event.type} to ${dlqTopic}`);
+        }
+        catch (dlqError) {
+            this.logger.error(`Failed to route to DLQ ${dlqTopic}: ${dlqError.message}`);
+        }
+    }
+}
+exports.KafkaEventConsumer = KafkaEventConsumer;

package/dist/KafkaEventPublisher.d.ts

@@ -0,0 +1,20 @@
+import { OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { IEventPublisher, DomainEvent } from '@quanticjs/events-core';
+declare const KAFKA_OPTIONS: unique symbol;
+export { KAFKA_OPTIONS };
+export interface KafkaPublisherConfig {
+    brokers: string[];
+    clientId: string;
+}
+export declare class KafkaEventPublisher implements IEventPublisher, OnModuleInit, OnModuleDestroy {
+    private readonly config;
+    private readonly logger;
+    private producer;
+    private kafka;
+    constructor(config: KafkaPublisherConfig);
+    onModuleInit(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    publish(event: DomainEvent): Promise<void>;
+    publishToDestination(destination: string, fields: Record<string, string>): Promise<string | null>;
+    private produceMessage;
+}

package/dist/KafkaEventPublisher.js

@@ -0,0 +1,93 @@
+"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 KafkaEventPublisher_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KafkaEventPublisher = exports.KAFKA_OPTIONS = void 0;
+const common_1 = require("@nestjs/common");
+const kafka_javascript_1 = require("@confluentinc/kafka-javascript");
+const KAFKA_OPTIONS = Symbol('KAFKA_OPTIONS');
+exports.KAFKA_OPTIONS = KAFKA_OPTIONS;
+let KafkaEventPublisher = KafkaEventPublisher_1 = class KafkaEventPublisher {
+    config;
+    logger = new common_1.Logger(KafkaEventPublisher_1.name);
+    producer = null;
+    kafka = null;
+    constructor(config) {
+        this.config = config;
+    }
+    async onModuleInit() {
+        this.kafka = new kafka_javascript_1.KafkaJS.Kafka({
+            'bootstrap.servers': this.config.brokers.join(','),
+            'client.id': this.config.clientId,
+        });
+        this.producer = this.kafka.producer({
+            'compression.type': 'lz4',
+        });
+        await this.producer.connect();
+        this.logger.log('Kafka producer connected');
+    }
+    async onModuleDestroy() {
+        if (this.producer) {
+            await this.producer.disconnect();
+            this.producer = null;
+            this.logger.log('Kafka producer disconnected');
+        }
+    }
+    async publish(event) {
+        const envelope = {
+            id: event.eventId,
+            type: event.eventType,
+            version: 1,
+            aggregateId: event.aggregateId,
+            organizationId: event.organizationId,
+            timestamp: event.occurredAt.toISOString(),
+            payload: event.payload,
+        };
+        await this.produceMessage(event.topic, event.aggregateId, envelope);
+    }
+    async publishToDestination(destination, fields) {
+        if (!this.producer) {
+            this.logger.warn('Kafka producer not connected, skipping publish');
+            return null;
+        }
+        const result = await this.producer.send({
+            topic: destination,
+            messages: [
+                {
+                    key: fields.aggregateId || null,
+                    value: JSON.stringify(fields),
+                },
+            ],
+        });
+        const offset = result?.[0]?.offset;
+        return offset != null ? String(offset) : null;
+    }
+    async produceMessage(topic, key, value) {
+        if (!this.producer) {
+            this.logger.warn('Kafka producer not connected, skipping publish');
+            return;
+        }
+        await this.producer.send({
+            topic,
+            messages: [
+                {
+                    key,
+                    value: JSON.stringify(value),
+                },
+            ],
+        });
+    }
+};
+exports.KafkaEventPublisher = KafkaEventPublisher;
+exports.KafkaEventPublisher = KafkaEventPublisher = KafkaEventPublisher_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], KafkaEventPublisher);

package/dist/QuanticEventsKafkaModule.d.ts

@@ -0,0 +1,5 @@
+import { DynamicModule } from '@nestjs/common';
+import { KafkaEventsModuleOptions } from './KafkaEvent';
+export declare class QuanticEventsKafkaModule {
+    static forRoot(options: KafkaEventsModuleOptions): DynamicModule;
+}

package/dist/QuanticEventsKafkaModule.js

@@ -0,0 +1,45 @@
+"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 QuanticEventsKafkaModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticEventsKafkaModule = void 0;
+const common_1 = require("@nestjs/common");
+const events_core_1 = require("@quanticjs/events-core");
+const KafkaEventPublisher_1 = require("./KafkaEventPublisher");
+let QuanticEventsKafkaModule = QuanticEventsKafkaModule_1 = class QuanticEventsKafkaModule {
+    static forRoot(options) {
+        return {
+            module: QuanticEventsKafkaModule_1,
+            imports: [events_core_1.QuanticEventsCoreModule.forRoot()],
+            providers: [
+                {
+                    provide: KafkaEventPublisher_1.KAFKA_OPTIONS,
+                    useValue: options,
+                },
+                {
+                    provide: KafkaEventPublisher_1.KafkaEventPublisher,
+                    useFactory: (config) => new KafkaEventPublisher_1.KafkaEventPublisher(config),
+                    inject: [KafkaEventPublisher_1.KAFKA_OPTIONS],
+                },
+                {
+                    provide: events_core_1.EVENT_PUBLISHER,
+                    useExisting: KafkaEventPublisher_1.KafkaEventPublisher,
+                },
+            ],
+            exports: [
+                KafkaEventPublisher_1.KafkaEventPublisher,
+                events_core_1.EVENT_PUBLISHER,
+            ],
+        };
+    }
+};
+exports.QuanticEventsKafkaModule = QuanticEventsKafkaModule;
+exports.QuanticEventsKafkaModule = QuanticEventsKafkaModule = QuanticEventsKafkaModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], QuanticEventsKafkaModule);

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { KafkaEventPublisher } from './KafkaEventPublisher';
+export { KafkaEventConsumer } from './KafkaEventConsumer';
+export { QuanticEventsKafkaModule } from './QuanticEventsKafkaModule';
+export type { KafkaEvent, KafkaEventsModuleOptions } from './KafkaEvent';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuanticEventsKafkaModule = exports.KafkaEventConsumer = exports.KafkaEventPublisher = void 0;
+var KafkaEventPublisher_1 = require("./KafkaEventPublisher");
+Object.defineProperty(exports, "KafkaEventPublisher", { enumerable: true, get: function () { return KafkaEventPublisher_1.KafkaEventPublisher; } });
+var KafkaEventConsumer_1 = require("./KafkaEventConsumer");
+Object.defineProperty(exports, "KafkaEventConsumer", { enumerable: true, get: function () { return KafkaEventConsumer_1.KafkaEventConsumer; } });
+var QuanticEventsKafkaModule_1 = require("./QuanticEventsKafkaModule");
+Object.defineProperty(exports, "QuanticEventsKafkaModule", { enumerable: true, get: function () { return QuanticEventsKafkaModule_1.QuanticEventsKafkaModule; } });

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@quanticjs/events-kafka",
+  "version": "6.0.0",
+  "description": "Kafka transport for @quanticjs/events-core — KafkaEventPublisher, KafkaEventConsumer with ADR-008 compliance",
+  "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",
+    "@quanticjs/events-core": "^6.0.0",
+    "@confluentinc/kafka-javascript": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  }
+}