@vytches/ddd-messaging 0.29.3 → 0.31.0-alpha.0

package/LLMGUIDE.md

@@ -14,71 +14,88 @@ True to the library's philosophy: **no database adapter ships with the package**
 
 ```typescript
 import {
-  OutboxService,
   OutboxProcessor,
   OutboxMessageFactory,
   EventBusOutboxHandler,
-  MessageStatus,
   MessagePriority,
   type IOutboxRepository,
+  type IOutboxMessageHandler,
 } from '@vytches/ddd-messaging';
 
-// 1. Implement the repository for your storage (example sketch)
-class PgOutboxRepository implements IOutboxRepository {
-  async save(message) {
+// 1. Implement the repository for your storage
+class PgOutboxRepository extends IOutboxRepository {
+  async saveMessage(message) {
     /* INSERT INTO outbox ... */
   }
-  async findPending(limit) {
-    /* SELECT ... WHERE status = 'pending' */
+  async saveBatch(messages) {
+    /* INSERT INTO outbox ... */
+  }
+  async getUnprocessedMessages(limit, priorityOrder, messageTypes) {
+    // IMPORTANT: order by priorityOrder array index, NOT alphabetically
+    // See "Priority ordering in repository implementations" below
+  }
+  async getById(id) {
+    /* SELECT ... */
   }
-  async markDispatched(id) {
+  async updateStatus(id, status, error?) {
     /* UPDATE ... */
   }
-  async markFailed(id, error) {
+  async updateStatusBatch(ids, status) {
     /* UPDATE ... */
   }
-  // ...
+  async incrementAttempt(id) {
+    /* UPDATE ... RETURNING attempts */
+  }
+  async deleteByStatusAndAge(olderThan, status) {
+    /* DELETE ... */
+  }
+  async scheduleMessage(message, processAfter) {
+    /* INSERT ... */
+  }
 }
 
-// 2. Wire up the outbox service
+// 2. Wire up the processor
 const repo = new PgOutboxRepository(db);
-const factory = new OutboxMessageFactory();
 const handler = new EventBusOutboxHandler(integrationBus);
-const processor = new OutboxProcessor(repo, handler, {
-  pollIntervalMs: 1_000,
+
+const processor = new OutboxProcessor(repo, {
   batchSize: 50,
+  processingInterval: 1_000,
+  retryBackoff: { initial: 1_000, multiplier: 2, maxDelay: 300_000 },
 });
+processor.registerHandler('order.placed', handler);
+processor.start();
 
-const outbox = new OutboxService(repo, factory, processor);
-
-// 3. In a transaction with your aggregate save
+// 3. Enqueue in the same transaction as your aggregate save
+const factory = new OutboxMessageFactory();
 await db.transaction(async tx => {
   await orderRepo.save(order, tx);
-  await outbox.enqueue(
-    integrationEvent,
-    { priority: MessagePriority.High },
-    tx
+  await repo.saveMessage(
+    factory.create(integrationEvent, {
+      priority: MessagePriority.HIGH,
+    })
   );
 });
 ```
 
 ## Key API
 
-| Export                   | Kind      | Description                                                      |
-| ------------------------ | --------- | ---------------------------------------------------------------- |
-| `IOutboxMessage`         | interface | The shape of a stored outbox row                                 |
-| `IOutboxRepository`      | interface | **You implement this**: persistence for outbox messages          |
-| `IOutboxMessageHandler`  | interface | How to dispatch a stored message (default: publish to event bus) |
-| `OutboxMessageOptions`   | type      | `{ priority, dedupKey, headers }` per-message overrides          |
-| `OutboxMiddleware`       | type      | Hook for cross-cutting concerns (tracing, encryption)            |
-| `OutboxProcessorOptions` | type      | `{ pollIntervalMs, batchSize, maxRetries, ... }`                 |
-| `OutboxServiceOptions`   | type      | Top-level config bag                                             |
-| `MessageStatus`          | enum      | `Pending`, `Dispatched`, `Failed`, `DeadLettered`                |
-| `MessagePriority`        | enum      | `Low`, `Normal`, `High`, `Critical`                              |
-| `OutboxMessageFactory`   | class     | Build `IOutboxMessage` from an integration event                 |
-| `OutboxProcessor`        | class     | Polls repo, dispatches via handler, updates status               |
-| `EventBusOutboxHandler`  | class     | Default handler — publishes via an `IIntegrationEventBus`        |
-| `OutboxService`          | class     | Facade combining factory + processor for the application         |
+| Export                   | Kind      | Description                                                                     |
+| ------------------------ | --------- | ------------------------------------------------------------------------------- |
+| `IOutboxMessage`         | interface | The shape of a stored outbox row                                                |
+| `IOutboxRepository`      | interface | **You implement this**: persistence for outbox messages                         |
+| `IOutboxMessageHandler`  | interface | How to dispatch a stored message (default: publish to event bus)                |
+| `OutboxMessageOptions`   | type      | `{ priority, dedupKey, headers }` per-message overrides                         |
+| `OutboxMiddleware`       | type      | Hook for cross-cutting concerns (tracing, encryption)                           |
+| `OutboxProcessorOptions` | type      | `{ pollIntervalMs, batchSize, maxRetries, ... }`                                |
+| `OutboxServiceOptions`   | type      | Top-level config bag                                                            |
+| `MessageStatus`          | enum      | `Pending`, `Dispatched`, `Failed`, `DeadLettered`                               |
+| `MessagePriority`        | enum      | `Low`, `Normal`, `High`, `Critical`                                             |
+| `OutboxMessageFactory`   | class     | Build `IOutboxMessage` from an integration event                                |
+| `OutboxProcessor`        | class     | Polls repo, dispatches via handler, updates status                              |
+| `EventBusOutboxHandler`  | class     | Default handler — publishes via an `IIntegrationEventBus`                       |
+| `OutboxService`          | class     | Facade combining factory + processor for the application                        |
+| `comparePriority`        | function  | Sorts `MessagePriority` values by a given order array (safe for partial arrays) |
 
 ## Patterns
 
