@vytches/ddd-messaging 0.26.0

package/dist/index.cjs

@@ -0,0 +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;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,411 @@
+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 {
+}
+class g {
+  /**
+   * Creates a new outbox message
+   * @param messageType Type of the message
+   * @param payload Message payload
+   * @param options Additional options
+   * @returns Outbox message
+   */
+  static createMessage(e, t, s) {
+    const r = {
+      id: h.getUUID(),
+      messageType: e,
+      payload: t,
+      metadata: s?.metadata || {},
+      status: o.PENDING,
+      attempts: 0,
+      createdAt: /* @__PURE__ */ new Date(),
+      priority: s?.priority || n.NORMAL
+    };
+    return s?.processAfter && (r.processAfter = s.processAfter), r;
+  }
+  /**
+   * Creates a delayed outbox message
+   * @param messageType Type of the message
+   * @param payload Message payload
+   * @param delayMs Delay in milliseconds
+   * @param options Additional options
+   * @returns Outbox message scheduled for later processing
+   */
+  static createDelayedMessage(e, t, s, r) {
+    const a = new Date(Date.now() + s);
+    return g.createMessage(e, t, {
+      ...r,
+      processAfter: a
+    });
+  }
+  /**
+   * Creates a high priority outbox message
+   * @param messageType Type of the message
+   * @param payload Message payload
+   * @param options Additional options
+   * @returns High priority outbox message
+   */
+  static createHighPriorityMessage(e, t, s) {
+    return g.createMessage(e, t, {
+      ...s,
+      priority: n.HIGH
+    });
+  }
+  /**
+   * Creates an outbox message from an integration event
+   * @param event Integration event
+   * @param options Additional options
+   * @returns Outbox message containing the integration event
+   */
+  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 = /* @__PURE__ */ new Map(), this.middlewares = [], this.isRunning = !1, this.logger = l.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
+    };
+  }
+  /**
+   * Registers a message handler for a specific message type
+   */
+  registerHandler(e, t) {
+    this.handlers.set(e, t), this.logger.debug(`Registered handler for message type: ${e}`);
+  }
+  /**
+   * Registers middleware for message processing pipeline
+   */
+  use(e) {
+    this.middlewares.push(e), this.logger.debug("Registered middleware");
+  }
+  /**
+   * Starts the processor with automatic interval processing
+   */
+  start() {
+    if (this.isRunning) {
+      this.logger.warn("Processor is already running");
+      return;
+    }
+    this.isRunning = !0, this.logger.info("Starting outbox processor"), this.scheduleProcessing();
+  }
+  /**
+   * Stops the processor
+   */
+  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");
+  }
+  /**
+   * Processes a single batch of pending messages.
+   *
+   * **Dispatch model:** messages within a batch are dispatched **in parallel**
+   * via `Promise.allSettled`. A failure in message N does **not** block
+   * messages N+1..N+M. Each failure is isolated, retry-counted via
+   * `incrementAttempt`, and reset to `PENDING` (or marked `FAILED` after
+   * `maxRetries` attempts) — independently of sibling messages.
+   *
+   * **Ordering:** parallel dispatch means message processing order is
+   * **not guaranteed** within a batch, even if `priorityOrder` was used to
+   * select which messages to fetch. If you need strict ordering, set
+   * `batchSize: 1` (one message per batch = sequential by definition).
+   *
+   * **Throughput:** for N messages and dispatch latency L, total batch time
+   * is approximately L (parallel) rather than N*L (sequential). For 200
+   * messages at 10ms dispatch each: ~10ms parallel vs ~2s sequential.
+   *
+   * **Quiescence:** if there are no pending messages, returns immediately
+   * without invoking handlers.
+   *
+   * @public
+   * @stable
+   * @since 0.1.0
+   */
+  async processBatch() {
+    if (!this.isRunning)
+      return;
+    const [e, t] = await d(
+      () => 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`);
+  }
+  /**
+   * Processes a single message through the middleware pipeline
+   */
+  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}`);
+    });
+    t && await this.handleMessageError(e, t);
+  }
+  /**
+   * Builds the middleware pipeline for message processing
+   */
+  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);
+  }
+  /**
+   * Handles errors during message processing
+   */
+  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}`);
+    }
+  }
+  /**
+   * Schedules the next processing cycle
+   */
+  scheduleProcessing() {
+    this.isRunning && (this.processingTimer = setTimeout(async () => {
+      await this.processBatch(), this.scheduleProcessing();
+    }, this.options.processingInterval));
+  }
+  /**
+   * Logs messages if logging is enabled
+   */
+  log(e) {
+    this.options.enableLogging && this.logger.info(e);
+  }
+  /**
+   * Gets processor statistics
+   */
+  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 = l.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
+    };
+  }
+  /**
+   * Saves a message to the outbox
+   */
+  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;
+  }
+  /**
+   * Saves multiple messages to the outbox in a batch
+   */
+  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;
+  }
+  /**
+   * Schedules a message for delayed processing
+   */
+  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;
+  }
+  /**
+   * Saves a high priority message to the outbox
+   */
+  async saveHighPriorityMessage(e, t, s) {
+    return this.saveMessage(e, t, {
+      ...s,
+      priority: n.HIGH
+    });
+  }
+  /**
+   * Saves a critical priority message to the outbox
+   */
+  async saveCriticalMessage(e, t, s) {
+    return this.saveMessage(e, t, {
+      ...s,
+      priority: n.CRITICAL
+    });
+  }
+  /**
+   * Converts a domain event to an outbox message and saves it
+   */
+  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;
+  }
+  /**
+   * Gets a message by ID
+   */
+  async getMessage(e) {
+    return this.repository.getById(e);
+  }
+  /**
+   * Gets pending messages (for monitoring purposes)
+   */
+  async getPendingMessages(e = 100) {
+    return this.repository.getUnprocessedMessages(e);
+  }
+  /**
+   * 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`);
+  }
+  /**
+   * 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`);
+  }
+  /**
+   * Cleans up old processed messages
+   */
+  async cleanup(e) {
+    const t = e ?? this.options.cleanupAfterDays, s = /* @__PURE__ */ 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;
+  }
+  /**
+   * Gets outbox statistics
+   */
+  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,
+      // Would need separate query
+      totalProcessed: 0,
+      // Would need separate query
+      totalFailed: 0
+      // Would need separate query
+    };
+  }
+  /**
+   * Logs messages if logging is enabled
+   */
+  log(e) {
+    this.options.enableLogging && this.logger.info(e);
+  }
+}
+export {
+  f as EventBusOutboxHandler,
+  y as IOutboxRepository,
+  n as MessagePriority,
+  o as MessageStatus,
+  g as OutboxMessageFactory,
+  m as OutboxProcessor,
+  M as OutboxService
+};

