@signaltree/events 7.3.5 → 7.4.0

package/dist/nestjs/dlq.service.cjs

@@ -0,0 +1,249 @@
+'use strict';
+
+var tslib = require('tslib');
+var common = require('@nestjs/common');
+var bullmq = require('bullmq');
+var tokens = require('./tokens.cjs');
+
+var DlqService_1;
+exports.DlqService = DlqService_1 = class DlqService {
+  config;
+  logger = new common.Logger(DlqService_1.name);
+  queue;
+  queueName;
+  constructor(config) {
+    this.config = config;
+    this.queueName = config.dlqQueueName ?? 'dead-letter';
+  }
+  async onModuleInit() {
+    if (!this.config.enableDlq) {
+      this.logger.log('DLQ is disabled');
+      return;
+    }
+    this.queue = new bullmq.Queue(this.queueName, {
+      connection: {
+        host: this.config.redis.host,
+        port: this.config.redis.port,
+        password: this.config.redis.password,
+        db: this.config.redis.db
+      },
+      defaultJobOptions: {
+        removeOnComplete: false,
+        // Keep for inspection
+        removeOnFail: false,
+        attempts: 1 // No retries in DLQ
+      }
+    });
+    this.logger.log(`DLQ "${this.queueName}" initialized`);
+  }
+  async onModuleDestroy() {
+    if (this.queue) {
+      await this.queue.close();
+    }
+  }
+  /**
+   * Send an event to the DLQ
+   */
+  async send(entry) {
+    if (!this.queue) {
+      throw new Error('DLQ is not initialized');
+    }
+    const job = await this.queue.add(`dlq:${entry.event.type}`, entry, {
+      jobId: `dlq:${entry.event.id}:${entry.subscriber}`
+    });
+    this.logger.debug(`Event ${entry.event.id} sent to DLQ (job: ${job.id})`);
+    return job.id ?? `dlq:${entry.event.id}:${entry.subscriber}`;
+  }
+  /**
+   * Get entries from DLQ
+   */
+  async getEntries(options = {}) {
+    if (!this.queue) {
+      return [];
+    }
+    const start = options.start ?? 0;
+    const end = options.end ?? 100;
+    const jobs = await this.queue.getJobs(['waiting', 'active', 'delayed', 'failed'], start, end);
+    let entries = jobs.map(job => job.data);
+    // Apply filters
+    if (options.eventType) {
+      entries = entries.filter(e => e.event.type === options.eventType);
+    }
+    if (options.subscriber) {
+      entries = entries.filter(e => e.subscriber === options.subscriber);
+    }
+    if (options.classification) {
+      entries = entries.filter(e => e.error.classification === options.classification);
+    }
+    if (options.from) {
+      const fromDate = options.from;
+      entries = entries.filter(e => new Date(e.failedAt) >= fromDate);
+    }
+    if (options.to) {
+      const toDate = options.to;
+      entries = entries.filter(e => new Date(e.failedAt) <= toDate);
+    }
+    return entries;
+  }
+  /**
+   * Get a specific entry by event ID
+   */
+  async getEntry(eventId, subscriber) {
+    if (!this.queue) {
+      return null;
+    }
+    // Try with subscriber suffix first
+    if (subscriber) {
+      const job = await this.queue.getJob(`dlq:${eventId}:${subscriber}`);
+      if (job) {
+        return job.data;
+      }
+    }
+    // Search through jobs
+    const jobs = await this.queue.getJobs(['waiting', 'active', 'delayed', 'failed']);
+    const job = jobs.find(j => j.data.event.id === eventId);
+    return job ? job.data : null;
+  }
+  /**
+   * Get DLQ statistics
+   */
+  async getStats() {
+    const entries = await this.getEntries({
+      start: 0,
+      end: 10000
+    });
+    const stats = {
+      total: entries.length,
+      byEventType: {},
+      bySubscriber: {},
+      byClassification: {
+        transient: 0,
+        permanent: 0,
+        poison: 0,
+        unknown: 0
+      }
+    };
+    for (const entry of entries) {
+      // By event type
+      stats.byEventType[entry.event.type] = (stats.byEventType[entry.event.type] ?? 0) + 1;
+      // By subscriber
+      stats.bySubscriber[entry.subscriber] = (stats.bySubscriber[entry.subscriber] ?? 0) + 1;
+      // By classification
+      stats.byClassification[entry.error.classification]++;
+      // Date tracking
+      const failedDate = new Date(entry.failedAt);
+      if (!stats.oldestEntry || failedDate < stats.oldestEntry) {
+        stats.oldestEntry = failedDate;
+      }
+      if (!stats.newestEntry || failedDate > stats.newestEntry) {
+        stats.newestEntry = failedDate;
+      }
+    }
+    return stats;
+  }
+  /**
+   * Replay an event from DLQ
+   *
+   * This removes the event from DLQ and republishes to original queue
+   */
+  async replay(eventId, subscriber, targetQueue) {
+    if (!this.queue) {
+      throw new Error('DLQ is not initialized');
+    }
+    const jobId = `dlq:${eventId}:${subscriber}`;
+    const job = await this.queue.getJob(jobId);
+    if (!job) {
+      this.logger.warn(`DLQ entry not found: ${jobId}`);
+      return false;
+    }
+    const entry = job.data;
+    // Get target queue
+    const targetQueueInstance = new bullmq.Queue(targetQueue, {
+      connection: {
+        host: this.config.redis.host,
+        port: this.config.redis.port,
+        password: this.config.redis.password,
+        db: this.config.redis.db
+      }
+    });
+    try {
+      // Republish to original queue
+      await targetQueueInstance.add(entry.event.type, entry.event, {
+        jobId: `replay:${entry.event.id}`
+      });
+      // Remove from DLQ
+      await job.remove();
+      this.logger.log(`Replayed event ${eventId} to queue ${targetQueue}`);
+      return true;
+    } finally {
+      await targetQueueInstance.close();
+    }
+  }
+  /**
+   * Replay all events matching criteria
+   */
+  async replayBatch(options) {
+    const entries = await this.getEntries(options);
+    let replayed = 0;
+    let failed = 0;
+    for (const entry of entries) {
+      try {
+        const success = await this.replay(entry.event.id, entry.subscriber, options.targetQueue);
+        if (success) replayed++;else failed++;
+      } catch {
+        failed++;
+      }
+    }
+    return {
+      replayed,
+      failed
+    };
+  }
+  /**
+   * Remove an entry from DLQ
+   */
+  async remove(eventId, subscriber) {
+    if (!this.queue) {
+      return false;
+    }
+    const job = await this.queue.getJob(`dlq:${eventId}:${subscriber}`);
+    if (job) {
+      await job.remove();
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Purge old entries from DLQ
+   */
+  async purge(olderThan) {
+    const entries = await this.getEntries({
+      to: olderThan,
+      start: 0,
+      end: 10000
+    });
+    let purged = 0;
+    for (const entry of entries) {
+      const removed = await this.remove(entry.event.id, entry.subscriber);
+      if (removed) purged++;
+    }
+    this.logger.log(`Purged ${purged} entries from DLQ older than ${olderThan.toISOString()}`);
+    return purged;
+  }
+  /**
+   * Clear all entries from DLQ
+   */
+  async clear() {
+    if (!this.queue) {
+      return 0;
+    }
+    const count = await this.queue.getJobCounts();
+    const total = count.waiting + count.active + count.delayed + count.failed;
+    await this.queue.obliterate({
+      force: true
+    });
+    this.logger.warn(`Cleared all ${total} entries from DLQ`);
+    return total;
+  }
+};
+exports.DlqService = DlqService_1 = tslib.__decorate([common.Injectable(), tslib.__param(0, common.Inject(tokens.EVENT_BUS_CONFIG)), tslib.__metadata("design:paramtypes", [Object])], exports.DlqService);

package/dist/nestjs/dlq.service.js

@@ -0,0 +1,249 @@
+import { __decorate, __param, __metadata } from 'tslib';
+import { Injectable, Inject, Logger } from '@nestjs/common';
+import { Queue } from 'bullmq';
+import { EVENT_BUS_CONFIG } from './tokens.js';
+
+var DlqService_1;
+let DlqService = DlqService_1 = class DlqService {
+  config;
+  logger = new Logger(DlqService_1.name);
+  queue;
+  queueName;
+  constructor(config) {
+    this.config = config;
+    this.queueName = config.dlqQueueName ?? 'dead-letter';
+  }
+  async onModuleInit() {
+    if (!this.config.enableDlq) {
+      this.logger.log('DLQ is disabled');
+      return;
+    }
+    this.queue = new Queue(this.queueName, {
+      connection: {
+        host: this.config.redis.host,
+        port: this.config.redis.port,
+        password: this.config.redis.password,
+        db: this.config.redis.db
+      },
+      defaultJobOptions: {
+        removeOnComplete: false,
+        // Keep for inspection
+        removeOnFail: false,
+        attempts: 1 // No retries in DLQ
+      }
+    });
+    this.logger.log(`DLQ "${this.queueName}" initialized`);
+  }
+  async onModuleDestroy() {
+    if (this.queue) {
+      await this.queue.close();
+    }
+  }
+  /**
+   * Send an event to the DLQ
+   */
+  async send(entry) {
+    if (!this.queue) {
+      throw new Error('DLQ is not initialized');
+    }
+    const job = await this.queue.add(`dlq:${entry.event.type}`, entry, {
+      jobId: `dlq:${entry.event.id}:${entry.subscriber}`
+    });
+    this.logger.debug(`Event ${entry.event.id} sent to DLQ (job: ${job.id})`);
+    return job.id ?? `dlq:${entry.event.id}:${entry.subscriber}`;
+  }
+  /**
+   * Get entries from DLQ
+   */
+  async getEntries(options = {}) {
+    if (!this.queue) {
+      return [];
+    }
+    const start = options.start ?? 0;
+    const end = options.end ?? 100;
+    const jobs = await this.queue.getJobs(['waiting', 'active', 'delayed', 'failed'], start, end);
+    let entries = jobs.map(job => job.data);
+    // Apply filters
+    if (options.eventType) {
+      entries = entries.filter(e => e.event.type === options.eventType);
+    }
+    if (options.subscriber) {
+      entries = entries.filter(e => e.subscriber === options.subscriber);
+    }
+    if (options.classification) {
+      entries = entries.filter(e => e.error.classification === options.classification);
+    }
+    if (options.from) {
+      const fromDate = options.from;
+      entries = entries.filter(e => new Date(e.failedAt) >= fromDate);
+    }
+    if (options.to) {
+      const toDate = options.to;
+      entries = entries.filter(e => new Date(e.failedAt) <= toDate);
+    }
+    return entries;
+  }
+  /**
+   * Get a specific entry by event ID
+   */
+  async getEntry(eventId, subscriber) {
+    if (!this.queue) {
+      return null;
+    }
+    // Try with subscriber suffix first
+    if (subscriber) {
+      const job = await this.queue.getJob(`dlq:${eventId}:${subscriber}`);
+      if (job) {
+        return job.data;
+      }
+    }
+    // Search through jobs
+    const jobs = await this.queue.getJobs(['waiting', 'active', 'delayed', 'failed']);
+    const job = jobs.find(j => j.data.event.id === eventId);
+    return job ? job.data : null;
+  }
+  /**
+   * Get DLQ statistics
+   */
+  async getStats() {
+    const entries = await this.getEntries({
+      start: 0,
+      end: 10000
+    });
+    const stats = {
+      total: entries.length,
+      byEventType: {},
+      bySubscriber: {},
+      byClassification: {
+        transient: 0,
+        permanent: 0,
+        poison: 0,
+        unknown: 0
+      }
+    };
+    for (const entry of entries) {
+      // By event type
+      stats.byEventType[entry.event.type] = (stats.byEventType[entry.event.type] ?? 0) + 1;
+      // By subscriber
+      stats.bySubscriber[entry.subscriber] = (stats.bySubscriber[entry.subscriber] ?? 0) + 1;
+      // By classification
+      stats.byClassification[entry.error.classification]++;
+      // Date tracking
+      const failedDate = new Date(entry.failedAt);
+      if (!stats.oldestEntry || failedDate < stats.oldestEntry) {
+        stats.oldestEntry = failedDate;
+      }
+      if (!stats.newestEntry || failedDate > stats.newestEntry) {
+        stats.newestEntry = failedDate;
+      }
+    }
+    return stats;
+  }
+  /**
+   * Replay an event from DLQ
+   *
+   * This removes the event from DLQ and republishes to original queue
+   */
+  async replay(eventId, subscriber, targetQueue) {
+    if (!this.queue) {
+      throw new Error('DLQ is not initialized');
+    }
+    const jobId = `dlq:${eventId}:${subscriber}`;
+    const job = await this.queue.getJob(jobId);
+    if (!job) {
+      this.logger.warn(`DLQ entry not found: ${jobId}`);
+      return false;
+    }
+    const entry = job.data;
+    // Get target queue
+    const targetQueueInstance = new Queue(targetQueue, {
+      connection: {
+        host: this.config.redis.host,
+        port: this.config.redis.port,
+        password: this.config.redis.password,
+        db: this.config.redis.db
+      }
+    });
+    try {
+      // Republish to original queue
+      await targetQueueInstance.add(entry.event.type, entry.event, {
+        jobId: `replay:${entry.event.id}`
+      });
+      // Remove from DLQ
+      await job.remove();
+      this.logger.log(`Replayed event ${eventId} to queue ${targetQueue}`);
+      return true;
+    } finally {
+      await targetQueueInstance.close();
+    }
+  }
+  /**
+   * Replay all events matching criteria
+   */
+  async replayBatch(options) {
+    const entries = await this.getEntries(options);
+    let replayed = 0;
+    let failed = 0;
+    for (const entry of entries) {
+      try {
+        const success = await this.replay(entry.event.id, entry.subscriber, options.targetQueue);
+        if (success) replayed++;else failed++;
+      } catch {
+        failed++;
+      }
+    }
+    return {
+      replayed,
+      failed
+    };
+  }
+  /**
+   * Remove an entry from DLQ
+   */
+  async remove(eventId, subscriber) {
+    if (!this.queue) {
+      return false;
+    }
+    const job = await this.queue.getJob(`dlq:${eventId}:${subscriber}`);
+    if (job) {
+      await job.remove();
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Purge old entries from DLQ
+   */
+  async purge(olderThan) {
+    const entries = await this.getEntries({
+      to: olderThan,
+      start: 0,
+      end: 10000
+    });
+    let purged = 0;
+    for (const entry of entries) {
+      const removed = await this.remove(entry.event.id, entry.subscriber);
+      if (removed) purged++;
+    }
+    this.logger.log(`Purged ${purged} entries from DLQ older than ${olderThan.toISOString()}`);
+    return purged;
+  }
+  /**
+   * Clear all entries from DLQ
+   */
+  async clear() {
+    if (!this.queue) {
+      return 0;
+    }
+    const count = await this.queue.getJobCounts();
+    const total = count.waiting + count.active + count.delayed + count.failed;
+    await this.queue.obliterate({
+      force: true
+    });
+    this.logger.warn(`Cleared all ${total} entries from DLQ`);
+    return total;
+  }
+};
+DlqService = DlqService_1 = __decorate([Injectable(), __param(0, Inject(EVENT_BUS_CONFIG)), __metadata("design:paramtypes", [Object])], DlqService);
+
+export { DlqService };

package/dist/nestjs/event-bus.module.cjs

@@ -0,0 +1,152 @@
+'use strict';
+
+var tslib = require('tslib');
+var common = require('@nestjs/common');
+var dlq_service = require('./dlq.service.cjs');
+var eventBus_service = require('./event-bus.service.cjs');
+var tokens = require('./tokens.cjs');
+var registry = require('../core/registry.cjs');
+var idempotency = require('../core/idempotency.cjs');
+var errorClassification = require('../core/error-classification.cjs');
+
+var EventBusModule_1;
+/**
+ * Default queue configuration based on priorities
+ */
+const DEFAULT_QUEUES = [{
+  name: 'events-critical',
+  priorities: ['critical'],
+  concurrency: 10
+}, {
+  name: 'events-high',
+  priorities: ['high'],
+  concurrency: 8
+}, {
+  name: 'events-normal',
+  priorities: ['normal'],
+  concurrency: 5
+}, {
+  name: 'events-low',
+  priorities: ['low'],
+  concurrency: 3
+}, {
+  name: 'events-bulk',
+  priorities: ['bulk'],
+  concurrency: 2,
+  rateLimit: {
+    max: 100,
+    duration: 1000
+  }
+}];
+exports.EventBusModule = EventBusModule_1 = class EventBusModule {
+  /**
+   * Register the EventBus module with configuration
+   *
+   * @example
+   * ```typescript
+   * @Module({
+   *   imports: [
+   *     EventBusModule.forRoot({
+   *       redis: { host: 'localhost', port: 6379 },
+   *       queues: [
+   *         { name: 'critical', priorities: ['critical'], concurrency: 10 },
+   *         { name: 'normal', priorities: ['high', 'normal'], concurrency: 5 },
+   *       ],
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRoot(config) {
+    const providers = EventBusModule_1.createProviders(config);
+    return {
+      module: EventBusModule_1,
+      global: true,
+      providers,
+      exports: [eventBus_service.EventBusService, dlq_service.DlqService, tokens.EVENT_BUS_CONFIG, tokens.EVENT_REGISTRY, tokens.IDEMPOTENCY_STORE, tokens.ERROR_CLASSIFIER]
+    };
+  }
+  /**
+   * Register the EventBus module with async configuration
+   *
+   * @example
+   * ```typescript
+   * @Module({
+   *   imports: [
+   *     EventBusModule.forRootAsync({
+   *       imports: [ConfigModule],
+   *       useFactory: (configService: ConfigService) => ({
+   *         redis: {
+   *           host: configService.get('REDIS_HOST'),
+   *           port: configService.get('REDIS_PORT'),
+   *         },
+   *       }),
+   *       inject: [ConfigService],
+   *     }),
+   *   ],
+   * })
+   * export class AppModule {}
+   * ```
+   */
+  static forRootAsync(asyncConfig) {
+    const configProvider = {
+      provide: tokens.EVENT_BUS_CONFIG,
+      useFactory: asyncConfig.useFactory,
+      inject: asyncConfig.inject ?? []
+    };
+    const registryProvider = {
+      provide: tokens.EVENT_REGISTRY,
+      useFactory: config => {
+        return registry.createEventRegistry(config.registry);
+      },
+      inject: [tokens.EVENT_BUS_CONFIG]
+    };
+    const idempotencyProvider = {
+      provide: tokens.IDEMPOTENCY_STORE,
+      useFactory: config => {
+        return config.idempotencyStore ?? idempotency.createInMemoryIdempotencyStore();
+      },
+      inject: [tokens.EVENT_BUS_CONFIG]
+    };
+    const errorClassifierProvider = {
+      provide: tokens.ERROR_CLASSIFIER,
+      useFactory: config => {
+        return errorClassification.createErrorClassifier(config.errorClassifier);
+      },
+      inject: [tokens.EVENT_BUS_CONFIG]
+    };
+    return {
+      module: EventBusModule_1,
+      global: true,
+      imports: asyncConfig.imports ?? [],
+      providers: [configProvider, registryProvider, idempotencyProvider, errorClassifierProvider, eventBus_service.EventBusService, dlq_service.DlqService],
+      exports: [eventBus_service.EventBusService, dlq_service.DlqService, tokens.EVENT_BUS_CONFIG, tokens.EVENT_REGISTRY, tokens.IDEMPOTENCY_STORE, tokens.ERROR_CLASSIFIER]
+    };
+  }
+  static createProviders(config) {
+    const queues = config.queues ?? DEFAULT_QUEUES;
+    const fullConfig = {
+      ...config,
+      queues,
+      enableDlq: config.enableDlq ?? true,
+      dlqQueueName: config.dlqQueueName ?? 'dead-letter',
+      enableMetrics: config.enableMetrics ?? true,
+      metricsPrefix: config.metricsPrefix ?? 'signaltree_events'
+    };
+    return [{
+      provide: tokens.EVENT_BUS_CONFIG,
+      useValue: fullConfig
+    }, {
+      provide: tokens.EVENT_REGISTRY,
+      useFactory: () => registry.createEventRegistry(config.registry)
+    }, {
+      provide: tokens.IDEMPOTENCY_STORE,
+      useValue: config.idempotencyStore ?? idempotency.createInMemoryIdempotencyStore()
+    }, {
+      provide: tokens.ERROR_CLASSIFIER,
+      useFactory: () => errorClassification.createErrorClassifier(config.errorClassifier)
+    }, eventBus_service.EventBusService, dlq_service.DlqService];
+  }
+};
+exports.EventBusModule = EventBusModule_1 = tslib.__decorate([common.Module({})], exports.EventBusModule);