@vytches/ddd-messaging 0.29.2 → 0.30.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 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||{}),l=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(l||{});const p=["critical","high","normal","low"];function y(i,e,t=p){const s=t.includes(i)?t.indexOf(i):t.length,r=t.includes(e)?t.indexOf(e):t.length;return s-r}class f{scheduleRetry(e,t){return Promise.resolve()}resetStaleProcessing(e){return Promise.resolve(0)}}class g{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||l.NORMAL};return s?.processAfter&&(r.processAfter=s.processAfter),r}static createDelayedMessage(e,t,s,r){const a=new Date(Date.now()+s);return g.createMessage(e,t,{...r,processAfter:a})}static createHighPriorityMessage(e,t,s){return g.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),g.createMessage(`integration_event:${e.eventName}`,e.payload,s)}}class m{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??[l.CRITICAL,l.HIGH,l.NORMAL,l.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}`)}registerDefaultHandler(e){this.defaultHandler=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)??this.defaultHandler;if(!t)throw new Error(`No handler registered for message type: ${e.messageType}`);this.handlers.has(e.messageType)||this.logger.debug(`Default handler used 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,hasDefaultHandler:this.defaultHandler!==void 0}}}class v{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??l.NORMAL,defaultMetadata:t.defaultMetadata??{},autoCleanup:t.autoCleanup??!1,cleanupAfterDays:t.cleanupAfterDays??7,enableLogging:t.enableLogging??!1}}async saveMessage(e,t,s){const r=g.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})=>g.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=g.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:l.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:l.CRITICAL})}async saveDomainEvent(e,t){const s=g.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=v;exports.IOutboxRepository=f;exports.MessagePriority=l;exports.MessageStatus=n;exports.OutboxMessageFactory=g;exports.OutboxProcessor=m;exports.OutboxService=M;exports.comparePriority=y;

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';

package/dist/index.js

@@ -1,7 +1,18 @@
 import { Logger as u } from "@vytches/ddd-logging";
 import { LibUtils as p, safeRun as d } from "@vytches/ddd-utils";
-var n = /* @__PURE__ */ ((i) => (i.PENDING = "PENDING", i.PROCESSING = "PROCESSING", i.PROCESSED = "PROCESSED", i.FAILED = "FAILED", i))(n || {}), g = /* @__PURE__ */ ((i) => (i.LOW = "low", i.NORMAL = "normal", i.HIGH = "high", i.CRITICAL = "critical", i))(g || {});
-class m {
+var n = /* @__PURE__ */ ((i) => (i.PENDING = "PENDING", i.PROCESSING = "PROCESSING", i.PROCESSED = "PROCESSED", i.FAILED = "FAILED", i))(n || {}), l = /* @__PURE__ */ ((i) => (i.LOW = "low", i.NORMAL = "normal", i.HIGH = "high", i.CRITICAL = "critical", i))(l || {});
+const y = [
+  "critical",
+  "high",
+  "normal",
+  "low"
+  /* LOW */
+];
+function v(i, e, t = y) {
+  const s = t.includes(i) ? t.indexOf(i) : t.length, r = t.includes(e) ? t.indexOf(e) : t.length;
+  return s - r;
+}
+class M {
   /**
    * Schedules a retry for a failed message at a specific future time.
    *
@@ -60,7 +71,7 @@ class h {
       status: n.PENDING,
       attempts: 0,
       createdAt: /* @__PURE__ */ new Date(),
-      priority: s?.priority || g.NORMAL
+      priority: s?.priority || l.NORMAL
     };
     return s?.processAfter && (r.processAfter = s.processAfter), r;
   }
@@ -89,7 +100,7 @@ class h {
   static createHighPriorityMessage(e, t, s) {
     return h.createMessage(e, t, {
       ...s,
-      priority: g.HIGH
+      priority: l.HIGH
     });
   }
   /**
@@ -112,17 +123,17 @@ class h {
     );
   }
 }
-class v {
+class R {
   constructor(e, t = {}) {
     this.handlers = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.logger = u.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: l, maxDelay: c } = t.retryBackoff;
-      if (o <= 0 || l <= 0 || c <= 0)
+      const { initial: o, multiplier: g, maxDelay: c } = t.retryBackoff;
+      if (o <= 0 || g <= 0 || c <= 0)
         throw new RangeError(
-          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${l}, maxDelay=${c})`
+          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${g}, maxDelay=${c})`
         );
     }
     const r = t.messageTimeout ?? 3e4, a = t.crashRecoveryThresholdMs ?? Math.max(3e5, r);
@@ -135,10 +146,10 @@ class v {
       maxRetries: t.maxRetries ?? 3,
       processingInterval: t.processingInterval ?? 5e3,
       priorityOrder: t.priorityOrder ?? [
-        g.CRITICAL,
-        g.HIGH,
-        g.NORMAL,
-        g.LOW
+        l.CRITICAL,
+        l.HIGH,
+        l.NORMAL,
+        l.LOW
       ],
       messageTimeout: r,
       enableLogging: t.enableLogging ?? !1,
@@ -172,6 +183,25 @@ class v {
   registerHandler(e, t) {
     this.handlers.set(e, t), this.logger.debug(`Registered handler for message type: ${e}`);
   }
+  /**
+   * Registers a catch-all handler invoked when no type-specific handler matches.
+   *
+   * NOTE: Registering a default handler removes the implicit type allowlist —
+   * all future message types, including ones added by mistake or injected via
+   * compromised storage, will be dispatched to this handler. Validate
+   * `message.messageType` inside the handler against a known-types set if your
+   * domain requires an explicit allowlist.
+   *
+   * NOTE: When `messageTypes` filter option is set, the default handler handles
+   * only types that pass through that filter. To handle all types, leave
+   * `messageTypes` unset.
+   *
+   * Calling this method a second time silently replaces the previous default
+   * handler (idempotent).
+   */
+  registerDefaultHandler(e) {
+    this.defaultHandler = e;
+  }
   /**
    * Registers middleware for message processing pipeline
    */
@@ -248,7 +278,7 @@ class v {
     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(), l = (await Promise.allSettled(
+    const a = Date.now(), g = (await Promise.allSettled(
       r.map((c) => this.processMessage(c))
     )).filter(
       (c) => c.status === "rejected" || c.status === "fulfilled" && c.value === !1
@@ -257,7 +287,7 @@ class v {
       "onBatchComplete",
       () => this.options.hooks?.onBatchComplete?.({
         processed: r.length,
-        failed: l,
+        failed: g,
         batchSize: e,
         durationMs: Date.now() - a
       })
@@ -277,9 +307,10 @@ class v {
    * Builds the middleware pipeline for message processing
    */
   buildPipeline(e) {
-    const t = this.handlers.get(e.messageType);
+    const t = this.handlers.get(e.messageType) ?? this.defaultHandler;
     if (!t)
       throw new Error(`No handler registered for message type: ${e.messageType}`);
+    this.handlers.has(e.messageType) || this.logger.debug(`Default handler used for message type: ${e.messageType}`);
     const s = async (r) => {
       await Promise.race([
         t.handle(r),
@@ -308,9 +339,9 @@ class v {
           () => this.options.hooks?.onPermanentFailure?.(e, t)
         );
       else if (this.options.retryBackoff) {
-        const { initial: r, multiplier: a, maxDelay: o } = this.options.retryBackoff, l = Math.min(r * Math.pow(a, s - 1), o), c = new Date(Date.now() + l);
+        const { initial: r, multiplier: a, maxDelay: o } = this.options.retryBackoff, g = Math.min(r * Math.pow(a, s - 1), o), c = new Date(Date.now() + g);
         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 ${l}ms (attempt ${s})`
+          `Message ${e.id} scheduled for retry in ${g}ms (attempt ${s})`
         );
       } else
         await this.repository.updateStatus(e.id, n.PENDING), this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s + 1})`);
@@ -380,11 +411,12 @@ class v {
       maxRetries: this.options.maxRetries,
       processingInterval: this.options.processingInterval,
       registeredHandlers: Array.from(this.handlers.keys()),
-      middlewareCount: this.middlewares.length
+      middlewareCount: this.middlewares.length,
+      hasDefaultHandler: this.defaultHandler !== void 0
     };
   }
 }
-class M {
+class w {
   constructor(e) {
     this.eventBus = e;
   }
@@ -400,10 +432,10 @@ class M {
     await this.eventBus.publish(s);
   }
 }
-class R {
+class P {
   constructor(e, t = {}) {
     this.logger = u.create("OutboxService"), this.repository = e, this.options = {
-      defaultPriority: t.defaultPriority ?? g.NORMAL,
+      defaultPriority: t.defaultPriority ?? l.NORMAL,
       defaultMetadata: t.defaultMetadata ?? {},
       autoCleanup: t.autoCleanup ?? !1,
       cleanupAfterDays: t.cleanupAfterDays ?? 7,
@@ -453,7 +485,7 @@ class R {
   async saveHighPriorityMessage(e, t, s) {
     return this.saveMessage(e, t, {
       ...s,
-      priority: g.HIGH
+      priority: l.HIGH
     });
   }
   /**
@@ -462,7 +494,7 @@ class R {
   async saveCriticalMessage(e, t, s) {
     return this.saveMessage(e, t, {
       ...s,
-      priority: g.CRITICAL
+      priority: l.CRITICAL
     });
   }
   /**
@@ -551,11 +583,12 @@ class R {
   }
 }
 export {
-  M as EventBusOutboxHandler,
-  m as IOutboxRepository,
-  g as MessagePriority,
+  w as EventBusOutboxHandler,
+  M as IOutboxRepository,
+  l as MessagePriority,
   n as MessageStatus,
   h as OutboxMessageFactory,
-  v as OutboxProcessor,
-  R as OutboxService
+  R as OutboxProcessor,
+  P as OutboxService,
+  v as comparePriority
 };

package/dist/outbox/outbox-interfaces.d.ts

@@ -48,3 +48,22 @@ export interface IOutboxMessageHandler<T = unknown> {
     handle(message: IOutboxMessage<T>): Promise<void>;
 }
 export type OutboxMiddleware = (next: (message: IOutboxMessage) => Promise<void>) => (message: IOutboxMessage) => Promise<void>;
+/**
+ * Compares two MessagePriority values for sorting purposes.
+ *
+ * Returns a negative number if `a` should be processed before `b`,
+ * positive if `b` before `a`, 0 if equal.
+ *
+ * @param order - Processing order array (first element = highest priority).
+ *   Defaults to [CRITICAL, HIGH, NORMAL, LOW].
+ *   Values absent from the array sort LAST (treated as lowest priority).
+ *   Passing a partial array is safe — missing values are not promoted.
+ *
+ * @example
+ * // Sort messages by priority (highest first):
+ * messages.sort((a, b) => comparePriority(a.priority, b.priority));
+ *
+ * // Custom order:
+ * messages.sort((a, b) => comparePriority(a.priority, b.priority, ['high', 'critical', 'normal', 'low']));
+ */
+export declare function comparePriority(a: MessagePriority, b: MessagePriority, order?: MessagePriority[]): number;

package/dist/outbox/outbox-processor.d.ts

@@ -85,6 +85,7 @@ export declare class OutboxProcessor {
     private readonly repository;
     private readonly options;
     private readonly handlers;
+    private defaultHandler?;
     private readonly middlewares;
     private isRunning;
     private processingTimer?;
@@ -100,6 +101,23 @@ export declare class OutboxProcessor {
      * Registers a message handler for a specific message type
      */
     registerHandler(messageType: string, handler: IOutboxMessageHandler): void;
+    /**
+     * Registers a catch-all handler invoked when no type-specific handler matches.
+     *
+     * NOTE: Registering a default handler removes the implicit type allowlist —
+     * all future message types, including ones added by mistake or injected via
+     * compromised storage, will be dispatched to this handler. Validate
+     * `message.messageType` inside the handler against a known-types set if your
+     * domain requires an explicit allowlist.
+     *
+     * NOTE: When `messageTypes` filter option is set, the default handler handles
+     * only types that pass through that filter. To handle all types, leave
+     * `messageTypes` unset.
+     *
+     * Calling this method a second time silently replaces the previous default
+     * handler (idempotent).
+     */
+    registerDefaultHandler(handler: IOutboxMessageHandler): void;
     /**
      * Registers middleware for message processing pipeline
      */
@@ -196,6 +214,7 @@ export declare class OutboxProcessor {
         processingInterval: number;
         registeredHandlers: string[];
         middlewareCount: number;
+        hasDefaultHandler: boolean;
     }>;
 }
 export declare class EventBusOutboxHandler implements IOutboxMessageHandler {

package/dist/outbox/outbox-repository.interface.d.ts

@@ -13,14 +13,19 @@ export declare abstract class IOutboxRepository {
      */
     abstract saveBatch<T = unknown>(messages: IOutboxMessage<T>[]): Promise<string[]>;
     /**
-     * Gets unprocessed messages from the outbox
-     * @param limit Maximum number of messages to retrieve
-     * @param priorityOrder Order of priority for processing (default: [CRITICAL, HIGH, NORMAL, LOW])
-     * @param messageTypes Optional allow-list of message types to fetch. When
-     *   provided, only messages whose `messageType` is in this list are returned
-     *   (e.g. `WHERE message_type IN (...)`). Omitting it fetches all types —
-     *   this parameter is optional and backward-compatible.
-     * @returns Unprocessed messages
+     * Returns unprocessed messages up to the given limit.
+     *
+     * @param limit - Maximum number of messages to return.
+     * @param priorityOrder - Ordered array of MessagePriority values defining
+     *   processing order (first element = highest priority, processed first).
+     *   Implementations MUST sort results by the position of each message's
+     *   priority in this array — do NOT use ORDER BY priority directly on the
+     *   string column. Alphabetical sort inverts the intent: 'critical' sorts
+     *   after 'high' alphabetically, causing CRITICAL messages to be processed
+     *   last. Use comparePriority() or array index-based sorting instead.
+     * @param messageTypes - Optional allow-list of message types to return.
+     *   When provided, only messages whose messageType is in this array are
+     *   returned. When absent, all message types are returned.
      */
     abstract getUnprocessedMessages(limit?: number, priorityOrder?: MessagePriority[], messageTypes?: string[]): Promise<IOutboxMessage[]>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-messaging",
-  "version": "0.29.2",
+  "version": "0.30.0",
   "description": "Outbox pattern and reliable message delivery",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@vytches/ddd-events": "0.29.2"
+    "@vytches/ddd-events": "0.30.0"
   },
   "scripts": {
     "build": "vite build",