package/dist/outbox/index.d.ts

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

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

@@ -0,0 +1,50 @@
+export declare enum MessageStatus {
+    PENDING = "PENDING",
+    PROCESSING = "PROCESSING",
+    PROCESSED = "PROCESSED",
+    FAILED = "FAILED"
+}
+export declare enum MessagePriority {
+    LOW = "low",
+    NORMAL = "normal",
+    HIGH = "high",
+    CRITICAL = "critical"
+}
+export interface IOutboxMessage<T = unknown> {
+    /** Unique identifier for the message */
+    id: string;
+    /** Type of message */
+    messageType: string;
+    /** Message payload */
+    payload: T;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+    /** Processing status */
+    status: MessageStatus;
+    /** Processing attempts count */
+    attempts: number;
+    /** When the message was created */
+    createdAt: Date;
+    /** When to process the message (for delayed processing) */
+    processAfter?: Date;
+    /** Priority level */
+    priority?: MessagePriority;
+    /** Last error message (if any) */
+    lastError?: string;
+}
+export interface OutboxMessageOptions {
+    /** When to process the message (for delayed processing) */
+    processAfter?: Date;
+    /** Priority level */
+    priority?: MessagePriority;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+export interface IOutboxMessageHandler<T = unknown> {
+    /**
+     * Handles a message from the outbox
+     * @param message Message to handle
+     */
+    handle(message: IOutboxMessage<T>): Promise<void>;
+}
+export type OutboxMiddleware = (next: (message: IOutboxMessage) => Promise<void>) => (message: IOutboxMessage) => Promise<void>;

package/dist/outbox/outbox-message-factory.d.ts

@@ -0,0 +1,39 @@
+import { IOutboxMessage, OutboxMessageOptions } from './outbox-interfaces';
+export declare class OutboxMessageFactory {
+    /**
+     * Creates a new outbox message
+     * @param messageType Type of the message
+     * @param payload Message payload
+     * @param options Additional options
+     * @returns Outbox message
+     */
+    static createMessage<T = unknown>(messageType: string, payload: T, options?: OutboxMessageOptions): IOutboxMessage<T>;
+    /**
+     * Creates a delayed outbox message
+     * @param messageType Type of the message
+     * @param payload Message payload
+     * @param delayMs Delay in milliseconds
+     * @param options Additional options
+     * @returns Outbox message scheduled for later processing
+     */
+    static createDelayedMessage<T = unknown>(messageType: string, payload: T, delayMs: number, options?: OutboxMessageOptions): IOutboxMessage<T>;
+    /**
+     * Creates a high priority outbox message
+     * @param messageType Type of the message
+     * @param payload Message payload
+     * @param options Additional options
+     * @returns High priority outbox message
+     */
+    static createHighPriorityMessage<T = unknown>(messageType: string, payload: T, options?: OutboxMessageOptions): IOutboxMessage<T>;
+    /**
+     * Creates an outbox message from an integration event
+     * @param event Integration event
+     * @param options Additional options
+     * @returns Outbox message containing the integration event
+     */
+    static createFromIntegrationEvent<T = unknown>(event: {
+        eventName: string;
+        payload?: T;
+        metadata?: Record<string, unknown>;
+    }, options?: OutboxMessageOptions): IOutboxMessage<T>;
+}

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

@@ -0,0 +1,105 @@
+import { IEventBus } from '../../../contracts/src/index.ts';
+import { IOutboxMessage, IOutboxMessageHandler, OutboxMiddleware, MessagePriority } from './outbox-interfaces';
+import { IOutboxRepository } from './outbox-repository.interface';
+export interface OutboxProcessorOptions {
+    /** Maximum number of messages to process in one batch */
+    batchSize?: number;
+    /** Maximum retry attempts for failed messages */
+    maxRetries?: number;
+    /** Processing interval in milliseconds */
+    processingInterval?: number;
+    /** Priority order for message processing */
+    priorityOrder?: MessagePriority[];
+    /** Timeout for processing a single message */
+    messageTimeout?: number;
+    /** Enable logging */
+    enableLogging?: boolean;
+}
+export declare class OutboxProcessor {
+    private readonly repository;
+    private readonly options;
+    private readonly handlers;
+    private readonly middlewares;
+    private isRunning;
+    private processingTimer?;
+    private readonly logger;
+    constructor(repository: IOutboxRepository, options?: OutboxProcessorOptions);
+    /**
+     * Registers a message handler for a specific message type
+     */
+    registerHandler(messageType: string, handler: IOutboxMessageHandler): void;
+    /**
+     * Registers middleware for message processing pipeline
+     */
+    use(middleware: OutboxMiddleware): void;
+    /**
+     * Starts the processor with automatic interval processing
+     */
+    start(): void;
+    /**
+     * Stops the processor
+     */
+    stop(): void;
+    /**
+     * Processes a single batch of pending messages.
+     *
+     * **Dispatch model:** messages within a batch are dispatched **in parallel**
+     * via `Promise.allSettled`. A failure in message N does **not** block
+     * messages N+1..N+M. Each failure is isolated, retry-counted via
+     * `incrementAttempt`, and reset to `PENDING` (or marked `FAILED` after
+     * `maxRetries` attempts) — independently of sibling messages.
+     *
+     * **Ordering:** parallel dispatch means message processing order is
+     * **not guaranteed** within a batch, even if `priorityOrder` was used to
+     * select which messages to fetch. If you need strict ordering, set
+     * `batchSize: 1` (one message per batch = sequential by definition).
+     *
+     * **Throughput:** for N messages and dispatch latency L, total batch time
+     * is approximately L (parallel) rather than N*L (sequential). For 200
+     * messages at 10ms dispatch each: ~10ms parallel vs ~2s sequential.
+     *
+     * **Quiescence:** if there are no pending messages, returns immediately
+     * without invoking handlers.
+     *
+     * @public
+     * @stable
+     * @since 0.1.0
+     */
+    processBatch(): Promise<void>;
+    /**
+     * Processes a single message through the middleware pipeline
+     */
+    private processMessage;
+    /**
+     * Builds the middleware pipeline for message processing
+     */
+    private buildPipeline;
+    /**
+     * Handles errors during message processing
+     */
+    private handleMessageError;
+    /**
+     * Schedules the next processing cycle
+     */
+    private scheduleProcessing;
+    /**
+     * Logs messages if logging is enabled
+     */
+    private log;
+    /**
+     * Gets processor statistics
+     */
+    getStats(): Promise<{
+        isRunning: boolean;
+        batchSize: number;
+        maxRetries: number;
+        processingInterval: number;
+        registeredHandlers: string[];
+        middlewareCount: number;
+    }>;
+}
+export declare class EventBusOutboxHandler implements IOutboxMessageHandler {
+    private readonly eventBus;
+    constructor(eventBus: IEventBus);
+    handle(message: IOutboxMessage): Promise<void>;
+}