@vytches/ddd-messaging 0.27.0 → 0.28.0

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("@vytches/ddd-logging"),d=require("@vytches/ddd-utils");var o=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(o||{}),n=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(n||{});class u{}class g{static createMessage(e,t,s){const r={id:d.LibUtils.getUUID(),messageType:e,payload:t,metadata:s?.metadata||{},status:o.PENDING,attempts:0,createdAt:new Date,priority:s?.priority||n.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:n.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 h{constructor(e,t={}){this.handlers=new Map,this.middlewares=[],this.isRunning=!1,this.logger=l.Logger.create("OutboxProcessor"),this.repository=e,this.options={batchSize:t.batchSize??10,maxRetries:t.maxRetries??3,processingInterval:t.processingInterval??5e3,priorityOrder:t.priorityOrder??[n.CRITICAL,n.HIGH,n.NORMAL,n.LOW],messageTimeout:t.messageTimeout??3e4,enableLogging:t.enableLogging??!1}}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"),this.scheduleProcessing()}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.logger.info("Stopped outbox processor")}async processBatch(){if(!this.isRunning)return;const[e,t]=await d.safeRun(()=>this.repository.getUnprocessedMessages(this.options.batchSize,this.options.priorityOrder));if(e){const a=e instanceof Error?e.message:String(e);this.logger.error(`Error retrieving messages: ${a}`);return}const s=t;if(!s||!Array.isArray(s)||s.length===0){this.logger.debug("No pending messages to process");return}this.logger.info(`Processing ${s.length} messages`);const r=s.map(a=>this.processMessage(a));await Promise.allSettled(r),this.logger.info(`Completed processing batch of ${s.length} messages`)}async processMessage(e){const[t]=await d.safeRun(async()=>{await this.repository.updateStatus(e.id,o.PROCESSING),await this.buildPipeline(e)(e),await this.repository.updateStatus(e.id,o.PROCESSED),this.logger.debug(`Successfully processed message ${e.id}`)});t&&await this.handleMessageError(e,t)}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,c)=>setTimeout(()=>c(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);this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`),s>=this.options.maxRetries?(await this.repository.updateStatus(e.id,o.FAILED,t),this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`)):(await this.repository.updateStatus(e.id,o.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(){this.isRunning&&(this.processingTimer=setTimeout(async()=>{await this.processBatch(),this.scheduleProcessing()},this.options.processingInterval))}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 p{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 y{constructor(e,t={}){this.logger=l.Logger.create("OutboxService"),this.repository=e,this.options={defaultPriority:t.defaultPriority??n.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:c})=>g.createMessage(r,a,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...c?.metadata},...c})),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}),c=await this.repository.scheduleMessage(a,a.processAfter);return this.logger.debug(`Scheduled message ${c} of type ${e} for processing in ${s}ms`),c}async saveHighPriorityMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:n.HIGH})}async saveCriticalMessage(e,t,s){return this.saveMessage(e,t,{...s,priority:n.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,o.PENDING),this.logger.info(`Reset message ${e} to pending for retry`)}async retryMessages(e){await this.repository.updateStatusBatch(e,o.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,o.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(o.PENDING),totalProcessing:e.getMessageCountByStatus(o.PROCESSING),totalProcessed:e.getMessageCountByStatus(o.PROCESSED),totalFailed:e.getMessageCountByStatus(o.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=p;exports.IOutboxRepository=u;exports.MessagePriority=n;exports.MessageStatus=o;exports.OutboxMessageFactory=g;exports.OutboxProcessor=h;exports.OutboxService=y;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@vytches/ddd-logging"),d=require("@vytches/ddd-utils");var o=(i=>(i.PENDING="PENDING",i.PROCESSING="PROCESSING",i.PROCESSED="PROCESSED",i.FAILED="FAILED",i))(o||{}),g=(i=>(i.LOW="low",i.NORMAL="normal",i.HIGH="high",i.CRITICAL="critical",i))(g||{});class p{scheduleRetry(e,t){return Promise.resolve()}}class c{static createMessage(e,t,s){const r={id:d.LibUtils.getUUID(),messageType:e,payload:t,metadata:s?.metadata||{},status:o.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 c.createMessage(e,t,{...r,processAfter:a})}static createHighPriorityMessage(e,t,s){return c.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),c.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:r,multiplier:a,maxDelay:n}=t.retryBackoff;if(r<=0||a<=0||n<=0)throw new RangeError(`OutboxProcessor: retryBackoff fields must be positive numbers (initial=${r}, multiplier=${a}, maxDelay=${n})`)}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:t.messageTimeout??3e4,enableLogging:t.enableLogging??!1,retryBackoff:t.retryBackoff}}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"),this.scheduleProcessing()}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.logger.info("Stopped outbox processor")}async processBatch(){if(!this.isRunning)return;const[e,t]=await d.safeRun(()=>this.repository.getUnprocessedMessages(this.options.batchSize,this.options.priorityOrder));if(e){const a=e instanceof Error?e.message:String(e);this.logger.error(`Error retrieving messages: ${a}`);return}const s=t;if(!s||!Array.isArray(s)||s.length===0){this.logger.debug("No pending messages to process");return}this.logger.info(`Processing ${s.length} messages`);const r=s.map(a=>this.processMessage(a));await Promise.allSettled(r),this.logger.info(`Completed processing batch of ${s.length} messages`)}async processMessage(e){const[t]=await d.safeRun(async()=>{await this.repository.updateStatus(e.id,o.PROCESSING),await this.buildPipeline(e)(e),await this.repository.updateStatus(e.id,o.PROCESSED),this.logger.debug(`Successfully processed message ${e.id}`)});t&&await this.handleMessageError(e,t)}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,n)=>setTimeout(()=>n(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}`),s>=this.options.maxRetries)await this.repository.updateStatus(e.id,o.FAILED,t),this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`);else if(this.options.retryBackoff){const{initial:r,multiplier:a,maxDelay:n}=this.options.retryBackoff,l=Math.min(r*Math.pow(a,s-1),n),h=new Date(Date.now()+l);await this.repository.updateStatus(e.id,o.PENDING),await this.repository.scheduleRetry(e.id,h),this.logger.info(`Message ${e.id} scheduled for retry in ${l}ms (attempt ${s})`)}else await this.repository.updateStatus(e.id,o.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(){this.isRunning&&(this.processingTimer=setTimeout(async()=>{await this.processBatch(),this.scheduleProcessing()},this.options.processingInterval))}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=c.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:n})=>c.createMessage(r,a,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...n?.metadata},...n})),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=c.createDelayedMessage(e,t,s,{priority:this.options.defaultPriority,metadata:{...this.options.defaultMetadata,...r?.metadata},...r}),n=await this.repository.scheduleMessage(a,a.processAfter);return this.logger.debug(`Scheduled message ${n} of type ${e} for processing in ${s}ms`),n}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=c.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,o.PENDING),this.logger.info(`Reset message ${e} to pending for retry`)}async retryMessages(e){await this.repository.updateStatusBatch(e,o.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,o.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(o.PENDING),totalProcessing:e.getMessageCountByStatus(o.PROCESSING),totalProcessed:e.getMessageCountByStatus(o.PROCESSED),totalFailed:e.getMessageCountByStatus(o.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=o;exports.OutboxMessageFactory=c;exports.OutboxProcessor=y;exports.OutboxService=m;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,9 +1,28 @@
-import { Logger as l } from "@vytches/ddd-logging";
-import { LibUtils as h, safeRun as d } from "@vytches/ddd-utils";
-var o = /* @__PURE__ */ ((i) => (i.PENDING = "PENDING", i.PROCESSING = "PROCESSING", i.PROCESSED = "PROCESSED", i.FAILED = "FAILED", i))(o || {}), n = /* @__PURE__ */ ((i) => (i.LOW = "low", i.NORMAL = "normal", i.HIGH = "high", i.CRITICAL = "critical", i))(n || {});
-class y {
+import { Logger as h } from "@vytches/ddd-logging";
+import { LibUtils as p, safeRun as l } from "@vytches/ddd-utils";
+var o = /* @__PURE__ */ ((i) => (i.PENDING = "PENDING", i.PROCESSING = "PROCESSING", i.PROCESSED = "PROCESSED", i.FAILED = "FAILED", i))(o || {}), g = /* @__PURE__ */ ((i) => (i.LOW = "low", i.NORMAL = "normal", i.HIGH = "high", i.CRITICAL = "critical", i))(g || {});
+class m {
+  /**
+   * Schedules a retry for a failed message at a specific future time.
+   *
+   * Default implementation is a no-op — repositories that do not support
+   * delayed processing will fall back to immediate retry (PENDING reset).
+   * Override this in concrete repositories to enable exponential backoff.
+   *
+   * **Multi-worker note:** `OutboxProcessor` calls `updateStatus(PENDING)` immediately
+   * before this method. In multi-worker environments, override this to perform
+   * an atomic `UPDATE ... SET status=PENDING, process_after=?` in a single statement,
+   * and ensure `getUnprocessedMessages` filters `WHERE process_after IS NULL OR process_after <= NOW()`
+   * to prevent duplicate dispatch during the window between the two calls.
+   *
+   * @param id Message ID
+   * @param processAfter When to retry the message
+   */
+  scheduleRetry(e, t) {
+    return Promise.resolve();
+  }
 }
-class g {
+class c {
   /**
    * Creates a new outbox message
    * @param messageType Type of the message
@@ -13,14 +32,14 @@ class g {
    */
   static createMessage(e, t, s) {
     const r = {
-      id: h.getUUID(),
+      id: p.getUUID(),
       messageType: e,
       payload: t,
       metadata: s?.metadata || {},
       status: o.PENDING,
       attempts: 0,
       createdAt: /* @__PURE__ */ new Date(),
-      priority: s?.priority || n.NORMAL
+      priority: s?.priority || g.NORMAL
     };
     return s?.processAfter && (r.processAfter = s.processAfter), r;
   }
@@ -34,7 +53,7 @@ class g {
    */
   static createDelayedMessage(e, t, s, r) {
     const a = new Date(Date.now() + s);
-    return g.createMessage(e, t, {
+    return c.createMessage(e, t, {
       ...r,
       processAfter: a
     });
@@ -47,9 +66,9 @@ class g {
    * @returns High priority outbox message
    */
   static createHighPriorityMessage(e, t, s) {
-    return g.createMessage(e, t, {
+    return c.createMessage(e, t, {
       ...s,
-      priority: n.HIGH
+      priority: g.HIGH
     });
   }
   /**
@@ -65,27 +84,39 @@ class g {
         ...t?.metadata || {}
       }
     };
-    return t?.priority && (s.priority = t.priority), t?.processAfter && (s.processAfter = t.processAfter), g.createMessage(
+    return t?.priority && (s.priority = t.priority), t?.processAfter && (s.processAfter = t.processAfter), c.createMessage(
       `integration_event:${e.eventName}`,
       e.payload,
       s
     );
   }
 }
-class m {
+class w {
   constructor(e, t = {}) {
-    this.handlers = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.logger = l.create("OutboxProcessor"), this.repository = e, this.options = {
-      batchSize: t.batchSize ?? 10,
+    this.handlers = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.logger = h.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: r, multiplier: a, maxDelay: n } = t.retryBackoff;
+      if (r <= 0 || a <= 0 || n <= 0)
+        throw new RangeError(
+          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${r}, multiplier=${a}, maxDelay=${n})`
+        );
+    }
+    this.repository = e, this.options = {
+      batchSize: s,
       maxRetries: t.maxRetries ?? 3,
       processingInterval: t.processingInterval ?? 5e3,
       priorityOrder: t.priorityOrder ?? [
-        n.CRITICAL,
-        n.HIGH,
-        n.NORMAL,
-        n.LOW
+        g.CRITICAL,
+        g.HIGH,
+        g.NORMAL,
+        g.LOW
       ],
       messageTimeout: t.messageTimeout ?? 3e4,
-      enableLogging: t.enableLogging ?? !1
+      enableLogging: t.enableLogging ?? !1,
+      retryBackoff: t.retryBackoff
     };
   }
   /**
@@ -148,7 +179,7 @@ class m {
   async processBatch() {
     if (!this.isRunning)
       return;
-    const [e, t] = await d(
+    const [e, t] = await l(
       () => this.repository.getUnprocessedMessages(this.options.batchSize, this.options.priorityOrder)
     );
     if (e) {
@@ -169,7 +200,7 @@ class m {
    * Processes a single message through the middleware pipeline
    */
   async processMessage(e) {
-    const [t] = await d(async () => {
+    const [t] = await l(async () => {
       await this.repository.updateStatus(e.id, o.PROCESSING), await this.buildPipeline(e)(e), await this.repository.updateStatus(e.id, o.PROCESSED), this.logger.debug(`Successfully processed message ${e.id}`);
     });
     t && await this.handleMessageError(e, t);
@@ -185,8 +216,8 @@ class m {
       await Promise.race([
         t.handle(r),
         new Promise(
-          (a, c) => setTimeout(
-            () => c(new Error("Message processing timeout")),
+          (a, n) => setTimeout(
+            () => n(new Error("Message processing timeout")),
             this.options.messageTimeout
           )
         )
@@ -200,7 +231,15 @@ class m {
   async handleMessageError(e, t) {
     try {
       const s = await this.repository.incrementAttempt(e.id);
-      this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`), s >= this.options.maxRetries ? (await this.repository.updateStatus(e.id, o.FAILED, t), this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`)) : (await this.repository.updateStatus(e.id, o.PENDING), this.logger.info(`Message ${e.id} scheduled for retry (attempt ${s + 1})`));
+      if (this.logger.warn(`Message ${e.id} failed, attempt ${s}: ${t?.message}`), s >= this.options.maxRetries)
+        await this.repository.updateStatus(e.id, o.FAILED, t), this.logger.error(`Message ${e.id} marked as failed after ${s} attempts`);
+      else if (this.options.retryBackoff) {
+        const { initial: r, multiplier: a, maxDelay: n } = this.options.retryBackoff, d = Math.min(r * Math.pow(a, s - 1), n), u = new Date(Date.now() + d);
+        await this.repository.updateStatus(e.id, o.PENDING), await this.repository.scheduleRetry(e.id, u), this.logger.info(
+          `Message ${e.id} scheduled for retry in ${d}ms (attempt ${s})`
+        );
+      } else
+        await this.repository.updateStatus(e.id, o.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}`);
@@ -234,7 +273,7 @@ class m {
     };
   }
 }
-class f {
+class M {
   constructor(e) {
     this.eventBus = e;
   }
@@ -250,10 +289,10 @@ class f {
     await this.eventBus.publish(s);
   }
 }
-class M {
+class S {
   constructor(e, t = {}) {
-    this.logger = l.create("OutboxService"), this.repository = e, this.options = {
-      defaultPriority: t.defaultPriority ?? n.NORMAL,
+    this.logger = h.create("OutboxService"), this.repository = e, this.options = {
+      defaultPriority: t.defaultPriority ?? g.NORMAL,
       defaultMetadata: t.defaultMetadata ?? {},
       autoCleanup: t.autoCleanup ?? !1,
       cleanupAfterDays: t.cleanupAfterDays ?? 7,
@@ -264,7 +303,7 @@ class M {
    * Saves a message to the outbox
    */
   async saveMessage(e, t, s) {
-    const r = g.createMessage(e, t, {
+    const r = c.createMessage(e, t, {
       priority: this.options.defaultPriority,
       metadata: { ...this.options.defaultMetadata, ...s?.metadata },
       ...s
@@ -276,10 +315,10 @@ class M {
    */
   async saveMessages(e) {
     const t = e.map(
-      ({ messageType: r, payload: a, options: c }) => g.createMessage(r, a, {
+      ({ messageType: r, payload: a, options: n }) => c.createMessage(r, a, {
         priority: this.options.defaultPriority,
-        metadata: { ...this.options.defaultMetadata, ...c?.metadata },
-        ...c
+        metadata: { ...this.options.defaultMetadata, ...n?.metadata },
+        ...n
       })
     ), s = await this.repository.saveBatch(t);
     return this.logger.debug(`Saved batch of ${e.length} messages`), s;
@@ -288,14 +327,14 @@ class M {
    * Schedules a message for delayed processing
    */
   async scheduleMessage(e, t, s, r) {
-    const a = g.createDelayedMessage(e, t, s, {
+    const a = c.createDelayedMessage(e, t, s, {
       priority: this.options.defaultPriority,
       metadata: { ...this.options.defaultMetadata, ...r?.metadata },
       ...r
-    }), c = await this.repository.scheduleMessage(a, a.processAfter);
+    }), n = await this.repository.scheduleMessage(a, a.processAfter);
     return this.logger.debug(
-      `Scheduled message ${c} of type ${e} for processing in ${s}ms`
-    ), c;
+      `Scheduled message ${n} of type ${e} for processing in ${s}ms`
+    ), n;
   }
   /**
    * Saves a high priority message to the outbox
@@ -303,7 +342,7 @@ class M {
   async saveHighPriorityMessage(e, t, s) {
     return this.saveMessage(e, t, {
       ...s,
-      priority: n.HIGH
+      priority: g.HIGH
     });
   }
   /**
@@ -312,14 +351,14 @@ class M {
   async saveCriticalMessage(e, t, s) {
     return this.saveMessage(e, t, {
       ...s,
-      priority: n.CRITICAL
+      priority: g.CRITICAL
     });
   }
   /**
    * Converts a domain event to an outbox message and saves it
    */
   async saveDomainEvent(e, t) {
-    const s = g.createFromIntegrationEvent(
+    const s = c.createFromIntegrationEvent(
       {
         eventName: e.eventName,
         payload: e,
@@ -401,11 +440,11 @@ class M {
   }
 }
 export {
-  f as EventBusOutboxHandler,
-  y as IOutboxRepository,
-  n as MessagePriority,
+  M as EventBusOutboxHandler,
+  m as IOutboxRepository,
+  g as MessagePriority,
   o as MessageStatus,
-  g as OutboxMessageFactory,
-  m as OutboxProcessor,
-  M as OutboxService
+  c as OutboxMessageFactory,
+  w as OutboxProcessor,
+  S as OutboxService
 };

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

@@ -1,6 +1,14 @@
 import { IEventBus } from '../../../contracts/src/index.ts';
 import { IOutboxMessage, IOutboxMessageHandler, OutboxMiddleware, MessagePriority } from './outbox-interfaces';
 import { IOutboxRepository } from './outbox-repository.interface';
+export interface RetryBackoffConfig {
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initial: number;
+    /** Multiplier applied per subsequent attempt (default: 2) */
+    multiplier: number;
+    /** Maximum delay cap in milliseconds (default: 300_000 — 5 min) */
+    maxDelay: number;
+}
 export interface OutboxProcessorOptions {
     /** Maximum number of messages to process in one batch */
     batchSize?: number;
@@ -14,6 +22,15 @@ export interface OutboxProcessorOptions {
     messageTimeout?: number;
     /** Enable logging */
     enableLogging?: boolean;
+    /**
+     * Exponential backoff for retries.
+     * When set, failed messages are scheduled for future retry via
+     * `IOutboxRepository.scheduleRetry()` instead of immediately re-queued.
+     * If the repository's `scheduleRetry` is a no-op, messages fall back to
+     * immediate PENDING reset (legacy behavior).
+     * If omitted, immediate retry is used for all messages.
+     */
+    retryBackoff?: RetryBackoffConfig;
 }
 export declare class OutboxProcessor {
     private readonly repository;

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

@@ -58,4 +58,21 @@ export declare abstract class IOutboxRepository {
      * @returns ID of the saved message
      */
     abstract scheduleMessage<T = unknown>(message: IOutboxMessage<T>, processAfter: Date): Promise<string>;
+    /**
+     * Schedules a retry for a failed message at a specific future time.
+     *
+     * Default implementation is a no-op — repositories that do not support
+     * delayed processing will fall back to immediate retry (PENDING reset).
+     * Override this in concrete repositories to enable exponential backoff.
+     *
+     * **Multi-worker note:** `OutboxProcessor` calls `updateStatus(PENDING)` immediately
+     * before this method. In multi-worker environments, override this to perform
+     * an atomic `UPDATE ... SET status=PENDING, process_after=?` in a single statement,
+     * and ensure `getUnprocessedMessages` filters `WHERE process_after IS NULL OR process_after <= NOW()`
+     * to prevent duplicate dispatch during the window between the two calls.
+     *
+     * @param id Message ID
+     * @param processAfter When to retry the message
+     */
+    scheduleRetry(_id: string, _processAfter: Date): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-messaging",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Outbox pattern and reliable message delivery",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -36,8 +36,8 @@
     "typescript": "^5.0.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.0.0",
-    "vitest": "^2.0.0",
-    "@vytches/ddd-testing": "0.27.0"
+    "vitest": "^4.0.0",
+    "@vytches/ddd-testing": "0.28.0"
   },
   "nx": {
     "tags": [
@@ -51,7 +51,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@vytches/ddd-events": "0.27.0"
+    "@vytches/ddd-events": "0.28.0"
   },
   "scripts": {
     "build": "vite build",