@@ -142,6 +159,90 @@ The library does **not** ship broker-specific adapters — that would force
 adopters to bring in BullMQ/Kafka/etc. as transitive dependencies. Write the
 ~10-line adapter yourself; the library guarantees the interface contract.
 
+### Fan-out: one default handler for N event types
+
+When you want a single handler to process all (or most) outbox message types —
+for example, routing every integration event to a BullMQ per-context queue — use
+`registerDefaultHandler` instead of registering the same handler 50 times.
+
+```typescript
+class FanOutHandler implements IOutboxMessageHandler {
+  constructor(private readonly queues: Map<string, Queue>) {}
+
+  async handle(message: IOutboxMessage): Promise<void> {
+    // RECOMMENDED: validate against a known-types set so new event types
+    // added to the domain are caught early rather than silently dispatched.
+    if (!KNOWN_EVENT_TYPES.has(message.messageType)) {
+      throw new Error(`Unknown event type: ${message.messageType}`);
+    }
+    const queue =
+      this.queues.get(message.messageType) ?? this.queues.get('default');
+    await queue?.add(message.messageType, message.payload, {
+      jobId: message.id,
+    });
+  }
+}
+
+const processor = new OutboxProcessor(repo, { batchSize: 200 });
+processor.registerDefaultHandler(new FanOutHandler(queues));
+processor.start();
+```
+
+**Security warning:** `registerDefaultHandler` removes the implicit type
+allowlist that exists when only `registerHandler` is used. Before VP-008, an
+unknown `messageType` would always throw — an implicit safety net. After
+registering a default handler, ALL future message types (including ones added
+later by mistake or injected via a compromised storage layer) will be dispatched
+automatically. Always validate `message.messageType` against an explicit
+known-types set inside the default handler.
+
+**Interaction with `messageTypes` option:** if
+`OutboxProcessorOptions.messageTypes` is set, the default handler will only see
+messages whose type passes that filter. To catch every type, leave
+`messageTypes` unset.
+
+**PII and new event types:** when a new domain event type carrying PII is added,
+review access controls on all downstream queues — the default handler will
+dispatch it to all configured destinations without any per-type gating.
+
+### Priority ordering in repository implementations
+
+`IOutboxRepository.getUnprocessedMessages` receives a `priorityOrder` array such
+as `[CRITICAL, HIGH, NORMAL, LOW]`. Repository implementations **MUST** order by
+the array index, not by raw column value. String comparison on the `priority`
+column (`ORDER BY priority DESC`) silently inverts the intent:
+`'normal' > 'low' > 'high' > 'critical'` alphabetically.
+
+Correct SQL using a `CASE` expression:
+
+```sql
+ORDER BY
+  CASE priority
+    WHEN 'critical' THEN 0
+    WHEN 'high'     THEN 1
+    WHEN 'normal'   THEN 2
+    WHEN 'low'      THEN 3
+    ELSE                 4   -- unknown priorities sort last
+  END
+```
+
+Or use the exported `comparePriority` helper in in-process sorting:
+
+```typescript
+import { comparePriority } from '@vytches/ddd-messaging';
+
+// Sort an in-memory array highest-priority-first:
+messages.sort((a, b) =>
+  comparePriority(
+    a.priority ?? MessagePriority.NORMAL,
+    b.priority ?? MessagePriority.NORMAL
+  )
+);
+```
+
+`comparePriority` is safe with partial or custom order arrays — values absent
+from the array sort last rather than accidentally first.
+
 ## Anti-Patterns
 
 - **Do not enqueue outbox messages outside the aggregate save transaction** — if

package/README.md

@@ -17,74 +17,101 @@ pnpm add @vytches/ddd-messaging
 
 ## What's included
 
