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

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

@@ -1,4 +1,4 @@
-import { IEventBus } from '../../../contracts/src/index.ts';
+import { IEventBus } from '@vytches/ddd-contracts';
 import { IOutboxMessage, IOutboxMessageHandler, OutboxMiddleware, MessagePriority } from './outbox-interfaces';
 import { IOutboxRepository } from './outbox-repository.interface';
 import { OutboxProcessorHooks } from './outbox-hooks';
@@ -80,16 +80,42 @@ export interface OutboxProcessorOptions {
      * logged and never breaks the processing loop. Omit to disable.
      */
     hooks?: OutboxProcessorHooks;
+    /**
+     * Opt-in: when `true`, `processBatch` calls `IOutboxRepository.claimBatch()`
+     * instead of `getUnprocessedMessages()`, and `processMessage` skips its own
+     * (now redundant) `updateStatus(id, PROCESSING)` call for messages obtained
+     * this way — the repository's `claimBatch` is responsible for the
+     * PROCESSING mark.
+     *
+     * **Correctness depends on the repository.** `claimBatch` is an optional
+     * method on `IOutboxRepository` with a non-atomic default implementation
+     * (read then mark, two steps). Setting `useClaimBatch: true` against a
+     * repository that has NOT overridden `claimBatch` with a real atomic
+     * claim (e.g. `SELECT ... FOR UPDATE SKIP LOCKED`) provides **no**
+     * additional safety over the default `getUnprocessedMessages` path — it
+     * only prevents duplicate dispatch when the repository's `claimBatch` is
+     * genuinely atomic.
+     *
+     * If the repository does not implement `claimBatch` at all (the method is
+     * `undefined`, e.g. a hand-rolled repository predating this option), the
+     * processor logs a warning once and falls back to
+     * `getUnprocessedMessages` for that batch.
+     *
+     * Defaults to `false` — no behavior change for existing consumers (AC#5).
+     */
+    useClaimBatch?: boolean;
 }
 export declare class OutboxProcessor {
     private readonly repository;
     private readonly options;
     private readonly handlers;
+    private defaultHandler?;
     private readonly middlewares;
     private isRunning;
     private processingTimer?;
     private crashRecoveryTimer?;
-    private readonly logger;
+    /** Guards the one-time fallback warning when `useClaimBatch` is set but the repository has no `claimBatch`. */
+    private warnedMissingClaimBatch;
     constructor(repository: IOutboxRepository, options?: OutboxProcessorOptions);
     /**
      * Invokes an observability hook in isolation. A throwing hook is logged and
@@ -100,6 +126,22 @@ export declare class OutboxProcessor {
      * Registers a message handler for a specific message type
      */
     registerHandler(messageType: string, handler: IOutboxMessageHandler): void;
+    /**
+     * Registers a catch-all handler invoked when no type-specific handler matches.
+     *
+     * NOTE: Registering a default handler removes the implicit type allowlist —
+     * all future message types, including ones added by mistake or injected via
+     * compromised storage, will be dispatched to this handler. Validate
+     * `message.messageType` inside the handler against a known-types set if your
+     * domain requires an explicit allowlist.
+     *
+     * NOTE: When `messageTypes` filter option is set, the default handler handles
+     * only types that pass through that filter. To handle all types, leave
+     * `messageTypes` unset.
+     *
+     * Second/subsequent call emits a warning and replaces the previous handler.
+     */
+    registerDefaultHandler(handler: IOutboxMessageHandler): void;
     /**
      * Registers middleware for message processing pipeline
      */
@@ -147,6 +189,9 @@ export declare class OutboxProcessor {
     }>;
     /**
      * Processes a single message through the middleware pipeline.
+     * @param alreadyClaimed When `true`, the message was already marked
+     *   `PROCESSING` by `IOutboxRepository.claimBatch()` — the redundant
+     *   `updateStatus(id, PROCESSING)` call is skipped.
      * @returns `true` if the message was processed successfully, `false` if it failed.
      */
     private processMessage;
@@ -182,10 +227,6 @@ export declare class OutboxProcessor {
      * logged, never thrown — crash recovery must not crash the processor.
      */
     private runCrashRecovery;
-    /**
-     * Logs messages if logging is enabled
-     */
-    private log;
     /**
      * Gets processor statistics
      */
@@ -196,6 +237,7 @@ export declare class OutboxProcessor {
         processingInterval: number;
         registeredHandlers: string[];
         middlewareCount: number;
+        hasDefaultHandler: boolean;
     }>;
 }
 export declare class EventBusOutboxHandler implements IOutboxMessageHandler {

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

@@ -1,4 +1,4 @@
-import { IOutboxMessage, MessagePriority, MessageStatus } from './outbox-interfaces';
+import { MessageStatus, IOutboxMessage, MessagePriority } from './outbox-interfaces';
 export declare abstract class IOutboxRepository {
     /**
      * Saves a message to the outbox
@@ -13,16 +13,73 @@ export declare abstract class IOutboxRepository {
      */
     abstract saveBatch<T = unknown>(messages: IOutboxMessage<T>[]): Promise<string[]>;
     /**
-     * Gets unprocessed messages from the outbox
-     * @param limit Maximum number of messages to retrieve
-     * @param priorityOrder Order of priority for processing (default: [CRITICAL, HIGH, NORMAL, LOW])
-     * @param messageTypes Optional allow-list of message types to fetch. When
-     *   provided, only messages whose `messageType` is in this list are returned
-     *   (e.g. `WHERE message_type IN (...)`). Omitting it fetches all types —
-     *   this parameter is optional and backward-compatible.
-     * @returns Unprocessed messages
+     * Returns unprocessed messages up to the given limit.
+     *
+     * **Not a claim.** This is a pure read — it does not mark returned messages
+     * as `PROCESSING` or otherwise reserve them. `OutboxProcessor` calls
+     * `updateStatus(id, PROCESSING)` for each message *after* this read
+     * returns, which means there is a window between "read" and "claimed"
+     * during which two concurrent processors (or two calls racing on the same
+     * processor) can both read the same PENDING message and both dispatch it.
+     * Multi-worker deployments that need "exactly one processor claims each
+     * message" should implement {@link claimBatch} with an atomic
+     * read+mark (e.g. `SELECT ... FOR UPDATE SKIP LOCKED` or a single
+     * `UPDATE ... WHERE status='PENDING' RETURNING *` statement / compare-
+     * and-swap on `status`) rather than relying on this method plus a
+     * follow-up `updateStatus`.
+     *
+     * Regardless of claim strategy, handlers should be idempotent to side
+     * effects — transient failures or duplicate-claim races may cause a
+     * handler to run more than once.
+     *
+     * @param limit - Maximum number of messages to return.
+     * @param priorityOrder - Ordered array of MessagePriority values defining
+     *   processing order (first element = highest priority, processed first).
+     *   Implementations MUST sort results by the position of each message's
+     *   priority in this array — do NOT use ORDER BY priority directly on the
+     *   string column. Alphabetical sort inverts the intent: 'critical' sorts
+     *   after 'high' alphabetically, causing CRITICAL messages to be processed
+     *   last. Use comparePriority() or array index-based sorting instead.
+     * @param messageTypes - Optional allow-list of message types to return.
+     *   When provided, only messages whose messageType is in this array are
+     *   returned. When absent, all message types are returned.
      */
     abstract getUnprocessedMessages(limit?: number, priorityOrder?: MessagePriority[], messageTypes?: string[]): Promise<IOutboxMessage[]>;
+    /**
+     * Atomically claims a batch of unprocessed messages: reads PENDING
+     * messages *and* marks them `PROCESSING` in the same operation, so two
+     * concurrent callers (two processor instances, or two racing calls on one
+     * instance) never both receive the same message.
+     *
+     * **Optional, and non-atomic by default.** This method is declared with
+     * `?` — it is NOT part of the required abstract contract, so existing
+     * `IOutboxRepository` subclasses keep compiling unmodified (AC#5). The
+     * default implementation provided here is a convenience shim only: it
+     * calls {@link getUnprocessedMessages} and then `updateStatusBatch(...,
+     * PROCESSING)` as two separate steps. **That is NOT atomic** — it has the
+     * exact same read-then-mark race window as calling
+     * `getUnprocessedMessages` + `updateStatus` manually, and is safe only for
+     * a single-worker deployment. Override `claimBatch` in a concrete
+     * repository (e.g. backed by `SELECT ... FOR UPDATE SKIP LOCKED`, or a
+     * single atomic `UPDATE ... WHERE status='PENDING' LIMIT n RETURNING *`)
+     * to get real multi-worker/multi-processor safety.
+     *
+     * `OutboxProcessor` only calls this method when
+     * `OutboxProcessorOptions.useClaimBatch` is explicitly set to `true`
+     * (opt-in, default `false`) — see AC#1/AC#2. When enabled, the processor
+     * skips its own redundant `updateStatus(id, PROCESSING)` call for messages
+     * returned by `claimBatch`, since claiming already performed that mark.
+     *
+     * Handlers should be idempotent to side effects regardless — transient
+     * failures or duplicate-claim races (e.g. with the non-atomic default
+     * implementation) may still cause a handler to run more than once.
+     *
+     * @param limit - Maximum number of messages to claim.
+     * @param priorityOrder - See {@link getUnprocessedMessages}.
+     * @param messageTypes - See {@link getUnprocessedMessages}.
+     * @returns Messages that were claimed (already marked `PROCESSING`).
+     */
+    claimBatch?(limit?: number, priorityOrder?: MessagePriority[], messageTypes?: string[]): Promise<IOutboxMessage[]>;
     /**
      * Gets specific message by ID
      * @param id Message ID

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

@@ -1,4 +1,4 @@
-import { IDomainEvent } from '../../../contracts/src/index.ts';
+import { IDomainEvent } from '@vytches/ddd-contracts';
 import { IOutboxMessage, OutboxMessageOptions, MessagePriority } from './outbox-interfaces';
 import { IOutboxRepository } from './outbox-repository.interface';
 export interface OutboxServiceOptions {
@@ -16,7 +16,6 @@ export interface OutboxServiceOptions {
 export declare class OutboxService {
     private readonly repository;
     private readonly options;
-    private readonly logger;
     constructor(repository: IOutboxRepository, options?: OutboxServiceOptions);
     /**
      * Saves a message to the outbox
@@ -75,8 +74,4 @@ export declare class OutboxService {
         totalProcessed: number;
         totalFailed: number;
     }>;
-    /**
-     * Logs messages if logging is enabled
-     */
-    private log;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vytches/ddd-messaging",
-  "version": "0.29.3",
+  "version": "0.31.0-alpha.0",
   "description": "Outbox pattern and reliable message delivery",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,7 +17,8 @@
   "files": [
     "LLMGUIDE.md",
     "README.md",
-    "dist"
+    "dist",
+    "LICENSE"
   ],
   "keywords": [
     "ddd",
@@ -36,7 +37,7 @@
     "typescript": "^5.0.0",
     "vite": "^7.3.2",
     "vite-plugin-dts": "^4.0.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.0"
   },
   "nx": {
     "tags": [
@@ -50,7 +51,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@vytches/ddd-events": "0.29.3"
+    "@vytches/ddd-contracts": "0.31.0-alpha.0",
+    "@vytches/ddd-utils": "0.31.0-alpha.0",
+    "@vytches/ddd-events": "0.31.0-alpha.0"
   },
   "scripts": {
     "build": "vite build",