@vytches/ddd-messaging 0.27.0 → 0.29.1

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

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, OutboxProcessorHooks, RetryBackoffConfig, OutboxServiceOptions, } from './outbox';
 export { MessageStatus, MessagePriority } from './outbox';
 export { IOutboxRepository, OutboxMessageFactory, OutboxProcessor, EventBusOutboxHandler, OutboxService, } from './outbox';

package/dist/index.js

@@ -1,9 +1,49 @@
-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 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 {
+  /**
+   * 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();
+  }
+  /**
+   * Resets messages stuck in `PROCESSING` back to `PENDING` so they can be
+   * re-dispatched. Used for crash recovery: if a worker dies mid-batch, its
+   * in-flight messages remain `PROCESSING` forever without this.
+   *
+   * Default implementation is a no-op returning `0` — repositories that do not
+   * track a per-message "processing since" timestamp simply opt out. Override
+   * in concrete repositories, e.g.:
+   * `UPDATE outbox_messages SET status='PENDING' WHERE status='PROCESSING' AND updated_at < olderThan`.
+   *
+   * **Safety:** implementations MUST only reset messages whose processing
+   * started strictly before `olderThan`. `OutboxProcessor` always passes a past
+   * timestamp (`now - crashRecoveryThresholdMs`, with the threshold validated to
+   * be `>= messageTimeout`), so legitimately in-flight messages are never reset.
+   *
+   * @param olderThan Reset only `PROCESSING` messages last touched before this instant
+   * @returns Number of messages reset to `PENDING`
+   */
+  resetStaleProcessing(e) {
+    return Promise.resolve(0);
+  }
 }
-class g {
+class h {
   /**
    * Creates a new outbox message
    * @param messageType Type of the message
@@ -13,14 +53,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,
+      status: n.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 +74,7 @@ class g {
    */
   static createDelayedMessage(e, t, s, r) {
     const a = new Date(Date.now() + s);
-    return g.createMessage(e, t, {
+    return h.createMessage(e, t, {
       ...r,
       processAfter: a
     });
@@ -47,9 +87,9 @@ class g {
    * @returns High priority outbox message
    */
   static createHighPriorityMessage(e, t, s) {
-    return g.createMessage(e, t, {
+    return h.createMessage(e, t, {
       ...s,
-      priority: n.HIGH
+      priority: g.HIGH
     });
   }
   /**
@@ -65,29 +105,67 @@ 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), h.createMessage(
       `integration_event:${e.eventName}`,
       e.payload,
       s
     );
   }
 }
-class m {
+class v {
   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 = 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)
+        throw new RangeError(
+          `OutboxProcessor: retryBackoff fields must be positive numbers (initial=${o}, multiplier=${l}, 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 ?? [
-        n.CRITICAL,
-        n.HIGH,
-        n.NORMAL,
-        n.LOW
+        g.CRITICAL,
+        g.HIGH,
+        g.NORMAL,
+        g.LOW
       ],
-      messageTimeout: t.messageTimeout ?? 3e4,
-      enableLogging: t.enableLogging ?? !1
+      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
     };
   }
+  /**
+   * Invokes an observability hook in isolation. A throwing hook is logged and
+   * swallowed so it can never break the processing loop (mitigation T3).
+   */
+  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}`);
+      }
+  }
   /**
    * Registers a message handler for a specific message type
    */
@@ -108,7 +186,9 @@ class m {
       this.logger.warn("Processor is already running");
       return;
     }
-    this.isRunning = !0, this.logger.info("Starting outbox processor"), this.scheduleProcessing();
+    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();
   }
   /**
    * Stops the processor
@@ -118,7 +198,7 @@ class m {
       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");
+    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");
   }
   /**
    * Processes a single batch of pending messages.
@@ -141,38 +221,57 @@ class m {
    * **Quiescence:** if there are no pending messages, returns immediately
    * without invoking handlers.
    *
+   * @returns `{ processed, batchSize }` — `processed` is how many messages were
+   *   dispatched this batch, `batchSize` the configured limit. A full batch
+   *   (`processed >= batchSize`) signals a likely backlog. Callers that ignore
+   *   the return value are unaffected (the value was previously `void`).
    * @public
    * @stable
    * @since 0.1.0
    */
   async processBatch() {
+    const e = this.options.batchSize;
     if (!this.isRunning)
-      return;
-    const [e, t] = await d(
-      () => this.repository.getUnprocessedMessages(this.options.batchSize, this.options.priorityOrder)
+      return { processed: 0, batchSize: e };
+    const [t, s] = await d(
+      () => this.repository.getUnprocessedMessages(
+        e,
+        this.options.priorityOrder,
+        this.options.messageTypes
+      )
     );
-    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;
+    if (t) {
+      const c = t instanceof Error ? t.message : String(t);
+      return this.logger.error(`Error retrieving messages: ${c}`), { processed: 0, batchSize: e };
     }
-    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`);
+    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(), l = (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: l,
+        batchSize: e,
+        durationMs: Date.now() - a
+      })
+    ), { processed: r.length, batchSize: e };
   }
   /**
-   * Processes a single message through the middleware pipeline
+   * Processes a single message through the middleware pipeline.
+   * @returns `true` if the message was processed successfully, `false` if it failed.
    */
   async processMessage(e) {
     const [t] = await d(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}`);
+      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}`);
     });
-    t && await this.handleMessageError(e, t);
+    return t ? (await this.handleMessageError(e, t), !1) : !0;
   }
   /**
    * Builds the middleware pipeline for message processing
@@ -185,8 +284,8 @@ class m {
       await Promise.race([
         t.handle(r),
         new Promise(
-          (a, c) => setTimeout(
-            () => c(new Error("Message processing timeout")),
+          (a, o) => setTimeout(
+            () => o(new Error("Message processing timeout")),
             this.options.messageTimeout
           )
         )
@@ -200,19 +299,70 @@ 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}`), 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, l = Math.min(r * Math.pow(a, s - 1), o), c = new Date(Date.now() + l);
+        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})`
+        );
+      } 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}`);
     }
   }
   /**
-   * Schedules the next processing cycle
+   * Schedules the next processing cycle.
+   *
+   * With `adaptiveRepoll` enabled, a full batch re-polls immediately (`delay 0`)
+   * to drain a backlog — until `adaptiveRepollMaxConsecutive` consecutive full
+   * batches trip the livelock guard, after which an `adaptiveRepollPauseMs`
+   * pause is inserted. Any non-full batch resets the cadence to
+   * `processingInterval`.
+   *
+   * @param consecutiveFullBatches running count of back-to-back full batches
+   * @param delay milliseconds to wait before the next batch
    */