-| Export                   | Kind           | Description                                                     |
-| ------------------------ | -------------- | --------------------------------------------------------------- |
-| `MessageStatus`          | enum           | `PENDING \| PROCESSING \| PROCESSED \| FAILED`                  |
-| `MessagePriority`        | enum           | `LOW \| NORMAL \| HIGH \| CRITICAL`                             |
-| `OutboxMessageFactory`   | class          | Creates `IOutboxMessage` instances                              |
-| `OutboxProcessor`        | class          | Polls the repository and dispatches messages                    |
-| `EventBusOutboxHandler`  | class          | `IOutboxMessageHandler` that publishes to an `IEventBus`        |
-| `OutboxService`          | class          | High-level facade: store, schedule, and coordinate processing   |
-| `IOutboxRepository`      | abstract class | Base repository contract — extend this for your storage backend |
-| `IOutboxMessage`         | interface      | Message shape with id, payload, status, priority, timestamps    |
-| `IOutboxMessageHandler`  | interface      | Single-method handler: `handle(message): Promise<void>`         |
-| `OutboxMiddleware`       | type           | Middleware signature for the processor pipeline                 |
-| `OutboxProcessorOptions` | interface      | Processor configuration (interval, batch size, retries…)        |
-| `OutboxServiceOptions`   | interface      | Service configuration                                           |
-| `OutboxMessageOptions`   | interface      | Per-message options (priority, processAfter…)                   |
-| `RetryBackoffConfig`     | interface      | Exponential backoff configuration for the processor             |
+| Export                   | Kind           | Description                                                              |
+| ------------------------ | -------------- | ------------------------------------------------------------------------ |
+| `MessageStatus`          | enum           | `PENDING \| PROCESSING \| PROCESSED \| FAILED`                           |
+| `MessagePriority`        | enum           | `low \| normal \| high \| critical`                                      |
+| `OutboxMessageFactory`   | class          | Creates `IOutboxMessage` instances                                       |
+| `OutboxProcessor`        | class          | Polls the repository and dispatches messages via registered handlers     |
+| `EventBusOutboxHandler`  | class          | `IOutboxMessageHandler` that publishes to an `IEventBus`                 |
+| `OutboxService`          | class          | High-level facade: store, schedule, and coordinate processing            |
+| `IOutboxRepository`      | abstract class | Base repository contract — extend this for your storage backend          |
+| `IOutboxMessage`         | interface      | Message shape with id, payload, status, priority, timestamps             |
+| `IOutboxMessageHandler`  | interface      | Single-method handler: `handle(message): Promise<void>`                  |
+| `OutboxMiddleware`       | type           | Middleware signature for the processor pipeline                          |
+| `OutboxProcessorOptions` | interface      | Processor configuration (interval, batch size, retries, backoff, hooks…) |
+| `OutboxProcessorHooks`   | interface      | Observability callbacks: batch complete, message failed, permanent fail  |
+| `OutboxServiceOptions`   | interface      | Service configuration                                                    |
+| `OutboxMessageOptions`   | interface      | Per-message options (priority, processAfter…)                            |
+| `RetryBackoffConfig`     | interface      | Exponential backoff configuration for the processor                      |
+| `comparePriority`        | function       | Compares two `MessagePriority` values by a given order array             |
 
 ## Quick start
 
 ```typescript
 import {
-  OutboxService,
   OutboxProcessor,
   OutboxMessageFactory,
   EventBusOutboxHandler,
   MessagePriority,
+  type IOutboxRepository,
 } from '@vytches/ddd-messaging';
-import { UnifiedEventBus } from '@vytches/ddd-events';
 
-// Implement IOutboxRepository for your storage (e.g. PostgreSQL)
+// 1. Implement IOutboxRepository for your storage (e.g. PostgreSQL)
 class PostgresOutboxRepository extends IOutboxRepository {
-  async save(message) {
-    /* ... */
+  async saveMessage(message) {
+    /* INSERT INTO outbox ... */
   }
-  async findPending(limit) {
-    /* ... */
+  async saveBatch(messages) {
+    /* INSERT INTO outbox (batch) ... */
   }
-  async markProcessed(id) {
-    /* ... */
+  async getUnprocessedMessages(limit, priorityOrder, messageTypes) {
+    // ORDER by priorityOrder array index — do NOT use ORDER BY priority string column
+    /* SELECT ... WHERE status = 'PENDING' ORDER BY CASE priority ... */
   }
-  async markFailed(id, error) {
-    /* ... */
+  async getById(id) {
+    /* SELECT ... */
+  }
+  async updateStatus(id, status, error?) {
+    /* UPDATE ... */
+  }
+  async updateStatusBatch(ids, status) {
+    /* UPDATE ... */
+  }
+  async incrementAttempt(id) {
+    /* UPDATE ... RETURNING attempts */
+  }
+  async deleteByStatusAndAge(olderThan, status) {
+    /* DELETE ... */
+  }
+  async scheduleMessage(message, processAfter) {
+    /* INSERT ... */
   }
 }
 
-const repository = new PostgresOutboxRepository();
-const eventBus = new UnifiedEventBus();
-
-// Service stores messages, processor dispatches them
-const service = new OutboxService(repository);
-const handler = new EventBusOutboxHandler(eventBus);
-const processor = new OutboxProcessor(repository, handler, {
-  processingInterval: 5_000,
+// 2. Wire up the processor
+const repo = new PostgresOutboxRepository(db);
+const processor = new OutboxProcessor(repo, {
   batchSize: 50,
+  processingInterval: 5_000,
   maxRetries: 3,
+  retryBackoff: { initial: 1_000, multiplier: 2, maxDelay: 300_000 },
 });
 
-// Store a message (call this inside your aggregate save transaction)
-const factory = new OutboxMessageFactory();
-const message = factory.create({
-  messageType: 'OrderCreated',
-  payload: { orderId: '123' },
-  priority: MessagePriority.HIGH,
+// Register a type-specific handler
+processor.registerHandler('OrderCreated', new EventBusOutboxHandler(eventBus));
+
+// Or a catch-all default handler for uniform fan-out
+processor.registerDefaultHandler({
+  async handle(message) {
+    await myQueue.add(message.messageType, message.payload);
+  },
 });
-await service.store(message);
 
-// Start polling
-await processor.start();
+processor.start();
+
+// 3. Enqueue in the same transaction as your aggregate save
+const factory = new OutboxMessageFactory();
+await db.transaction(async tx => {
+  await orderRepo.save(order, tx);
+  await repo.saveMessage(
+    factory.create({
+      messageType: 'OrderCreated',
+      payload: { orderId: order.id },
+      priority: MessagePriority.HIGH,
+    })
+  );
+});
 ```
 
 ## Custom message handler