-  scheduleProcessing() {
+  scheduleProcessing(e = 0, t = this.options.processingInterval) {
     this.isRunning && (this.processingTimer = setTimeout(async () => {
-      await this.processBatch(), this.scheduleProcessing();
-    }, this.options.processingInterval));
+      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));
+  }
+  /**
+   * Schedules the next crash-recovery cycle. No-op unless
+   * `crashRecoveryIntervalMs` was configured.
+   */
+  scheduleCrashRecovery() {
+    !this.isRunning || this.options.crashRecoveryIntervalMs === void 0 || (this.crashRecoveryTimer = setTimeout(async () => {
+      await this.runCrashRecovery(), this.scheduleCrashRecovery();
+    }, this.options.crashRecoveryIntervalMs));
+  }
+  /**
+   * Resets messages orphaned in `PROCESSING` (older than
+   * `crashRecoveryThresholdMs`) back to `PENDING` via the repository. Errors are
+   * logged, never thrown — crash recovery must not crash the processor.
+   */
+  async runCrashRecovery() {
+    const e = new Date(Date.now() - this.options.crashRecoveryThresholdMs), [t, s] = await d(() => 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`);
   }
   /**
    * Logs messages if logging is enabled
@@ -234,7 +384,7 @@ class m {
     };
   }
 }
-class f {
+class M {
   constructor(e) {
     this.eventBus = e;
   }
@@ -250,10 +400,10 @@ class f {
     await this.eventBus.publish(s);
   }
 }
-class M {
+class R {
   constructor(e, t = {}) {
-    this.logger = l.create("OutboxService"), this.repository = e, this.options = {
-      defaultPriority: t.defaultPriority ?? n.NORMAL,
+    this.logger = u.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 +414,7 @@ class M {
    * Saves a message to the outbox
    */
   async saveMessage(e, t, s) {
-    const r = g.createMessage(e, t, {
+    const r = h.createMessage(e, t, {
       priority: this.options.defaultPriority,
       metadata: { ...this.options.defaultMetadata, ...s?.metadata },
       ...s
@@ -276,10 +426,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: o }) => h.createMessage(r, a, {
         priority: this.options.defaultPriority,
-        metadata: { ...this.options.defaultMetadata, ...c?.metadata },
-        ...c
+        metadata: { ...this.options.defaultMetadata, ...o?.metadata },
+        ...o
       })
     ), s = await this.repository.saveBatch(t);
     return this.logger.debug(`Saved batch of ${e.length} messages`), s;
@@ -288,14 +438,14 @@ class M {
    * Schedules a message for delayed processing
    */
   async scheduleMessage(e, t, s, r) {
-    const a = g.createDelayedMessage(e, t, s, {
+    const a = h.createDelayedMessage(e, t, s, {
       priority: this.options.defaultPriority,
       metadata: { ...this.options.defaultMetadata, ...r?.metadata },
       ...r
-    }), c = await this.repository.scheduleMessage(a, a.processAfter);
+    }), o = 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 ${o} of type ${e} for processing in ${s}ms`
+    ), o;
   }
   /**
    * Saves a high priority message to the outbox
@@ -303,7 +453,7 @@ class M {
   async saveHighPriorityMessage(e, t, s) {
     return this.saveMessage(e, t, {
       ...s,
-      priority: n.HIGH
+      priority: g.HIGH
     });
   }
   /**
@@ -312,14 +462,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 = h.createFromIntegrationEvent(
       {
         eventName: e.eventName,
         payload: e,
@@ -353,13 +503,13 @@ class M {
    * Retries a failed message by resetting it to pending status
    */
   async retryMessage(e) {
-    await this.repository.updateStatus(e, o.PENDING), this.logger.info(`Reset message ${e} to pending for retry`);
+    await this.repository.updateStatus(e, n.PENDING), this.logger.info(`Reset message ${e} to pending for retry`);
   }
   /**
    * Retries multiple failed messages
    */
   async retryMessages(e) {
-    await this.repository.updateStatusBatch(e, o.PENDING), this.logger.info(`Reset ${e.length} messages to pending for retry`);
+    await this.repository.updateStatusBatch(e, n.PENDING), this.logger.info(`Reset ${e.length} messages to pending for retry`);
   }
   /**
    * Cleans up old processed messages
@@ -369,7 +519,7 @@ class M {
     s.setDate(s.getDate() - t);
     const r = await this.repository.deleteByStatusAndAge(
       s,
-      o.PROCESSED
+      n.PROCESSED
     );
     return this.logger.info(`Cleaned up ${r} processed messages older than ${t} days`), r;
   }
@@ -379,10 +529,10 @@ class M {
   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: 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,
@@ -401,11 +551,11 @@ class M {
   }
 }
 export {
-  f as EventBusOutboxHandler,
-  y as IOutboxRepository,
-  n as MessagePriority,
-  o as MessageStatus,
-  g as OutboxMessageFactory,
-  m as OutboxProcessor,
-  M as OutboxService
+  M as EventBusOutboxHandler,
+  m as IOutboxRepository,
+  g as MessagePriority,
+  n as MessageStatus,
+  h as OutboxMessageFactory,
+  v as OutboxProcessor,
+  R as OutboxService
 };

package/dist/outbox/index.d.ts

@@ -2,4 +2,5 @@ export * from './outbox-interfaces';
 export * from './outbox-repository.interface';
 export * from './outbox-message-factory';
 export * from './outbox-processor';
+export * from './outbox-hooks';
 export * from './outbox-service';

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

@@ -0,0 +1,24 @@
+import { IOutboxMessage } from './outbox-interfaces';
+/**
+ * Observability callbacks for {@link OutboxProcessor}. Use them to wire metrics
+ * (Prometheus counters, DataDog), alerting on permanent failures, or dead-letter
+ * routing — without coupling the processor to any specific telemetry stack.
+ *
+ * **Hooks must be synchronous and fast.** Each call is wrapped in a try/catch by
+ * the processor, so a throwing hook is logged and ignored (it never breaks the
+ * processing loop), but a slow hook still blocks the batch. Offload heavy work
+ * (network, disk) to a queue inside the hook.
+ */
+export interface OutboxProcessorHooks {
+    /** Fired once per processed batch with aggregate counts and wall-clock duration. */
+    onBatchComplete?(result: {
+        processed: number;
+        failed: number;
+        batchSize: number;
+        durationMs: number;
+    }): void;
+    /** Fired on every message failure, including ones that will be retried. */
+    onMessageFailed?(message: IOutboxMessage, error: Error, attempt: number): void;
+    /** Fired when a message is marked `FAILED` after exhausting `maxRetries`. */
+    onPermanentFailure?(message: IOutboxMessage, error: Error): void;
+}