@@ -102,41 +129,29 @@ class KafkaMessageHandler implements IOutboxMessageHandler {
     });
   }
 }
+
+processor.registerHandler('OrderCreated', new KafkaMessageHandler());
 ```
 
-## Implement your repository
+## Default (catch-all) handler
 
-Extend `IOutboxRepository` and provide persistence:
+For uniform dispatch — e.g. routing all event types to a single queue — use
+`registerDefaultHandler` instead of registering per-type:
 
 ```typescript
-import {
-  IOutboxRepository,
-  IOutboxMessage,
-  MessageStatus,
-} from '@vytches/ddd-messaging';
-
-class MyOutboxRepository extends IOutboxRepository {
-  async save(message: IOutboxMessage): Promise<void> {
-    await db.outbox.insert(message);
-  }
-
-  async findPendingMessages(limit: number): Promise<IOutboxMessage[]> {
-    return db.outbox.findWhere({ status: MessageStatus.PENDING }, limit);
-  }
-
-  async markAsProcessed(id: string): Promise<void> {
-    await db.outbox.update(id, { status: MessageStatus.PROCESSED });
-  }
-
-  async markAsFailed(id: string, error: string): Promise<void> {
-    await db.outbox.update(id, {
-      status: MessageStatus.FAILED,
-      lastError: error,
+processor.registerDefaultHandler({
+  async handle(message) {
+    await fanOutQueue.add(message.messageType, message.payload, {
+      jobId: message.id,
     });
-  }
-}
+  },
+});
 ```
 
+> **Note:** Registering a default handler removes the implicit per-type
+> allowlist. Validate `message.messageType` inside the handler if you need an
+> explicit allowlist.
+
 ## Package boundaries
 
 `@vytches/ddd-messaging` depends on:

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@vytches/ddd-logging"),d=require("@vytches/ddd-utils");var n=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(n||{}),g=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(g||{});class p{scheduleRetry(e,t){return Promise.resolve()}resetStaleProcessing(e){return Promise.resolve(0)}}class l{static createMessage(e,t,s){const r={id:d.LibUtils.getUUID(),messageType:e,payload:t,metadata:s?.metadata||{},status:n.PENDING,attempts:0,createdAt:new Date,priority:s?.priority||g.NORMAL};return s?.processAfter&&(r.processAfter=s.processAfter),r}static createDelayedMessage(e,t,s,r){const a=new Date(Date.now()+s);return l.createMessage(e,t,{...r,processAfter:a})}static createHighPriorityMessage(e,t,s){return l.createMessage(e,t,{...s,priority:g.HIGH})}static createFromIntegrationEvent(e,t){const s={metadata:{...e.metadata||{},...t?.metadata||{}}};return t?.priority&&(s.priority=t.priority),t?.processAfter&&(s.processAfter=t.processAfter),l.createMessage(`integration_event:${e.eventName}`,e.payload,s)}}class y{constructor(e,t={}){this.handlers=new Map,this.middlewares=[],this.isRunning=!1,this.logger=u.Logger.create("OutboxProcessor");const s=t.batchSize??10;if(s>1e4)throw new RangeError(`OutboxProcessor: batchSize must be ≤ 10,000, got ${s}`);if(t.retryBackoff){const{initial:o,multiplier:h,maxDelay:c}=t.retryBackoff;if(o<=0||h<=0||c<=0)throw new RangeError(`OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${h}, maxDelay=${c})`)}const r=t.messageTimeout??3e4,a=t.crashRecoveryThresholdMs??Math.max(3e5,r);if(a<r)throw new RangeError(`OutboxProcessor: crashRecoveryThresholdMs (${a}) must be ≥ messageTimeout (${r}) to avoid resetting in-flight messages`);this.repository=e,this.options={batchSize:s,maxRetries:t.maxRetries??3,processingInterval:t.processingInterval??5e3,priorityOrder:t.priorityOrder??[g.CRITICAL,g.HIGH,g.NORMAL,g.LOW],messageTimeout:r,enableLogging:t.enableLogging??!1,retryBackoff:t.retryBackoff,messageTypes:t.messageTypes,crashRecoveryIntervalMs:t.crashRecoveryIntervalMs,crashRecoveryThresholdMs:a,adaptiveRepoll:t.adaptiveRepoll??!1,adaptiveRepollMaxConsecutive:t.adaptiveRepollMaxConsecutive??5,adaptiveRepollPauseMs:t.adaptiveRepollPauseMs??50,startupJitterMs:t.startupJitterMs??0,hooks:t.hooks}}safelyInvokeHook(e,t){if(this.options.hooks)try{t()}catch(s){const r=s instanceof Error?s.message:String(s);this.logger.error(`Outbox hook ${e} threw and was ignored: ${r}`)}}registerHandler(e,t){this.handlers.set(e,t),this.logger.debug(`Registered handler for message type: ${e}`)}use(e){this.middlewares.push(e),this.logger.debug("Registered middleware")}start(){if(this.isRunning){this.logger.warn("Processor is already running");return}this.isRunning=!0,this.logger.info("Starting outbox processor");const e=this.options.startupJitterMs>0?Math.floor(Math.random()*this.options.startupJitterMs):0;this.scheduleProcessing(0,this.options.processingInterval+e),this.scheduleCrashRecovery()}stop(){if(!this.isRunning){this.logger.warn("Processor is not running");return}this.isRunning=!1,this.processingTimer&&(clearTimeout(this.processingTimer),this.processingTimer=void 0),this.crashRecoveryTimer&&(clearTimeout(this.crashRecoveryTimer),this.crashRecoveryTimer=void 0),this.logger.info("Stopped outbox processor")}async processBatch(){const e=this.options.batchSize;if(!this.isRunning)return{processed:0,batchSize:e};const[t,s]=await d.safeRun(()=>this.repository.getUnprocessedMessages(e,this.options.priorityOrder,this.options.messageTypes));if(t){const c=t instanceof Error?t.message:String(t);return this.logger.error(`Error retrieving messages: ${c}`),{processed:0,batchSize:e}}const r=s;if(!r||!Array.isArray(r)||r.length===0)return this.logger.debug("No pending messages to process"),{processed:0,batchSize:e};this.logger.info(`Processing ${r.length} messages`);const a=Date.now(),h=(await Promise.allSettled(r.map(c=>this.processMessage(c)))).filter(c=>c.status==="rejected"||c.status==="fulfilled"&&c.value===!1).length;return this.logger.info(`Completed processing batch of ${r.length} messages`),this.safelyInvokeHook("onBatchComplete",()=>this.options.hooks?.onBatchComplete?.({processed:r.length,failed:h,batchSize:e,durationMs:Date.now()-a})),{processed:r.length,batchSize:e}}async processMessage(e){const[t]=await d.safeRun(async()=>{await this.repository.updateStatus(e.id,n.PROCESSING),await this.buildPipeline(e)(e),await this.repository.updateStatus(e.id,n.PROCESSED),this.logger.debug(`Successfully processed message ${e.id}`)});return t?(await this.handleMessageError(e,t),!1):!0}buildPipeline(e){const t=this.handlers.get(e.messageType);if(!t)throw new Error(`No handler registered for message type: ${e.messageType}`);const s=async r=>{await Promise.race([t.handle(r),new Promise((a,o)=>setTimeout(()=>o(new Error("Message processing timeout")),this.options.messageTimeout))])};return this.middlewares.reduceRight((r,a)=>a(r),s)}async handleMessageError(e,t){try{const s=await this.repository.incrementAttempt(e.id);if(this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`),this.safelyInvokeHook("onMessageFailed",()=>this.options.hooks?.onMessageFailed?.(e,t,s)),s>=this.options.maxRetries)await this.repository.updateStatus(e.id,n.FAILED,t),this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`),this.safelyInvokeHook("onPermanentFailure",()=>this.options.hooks?.onPermanentFailure?.(e,t));else if(this.options.retryBackoff){const{initial:r,multiplier:a,maxDelay:o}=this.options.retryBackoff,h=Math.min(r*Math.pow(a,s-1),o),c=new Date(Date.now()+h);await this.repository.updateStatus(e.id,n.PENDING),await this.repository.scheduleRetry(e.id,c),this.logger.info(`Message ${e.id} scheduled for retry in ${h}ms (attempt ${s})`)}else await this.repository.updateStatus(e.id,n.PENDING),this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s+1})`)}catch(s){const r=s instanceof Error?s.message:String(s);this.logger.error(`Error updating message status: ${r}`)}}scheduleProcessing(e=0,t=this.options.processingInterval){this.isRunning&&(this.processingTimer=setTimeout(async()=>{const s=await this.processBatch();if(this.options.adaptiveRepoll&&s.processed>0&&s.processed>=s.batchSize){const a=e+1,o=a>this.options.adaptiveRepollMaxConsecutive?this.options.adaptiveRepollPauseMs:0;this.scheduleProcessing(a,o)}else this.scheduleProcessing(0,this.options.processingInterval)},t))}scheduleCrashRecovery(){!this.isRunning||this.options.crashRecoveryIntervalMs===void 0||(this.crashRecoveryTimer=setTimeout(async()=>{await this.runCrashRecovery(),this.scheduleCrashRecovery()},this.options.crashRecoveryIntervalMs))}async runCrashRecovery(){const e=new Date(Date.now()-this.options.crashRecoveryThresholdMs),[t,s]=await d.safeRun(()=>this.repository.resetStaleProcessing(e));if(t){const r=t instanceof Error?t.message:String(t);this.logger.error(`Crash recovery failed: ${r}`);return}s&&s>0&&this.logger.warn(`Crash recovery reset ${s} stale PROCESSING message(s) to PENDING`)}log(e){this.options.enableLogging&&this.logger.info(e)}async getStats(){return{isRunning:this.isRunning,batchSize:this.options.batchSize,maxRetries:this.options.maxRetries,processingInterval:this.options.processingInterval,registeredHandlers:Array.from(this.handlers.keys()),middlewareCount:this.middlewares.length}}}class f{constructor(e){this.eventBus=e}async handle(e){const s={eventName:e.messageType.startsWith("integration_event:")?e.messageType.replace("integration_event:",""):e.messageType,eventId:e.id,occurredOn:e.createdAt,version:1,...e.payload,...e.metadata};await this.eventBus.publish(s)}}class m{constructor(e,t={}){this.logger=u.Logger.create("OutboxService"),this.repository=e,this.options={defaultPriority:t.defaultPriority??g.NORMAL,defaultMetadata:t.defaultMetadata??{},autoCleanup:t.autoCleanup??!1,cleanupAfterDays:t.cleanupAfterDays??7,enableLogging:t.enableLogging??!1}}async saveMessage(e,t,s){const r=l.createMessage(e,t,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...s?.metadata},...s}),a=await this.repository.saveMessage(r);return this.logger.debug(`Saved message ${a} of type ${e}`),a}async saveMessages(e){const t=e.map(({messageType:r,payload:a,options:o})=>l.createMessage(r,a,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...o?.metadata},...o})),s=await this.repository.saveBatch(t);return this.logger.debug(`Saved batch of ${e.length} messages`),s}async scheduleMessage(e,t,s,r){const a=l.createDelayedMessage(e,t,s,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...r?.metadata},...r}),o=await this.repository.scheduleMessage(a,a.processAfter);return this.logger.debug(`Scheduled message ${o} of type ${e} for processing in ${s}ms`),o}async saveHighPriorityMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:g.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:g.CRITICAL})}async saveDomainEvent(e,t){const s=l.createFromIntegrationEvent({eventName:e.eventName,payload:e,metadata:{eventId:e?.metadata?.eventId,occurredOn:e?.metadata?.occurredOn,version:e?.metadata?.version}},{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...t?.metadata},...t}),r=await this.repository.saveMessage(s);return this.logger.debug(`Saved domain event ${e.eventName} as message ${r}`),r}async getMessage(e){return this.repository.getById(e)}async getPendingMessages(e=100){return this.repository.getUnprocessedMessages(e)}async retryMessage(e){await this.repository.updateStatus(e,n.PENDING),this.logger.info(`Reset message ${e} to pending for retry`)}async retryMessages(e){await this.repository.updateStatusBatch(e,n.PENDING),this.logger.info(`Reset ${e.length} messages to pending for retry`)}async cleanup(e){const t=e??this.options.cleanupAfterDays,s=new Date;s.setDate(s.getDate()-t);const r=await this.repository.deleteByStatusAndAge(s,n.PROCESSED);return this.logger.info(`Cleaned up ${r} processed messages older than ${t} days`),r}async getStats(){const e=this.repository;return e.getMessageCountByStatus?{totalPending:e.getMessageCountByStatus(n.PENDING),totalProcessing:e.getMessageCountByStatus(n.PROCESSING),totalProcessed:e.getMessageCountByStatus(n.PROCESSED),totalFailed:e.getMessageCountByStatus(n.FAILED)}:{totalPending:(await this.repository.getUnprocessedMessages(1e3)).length,totalProcessing:0,totalProcessed:0,totalFailed:0}}log(e){this.options.enableLogging&&this.logger.info(e)}}exports.EventBusOutboxHandler=f;exports.IOutboxRepository=p;exports.MessagePriority=g;exports.MessageStatus=n;exports.OutboxMessageFactory=l;exports.OutboxProcessor=y;exports.OutboxService=m;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("@vytches/ddd-utils"),c=require("@vytches/ddd-contracts/internal");var n=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(n||{}),l=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(l||{});const m=["critical","high","normal","low"];function f(i,e,t=m){const s=t.includes(i)?t.indexOf(i):t.length,a=t.includes(e)?t.indexOf(e):t.length;return s-a}class v{async claimBatch(e,t,s){const a=await this.getUnprocessedMessages(e,t,s);return a.length===0?a:(await this.updateStatusBatch(a.map(r=>r.id),n.PROCESSING),a.map(r=>({...r,status:n.PROCESSING})))}scheduleRetry(e,t){return Promise.resolve()}resetStaleProcessing(e){return Promise.resolve(0)}}class h{static createMessage(e,t,s){const a={id:p.LibUtils.getUUID(),messageType:e,payload:t,metadata:s?.metadata||{},status:n.PENDING,attempts:0,createdAt:new Date,priority:s?.priority||l.NORMAL};return s?.processAfter&&(a.processAfter=s.processAfter),a}static createDelayedMessage(e,t,s,a){const r=new Date(Date.now()+s);return h.createMessage(e,t,{...a,processAfter:r})}static createHighPriorityMessage(e,t,s){return h.createMessage(e,t,{...s,priority:l.HIGH})}static createFromIntegrationEvent(e,t){const s={metadata:{...e.metadata||{},...t?.metadata||{}}};return t?.priority&&(s.priority=t.priority),t?.processAfter&&(s.processAfter=t.processAfter),h.createMessage(`integration_event:${e.eventName}`,e.payload,s)}}class M{constructor(e,t={}){this.handlers=new Map,this.middlewares=[],this.isRunning=!1,this.warnedMissingClaimBatch=!1;const s=t.batchSize??10;if(s>1e4)throw new RangeError(`OutboxProcessor: batchSize must be ≤ 10,000, got ${s}`);if(t.retryBackoff){const{initial:o,multiplier:u,maxDelay:d}=t.retryBackoff;if(o<=0||u<=0||d<=0)throw new RangeError(`OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${u}, maxDelay=${d})`)}const a=t.messageTimeout??3e4,r=t.crashRecoveryThresholdMs??Math.max(3e5,a);if(r<a)throw new RangeError(`OutboxProcessor: crashRecoveryThresholdMs (${r}) must be ≥ messageTimeout (${a}) to avoid resetting in-flight messages`);this.repository=e,this.options={batchSize:s,maxRetries:t.maxRetries??3,processingInterval:t.processingInterval??5e3,priorityOrder:t.priorityOrder??[l.CRITICAL,l.HIGH,l.NORMAL,l.LOW],messageTimeout:a,enableLogging:t.enableLogging??!1,retryBackoff:t.retryBackoff,messageTypes:t.messageTypes,crashRecoveryIntervalMs:t.crashRecoveryIntervalMs,crashRecoveryThresholdMs:r,adaptiveRepoll:t.adaptiveRepoll??!1,adaptiveRepollMaxConsecutive:t.adaptiveRepollMaxConsecutive??5,adaptiveRepollPauseMs:t.adaptiveRepollPauseMs??50,startupJitterMs:t.startupJitterMs??0,hooks:t.hooks,useClaimBatch:t.useClaimBatch??!1}}safelyInvokeHook(e,t){if(this.options.hooks)try{t()}catch(s){c.internalLogger.error(`OutboxProcessor: hook ${e} threw and was ignored`,s instanceof Error?s:void 0,{hookName:e})}}registerHandler(e,t){this.handlers.set(e,t)}registerDefaultHandler(e){this.defaultHandler&&c.internalLogger.warn("registerDefaultHandler: replacing existing default handler — previous handler discarded"),this.defaultHandler=e}use(e){this.middlewares.push(e)}start(){if(this.isRunning){c.internalLogger.warn("OutboxProcessor: processor is already running");return}this.isRunning=!0;const e=this.options.startupJitterMs>0?Math.floor(Math.random()*this.options.startupJitterMs):0;this.scheduleProcessing(0,this.options.processingInterval+e),this.scheduleCrashRecovery()}stop(){if(!this.isRunning){c.internalLogger.warn("OutboxProcessor: processor is not running");return}this.isRunning=!1,this.processingTimer&&(clearTimeout(this.processingTimer),this.processingTimer=void 0),this.crashRecoveryTimer&&(clearTimeout(this.crashRecoveryTimer),this.crashRecoveryTimer=void 0)}async processBatch(){const e=this.options.batchSize;if(!this.isRunning)return{processed:0,batchSize:e};const t=this.repository.claimBatch,s=this.options.useClaimBatch===!0&&typeof t=="function";this.options.useClaimBatch&&!s&&!this.warnedMissingClaimBatch&&(this.warnedMissingClaimBatch=!0,c.internalLogger.warn("OutboxProcessor: useClaimBatch is enabled but the repository does not implement claimBatch() — falling back to getUnprocessedMessages (no atomic-claim protection)"));const[a,r]=await p.safeRun(()=>s&&t?t.call(this.repository,e,this.options.priorityOrder,this.options.messageTypes):this.repository.getUnprocessedMessages(e,this.options.priorityOrder,this.options.messageTypes));if(a)return c.internalLogger.error("OutboxProcessor: error retrieving messages",a instanceof Error?a:void 0),{processed:0,batchSize:e};const o=r;if(!o||!Array.isArray(o)||o.length===0)return{processed:0,batchSize:e};const u=Date.now(),y=(await Promise.allSettled(o.map(g=>this.processMessage(g,s)))).filter(g=>g.status==="rejected"||g.status==="fulfilled"&&g.value===!1).length;return this.safelyInvokeHook("onBatchComplete",()=>this.options.hooks?.onBatchComplete?.({processed:o.length,failed:y,batchSize:e,durationMs:Date.now()-u})),{processed:o.length,batchSize:e}}async processMessage(e,t=!1){const[s]=await p.safeRun(async()=>{t||await this.repository.updateStatus(e.id,n.PROCESSING),await this.buildPipeline(e)(e),await this.repository.updateStatus(e.id,n.PROCESSED)});return s?(await this.handleMessageError(e,s),!1):!0}buildPipeline(e){const t=this.handlers.get(e.messageType)??this.defaultHandler;if(!t)throw new Error(`No handler registered for message type: ${e.messageType}`);const s=async a=>{let r;try{await Promise.race([t.handle(a),new Promise((o,u)=>{r=setTimeout(()=>u(new Error("Message processing timeout")),this.options.messageTimeout)})])}finally{r!==void 0&&clearTimeout(r)}};return this.middlewares.reduceRight((a,r)=>r(a),s)}async handleMessageError(e,t){try{const s=await this.repository.incrementAttempt(e.id);if(c.internalLogger.warn(`OutboxProcessor: message ${e.id} failed, attempt ${s}: ${p.LibUtils.sanitizeLogMessage(t?.message??String(t))}`),this.safelyInvokeHook("onMessageFailed",()=>this.options.hooks?.onMessageFailed?.(e,t,s)),s>=this.options.maxRetries)await this.repository.updateStatus(e.id,n.FAILED,t),c.internalLogger.error("OutboxProcessor: message permanently failed",t,{messageId:e.id,attempts:s}),this.safelyInvokeHook("onPermanentFailure",()=>this.options.hooks?.onPermanentFailure?.(e,t));else if(this.options.retryBackoff){const{initial:a,multiplier:r,maxDelay:o}=this.options.retryBackoff,u=Math.min(a*Math.pow(r,s-1),o),d=new Date(Date.now()+u);await this.repository.updateStatus(e.id,n.PENDING),await this.repository.scheduleRetry(e.id,d)}else await this.repository.updateStatus(e.id,n.PENDING)}catch(s){c.internalLogger.error("OutboxProcessor: error updating message status",s instanceof Error?s:void 0,{messageId:e.id})}}scheduleProcessing(e=0,t=this.options.processingInterval){this.isRunning&&(this.processingTimer=setTimeout(async()=>{const s=await this.processBatch();if(this.options.adaptiveRepoll&&s.processed>0&&s.processed>=s.batchSize){const r=e+1,o=r>this.options.adaptiveRepollMaxConsecutive?this.options.adaptiveRepollPauseMs:0;this.scheduleProcessing(r,o)}else this.scheduleProcessing(0,this.options.processingInterval)},t))}scheduleCrashRecovery(){!this.isRunning||this.options.crashRecoveryIntervalMs===void 0||(this.crashRecoveryTimer=setTimeout(async()=>{await this.runCrashRecovery(),this.scheduleCrashRecovery()},this.options.crashRecoveryIntervalMs))}async runCrashRecovery(){const e=new Date(Date.now()-this.options.crashRecoveryThresholdMs),[t,s]=await p.safeRun(()=>this.repository.resetStaleProcessing(e));if(t){c.internalLogger.error("OutboxProcessor: crash recovery failed",t instanceof Error?t:void 0);return}s&&s>0&&c.internalLogger.warn(`OutboxProcessor: crash recovery reset ${s} stale PROCESSING message(s) to PENDING`)}async getStats(){return{isRunning:this.isRunning,batchSize:this.options.batchSize,maxRetries:this.options.maxRetries,processingInterval:this.options.processingInterval,registeredHandlers:Array.from(this.handlers.keys()),middlewareCount:this.middlewares.length,hasDefaultHandler:this.defaultHandler!==void 0}}}class R{constructor(e){this.eventBus=e}async handle(e){const s={eventName:e.messageType.startsWith("integration_event:")?e.messageType.replace("integration_event:",""):e.messageType,eventId:e.id,occurredOn:e.createdAt,version:1,...e.payload,...e.metadata};await this.eventBus.publish(s)}}class P{constructor(e,t={}){this.repository=e,this.options={defaultPriority:t.defaultPriority??l.NORMAL,defaultMetadata:t.defaultMetadata??{},autoCleanup:t.autoCleanup??!1,cleanupAfterDays:t.cleanupAfterDays??7,enableLogging:t.enableLogging??!1}}async saveMessage(e,t,s){const a=h.createMessage(e,t,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...s?.metadata},...s});return await this.repository.saveMessage(a)}async saveMessages(e){const t=e.map(({messageType:a,payload:r,options:o})=>h.createMessage(a,r,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...o?.metadata},...o}));return await this.repository.saveBatch(t)}async scheduleMessage(e,t,s,a){const r=h.createDelayedMessage(e,t,s,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...a?.metadata},...a});return await this.repository.scheduleMessage(r,r.processAfter)}async saveHighPriorityMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:l.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:l.CRITICAL})}async saveDomainEvent(e,t){const s=h.createFromIntegrationEvent({eventName:e.eventName,payload:e,metadata:{eventId:e?.metadata?.eventId,occurredOn:e?.metadata?.occurredOn,version:e?.metadata?.version}},{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...t?.metadata},...t});return await this.repository.saveMessage(s)}async getMessage(e){return this.repository.getById(e)}async getPendingMessages(e=100){return this.repository.getUnprocessedMessages(e)}async retryMessage(e){await this.repository.updateStatus(e,n.PENDING)}async retryMessages(e){await this.repository.updateStatusBatch(e,n.PENDING)}async cleanup(e){const t=e??this.options.cleanupAfterDays,s=new Date;return s.setDate(s.getDate()-t),await this.repository.deleteByStatusAndAge(s,n.PROCESSED)}async getStats(){const e=this.repository;return e.getMessageCountByStatus?{totalPending:e.getMessageCountByStatus(n.PENDING),totalProcessing:e.getMessageCountByStatus(n.PROCESSING),totalProcessed:e.getMessageCountByStatus(n.PROCESSED),totalFailed:e.getMessageCountByStatus(n.FAILED)}:{totalPending:(await this.repository.getUnprocessedMessages(1e3)).length,totalProcessing:0,totalProcessed:0,totalFailed:0}}}exports.EventBusOutboxHandler=R;exports.IOutboxRepository=v;exports.MessagePriority=l;exports.MessageStatus=n;exports.OutboxMessageFactory=h;exports.OutboxProcessor=M;exports.OutboxService=P;exports.comparePriority=f;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export type { IOutboxMessage, OutboxMessageOptions, IOutboxMessageHandler, OutboxMiddleware, OutboxProcessorOptions, OutboxProcessorHooks, RetryBackoffConfig, OutboxServiceOptions, } from './outbox';
 export { MessageStatus, MessagePriority } from './outbox';
+export { comparePriority } from './outbox';
 export { IOutboxRepository, OutboxMessageFactory, OutboxProcessor, EventBusOutboxHandler, OutboxService, } from './outbox';