@miiajs/messaging 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruslan Matiushev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @miiajs/messaging
+
+Decorator-driven message bus for MiiaJS - retry with auto-DLQ, idempotency, named buses, W3C tracing.
+
+## Installation
+
+```bash
+npm install @miiajs/messaging
+```
+
+## Documentation
+
+**[miiajs.com/docs/packages/messaging](https://miiajs.com/docs/packages/messaging)**
+
+## License
+
+MIT

package/dist/decorators.d.ts

@@ -0,0 +1,149 @@
+import { type DiscoverableMethodMeta } from '@miiajs/core';
+import type { DispatchMode, MessageMeta } from './types.js';
+export declare const ON: unique symbol;
+export declare const IDEMPOTENT: unique symbol;
+export interface OnMeta extends DiscoverableMethodMeta {
+    topic: string;
+    /**
+     * Explicit broker consumer group (competing-consumers worker pool). When
+     * omitted, the bus auto-derives a per-handler group `<topic>__<Class>_<method>`
+     * (optionally `<appName>:` prefixed). Setting this option puts multiple
+     * handlers (across classes or replicas) into the same broker group so the
+     * broker round-robins each message to one of them. Requires
+     * `transport.supportsCompetingConsumers === true`.
+     */
+    group?: string;
+    concurrency?: number;
+    /**
+     * Target bus name when multiple `MessagingModule.configure(opts, name)` are
+     * registered. Omit (or `undefined`) to target the default bus. Throws at
+     * startup if the referenced bus name has no matching `MessagingModule`.
+     */
+    bus?: string;
+    /**
+     * Per-handler override of the bus / transport dispatch mode. Resolution
+     * order: this field > `MessagingModule.configure({ dispatch: { mode } })` >
+     * `transport.defaultMode`. Validated against `transport.supportedModes` at
+     * `MessageBus.onReady()`.
+     */
+    mode?: DispatchMode;
+    /**
+     * Cluster-wide fan-out for this handler. When `true`, the auto-derived group
+     * is suffixed with `__<hostname>_<pid>` so every replica gets a unique broker
+     * group and the broker delivers a copy of each message to every replica.
+     * Mutually exclusive with `group` - explicit `group` is for shared work
+     * across handlers/replicas, broadcast replicates work to every replica.
+     *
+     * Use for in-process state that every replica must update on its own
+     * (cache invalidation, websocket broadcast).
+     */
+    broadcast?: boolean;
+}
+export interface IdempotentMeta {
+    /** Claim lifetime in milliseconds. */
+    ttl: number;
+    key?: (payload: unknown, meta: MessageMeta) => string;
+}
+/**
+ * Marks a method as a message handler for `topic`. At app startup, MessageBus
+ * discovers all `@On` methods via DiscoveryService (during `onReady`) and
+ * subscribes each one to the configured transport.
+ *
+ * @param topic   Free-form string. Transports do not interpret dots/slashes.
+ * @param options.group        Explicit broker consumer group (competing-consumers
+ *                             worker pool). Without it, an auto-derived
+ *                             per-handler group is used.
+ * @param options.concurrency  Per-handler subscription concurrency. In sliding
+ *                             mode = number of lanes.
+ * @param options.mode         Per-handler dispatch mode. Resolution: this
+ *                             field > bus default > `transport.defaultMode`.
+ * @param options.bus          Target bus for multi-bus setups.
+ * @param options.broadcast    Cluster-wide fan-out (every replica gets a copy).
+ *                             Mutually exclusive with `group`.
+ *
+ * **Subscription model.** Each `@On` becomes its own broker subscription with
+ * an auto-derived consumer group `<topic>__<ClassName>_<methodName>` (or
+ * `<appName>:<topic>__<ClassName>_<methodName>` if `MessagingModule.configure`
+ * provides `appName`). Within one process every handler runs independently:
+ * retry, ack/nack, mode/concurrency are isolated per handler.
+ *
+ * For replicas of the same handler running in N processes, broker round-robins
+ * each message to exactly one of the N consumers (load balance scaling).
+ *
+ * For cluster-wide fan-out (each replica processes its own copy), set
+ * `broadcast: true`. For competing-consumers worker pool across multiple
+ * handler classes, pass explicit `group: 'pool-name'` (requires
+ * `transport.supportsCompetingConsumers === true`).
+ *
+ * **Multi-topic handlers.** Decorating one method with multiple `@On` works
+ * naturally - each decoration creates its own subscription with its own
+ * auto-derived group. Useful when a single handler responds to several
+ * topics:
+ * ```ts
+ * @On('user.created')
+ * @On('user.updated')
+ * async syncToCRM(user: User) { ... }
+ * // → 2 subscriptions: user.created__SyncService_syncToCRM, user.updated__...
+ * ```
+ *
+ * @example
+ * ```ts
+ * @On('user.created')                              // 1 worker, fan-out across handlers
+ * @On('cache.invalidate', { broadcast: true })     // copy to every replica
+ * @On('jobs', { group: 'workers' })                // explicit competing-consumers pool
+ * ```
+ */
+export declare const On: (topic: string, options?: {
+    group?: string;
+    concurrency?: number;
+    bus?: string;
+    mode?: DispatchMode;
+    broadcast?: boolean;
+} | undefined) => (target: Function, context: ClassMethodDecoratorContext) => void;
+/**
+ * Skip the handler when the same logical message has already been processed.
+ *
+ * When applied to an `@On` handler, MessageBus claims an idempotency key in the
+ * configured `IdempotencyStore` before invoking the handler. If the claim
+ * already exists (duplicate delivery from XAUTOCLAIM, network blip, etc.),
+ * the handler is silently skipped and the message is acked.
+ *
+ * Default key is `${envelope.id}:${ClassName}.${methodName}` - per-handler
+ * scope, so two `@Idempotent` handlers on the same topic do NOT conflict
+ * by default. Pass an explicit `key` to override (for example, dedupe on a
+ * business identifier from payload, or share a single key across handlers).
+ *
+ * **NOT exactly-once.** If the consumer crashes after `claim()` but before
+ * the message is acked back to the broker, the claim stays in the store
+ * while the broker still considers the message un-acked. After redelivery
+ * the next consumer sees a stale claim and skips the handler, effectively
+ * losing the message. For business-critical workflows pair `@Idempotent`
+ * with a transactional outbox or use idempotent-by-design handlers
+ * (`UPDATE WHERE id=?`) instead.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class PaymentService {
+ *   @On('order.placed')
+ *   @Idempotent({ ttl: 24 * 60 * 60 * 1000 }) // dedupe within 24h
+ *   async chargeCard(order: Order) {
+ *     await this.payments.charge(order.cardId, order.total)
+ *   }
+ *
+ *   // Custom key when the upstream may republish the same business event
+ *   // with different envelope.id values:
+ *   @On('payment.received')
+ *   @Idempotent({ ttl: 24 * 60 * 60 * 1000, key: (p: Payment) => `payment:${p.transactionId}` })
+ *   async onPayment(payment: Payment) { ... }
+ * }
+ * ```
+ *
+ * @throws at app startup if any `@Idempotent` handler exists but no
+ *   `IdempotencyStore` was passed to `MessagingModule.configure()`.
+ */
+export declare const Idempotent: (options: {
+    ttl: number;
+    key?: (payload: unknown, meta: MessageMeta) => string;
+}) => (target: Function, context: ClassMethodDecoratorContext) => void;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiD,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAA;AACzG,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D,eAAO,MAAM,EAAE,eAA8B,CAAA;AAE7C,eAAO,MAAM,UAAU,eAAsC,CAAA;AAE7D,MAAM,WAAW,MAAO,SAAQ,sBAAsB;IACpD,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,KAAK,MAAM,CAAA;CACtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,EAAE;YAGS,MAAM;kBAAgB,MAAM;UAAQ,MAAM;WAAS,YAAY;gBAAc,OAAO;kFAY1G,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,UAAU;SACJ,MAAM;UAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,KAAK,MAAM;sEAM9E,CAAA"}

package/dist/decorators.js

@@ -0,0 +1,112 @@
+import { createMethodDecorator, pushMeta, setInMapMeta } from '@miiajs/core';
+export const ON = Symbol('miia:messaging:on');
+export const IDEMPOTENT = Symbol('miia:messaging:idempotent');
+/**
+ * Marks a method as a message handler for `topic`. At app startup, MessageBus
+ * discovers all `@On` methods via DiscoveryService (during `onReady`) and
+ * subscribes each one to the configured transport.
+ *
+ * @param topic   Free-form string. Transports do not interpret dots/slashes.
+ * @param options.group        Explicit broker consumer group (competing-consumers
+ *                             worker pool). Without it, an auto-derived
+ *                             per-handler group is used.
+ * @param options.concurrency  Per-handler subscription concurrency. In sliding
+ *                             mode = number of lanes.
+ * @param options.mode         Per-handler dispatch mode. Resolution: this
+ *                             field > bus default > `transport.defaultMode`.
+ * @param options.bus          Target bus for multi-bus setups.
+ * @param options.broadcast    Cluster-wide fan-out (every replica gets a copy).
+ *                             Mutually exclusive with `group`.
+ *
+ * **Subscription model.** Each `@On` becomes its own broker subscription with
+ * an auto-derived consumer group `<topic>__<ClassName>_<methodName>` (or
+ * `<appName>:<topic>__<ClassName>_<methodName>` if `MessagingModule.configure`
+ * provides `appName`). Within one process every handler runs independently:
+ * retry, ack/nack, mode/concurrency are isolated per handler.
+ *
+ * For replicas of the same handler running in N processes, broker round-robins
+ * each message to exactly one of the N consumers (load balance scaling).
+ *
+ * For cluster-wide fan-out (each replica processes its own copy), set
+ * `broadcast: true`. For competing-consumers worker pool across multiple
+ * handler classes, pass explicit `group: 'pool-name'` (requires
+ * `transport.supportsCompetingConsumers === true`).
+ *
+ * **Multi-topic handlers.** Decorating one method with multiple `@On` works
+ * naturally - each decoration creates its own subscription with its own
+ * auto-derived group. Useful when a single handler responds to several
+ * topics:
+ * ```ts
+ * @On('user.created')
+ * @On('user.updated')
+ * async syncToCRM(user: User) { ... }
+ * // → 2 subscriptions: user.created__SyncService_syncToCRM, user.updated__...
+ * ```
+ *
+ * @example
+ * ```ts
+ * @On('user.created')                              // 1 worker, fan-out across handlers
+ * @On('cache.invalidate', { broadcast: true })     // copy to every replica
+ * @On('jobs', { group: 'workers' })                // explicit competing-consumers pool
+ * ```
+ */
+export const On = createMethodDecorator((_target, ctx, topic, options) => {
+    pushMeta(ctx.metadata, ON, {
+        handlerName: ctx.name,
+        topic,
+        group: options?.group,
+        concurrency: options?.concurrency,
+        bus: options?.bus,
+        mode: options?.mode,
+        broadcast: options?.broadcast,
+    });
+});
+/**
+ * Skip the handler when the same logical message has already been processed.
+ *
+ * When applied to an `@On` handler, MessageBus claims an idempotency key in the
+ * configured `IdempotencyStore` before invoking the handler. If the claim
+ * already exists (duplicate delivery from XAUTOCLAIM, network blip, etc.),
+ * the handler is silently skipped and the message is acked.
+ *
+ * Default key is `${envelope.id}:${ClassName}.${methodName}` - per-handler
+ * scope, so two `@Idempotent` handlers on the same topic do NOT conflict
+ * by default. Pass an explicit `key` to override (for example, dedupe on a
+ * business identifier from payload, or share a single key across handlers).
+ *
+ * **NOT exactly-once.** If the consumer crashes after `claim()` but before
+ * the message is acked back to the broker, the claim stays in the store
+ * while the broker still considers the message un-acked. After redelivery
+ * the next consumer sees a stale claim and skips the handler, effectively
+ * losing the message. For business-critical workflows pair `@Idempotent`
+ * with a transactional outbox or use idempotent-by-design handlers
+ * (`UPDATE WHERE id=?`) instead.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class PaymentService {
+ *   @On('order.placed')
+ *   @Idempotent({ ttl: 24 * 60 * 60 * 1000 }) // dedupe within 24h
+ *   async chargeCard(order: Order) {
+ *     await this.payments.charge(order.cardId, order.total)
+ *   }
+ *
+ *   // Custom key when the upstream may republish the same business event
+ *   // with different envelope.id values:
+ *   @On('payment.received')
+ *   @Idempotent({ ttl: 24 * 60 * 60 * 1000, key: (p: Payment) => `payment:${p.transactionId}` })
+ *   async onPayment(payment: Payment) { ... }
+ * }
+ * ```
+ *
+ * @throws at app startup if any `@Idempotent` handler exists but no
+ *   `IdempotencyStore` was passed to `MessagingModule.configure()`.
+ */
+export const Idempotent = createMethodDecorator((_target, ctx, options) => {
+    setInMapMeta(ctx.metadata, IDEMPOTENT, String(ctx.name), {
+        ttl: options.ttl,
+        key: options.key,
+    });
+});
+//# sourceMappingURL=decorators.js.map

package/dist/decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,QAAQ,EAAE,YAAY,EAA+B,MAAM,cAAc,CAAA;AAGzG,MAAM,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAA;AAE7C,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,2BAA2B,CAAC,CAAA;AA8C7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,qBAAqB,CAKrC,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;IACjC,QAAQ,CAAC,GAAG,CAAC,QAAS,EAAE,EAAE,EAAE;QAC1B,WAAW,EAAE,GAAG,CAAC,IAAc;QAC/B,KAAK;QACL,KAAK,EAAE,OAAO,EAAE,KAAK;QACrB,WAAW,EAAE,OAAO,EAAE,WAAW;QACjC,GAAG,EAAE,OAAO,EAAE,GAAG;QACjB,IAAI,EAAE,OAAO,EAAE,IAAI;QACnB,SAAS,EAAE,OAAO,EAAE,SAAS;KACb,CAAC,CAAA;AACrB,CAAC,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAE7C,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;IAC1B,YAAY,CAAC,GAAG,CAAC,QAAS,EAAE,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QACxD,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,EAAE,OAAO,CAAC,GAAG;KACQ,CAAC,CAAA;AAC7B,CAAC,CAAC,CAAA"}

package/dist/group-name.d.ts

@@ -0,0 +1,33 @@
+export interface DeriveGroupNameInput {
+    topic: string;
+    ctorName: string;
+    methodName: string;
+    appName: string | null;
+    /**
+     * Explicit user-provided group from `@On({ group: '...' })`. When set,
+     * returned as-is - explicit groups are full-qualified by the user and do
+     * NOT receive `appName` prefix.
+     */
+    explicitGroup?: string;
+    /**
+     * Cluster-wide fan-out opt-in. When `true`, the group is suffixed with
+     * `__<hostname>_<pid>` so every replica gets a unique broker group and
+     * the broker delivers a copy of each message to every replica. Mutually
+     * exclusive with `explicitGroup`.
+     */
+    broadcast?: boolean;
+}
+/**
+ * Build the broker consumer group name for an `@On` handler.
+ *
+ * Resolution order:
+ * - `explicitGroup` provided → returned as-is (no `appName` prefix, no broadcast suffix)
+ * - `broadcast: true` → `${appName ? appName + ':' : ''}${topic}__${ctor}_${method}__${hostname}_${pid}`
+ * - default → `${appName ? appName + ':' : ''}${topic}__${ctor}_${method}`
+ *
+ * The broadcast suffix uses only `hostname` + `pid` (no random component) so that
+ * orphan-cleanup logic in transports can reliably match previous-incarnation
+ * groups by stable host pattern when the process restarts.
+ */
+export declare function deriveGroupName(input: DeriveGroupNameInput): string;
+//# sourceMappingURL=group-name.d.ts.map

package/dist/group-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-name.d.ts","sourceRoot":"","sources":["../src/group-name.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAWnE"}

package/dist/group-name.js

@@ -0,0 +1,25 @@
+import { hostname } from 'node:os';
+/**
+ * Build the broker consumer group name for an `@On` handler.
+ *
+ * Resolution order:
+ * - `explicitGroup` provided → returned as-is (no `appName` prefix, no broadcast suffix)
+ * - `broadcast: true` → `${appName ? appName + ':' : ''}${topic}__${ctor}_${method}__${hostname}_${pid}`
+ * - default → `${appName ? appName + ':' : ''}${topic}__${ctor}_${method}`
+ *
+ * The broadcast suffix uses only `hostname` + `pid` (no random component) so that
+ * orphan-cleanup logic in transports can reliably match previous-incarnation
+ * groups by stable host pattern when the process restarts.
+ */
+export function deriveGroupName(input) {
+    if (input.explicitGroup)
+        return input.explicitGroup;
+    const base = input.appName
+        ? `${input.appName}:${input.topic}__${input.ctorName}_${input.methodName}`
+        : `${input.topic}__${input.ctorName}_${input.methodName}`;
+    if (input.broadcast) {
+        return `${base}__${hostname()}_${process.pid}`;
+    }
+    return base;
+}
+//# sourceMappingURL=group-name.js.map

package/dist/group-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-name.js","sourceRoot":"","sources":["../src/group-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAsBlC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,IAAI,KAAK,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC,aAAa,CAAA;IAEnD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO;QACxB,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,UAAU,EAAE;QAC1E,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,UAAU,EAAE,CAAA;IAE3D,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACpB,OAAO,GAAG,IAAI,KAAK,QAAQ,EAAE,IAAI,OAAO,CAAC,GAAG,EAAE,CAAA;IAChD,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/idempotency.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pluggable idempotency primitive used by `@Idempotent` handlers in MessageBus.
+ *
+ * `claim(id, ttl)` is the atomic "first time?" check; `release(id)` lets the
+ * next retry attempt re-claim after a handler error. The store is transport-
+ * agnostic - a Redis Streams transport may pair with a Postgres-backed store,
+ * a NATS transport may use the broker's native dedup window plus a memory
+ * store for cross-restart safety.
+ *
+ * Implementations shipped:
+ * - `memoryIdempotencyStore()` - in-process Map with LRU eviction; default
+ *   for dev/tests; not safe across processes.
+ * - `redisIdempotencyStore()` from `@miiajs/messaging-redis` - production-ready,
+ *   atomic via SET NX EX.
+ *
+ * Custom backends (Postgres `INSERT ON CONFLICT`, DynamoDB conditional put)
+ * implement this interface directly.
+ */
+export interface IdempotencyStore {
+    /**
+     * Try to claim an ID for the given TTL (in milliseconds).
+     *
+     * - returns `true` → first claim, the framework proceeds with the handler
+     * - returns `false` → already claimed, the handler is silently skipped
+     *   (treated as "already processed")
+     *
+     * Must be atomic: concurrent calls with the same id must produce exactly
+     * one `true` and the rest `false`.
+     */
+    claim(id: string, ttlMs: number): Promise<boolean>;
+    /**
+     * Release a previously-claimed id so a future delivery can re-claim.
+     * Called by MessageBus when the handler errors. Idempotent (no-op if id
+     * is not present).
+     */
+    release(id: string): Promise<void>;
+    onDestroy?(): Promise<void>;
+}
+/**
+ * DI token for the optional idempotency store.
+ *
+ * Always registered by `MessagingModule.configure()` (value is `null` when
+ * the user did not configure one). MessageBus reads it via `injectOptional`
+ * and only uses the store when a handler has `@Idempotent`.
+ */
+export declare const IDEMPOTENCY_STORE = "miia:messaging:idempotency-store";
+export interface MemoryIdempotencyStoreOptions {
+    /**
+     * Max entries kept before LRU eviction. Default 10000.
+     *
+     * If an entry is evicted before its TTL, a duplicate may be re-processed.
+     * Acceptable trade-off for in-process stores; production deployments
+     * should use a Redis-backed store with bounded memory pressure.
+     */
+    maxSize?: number;
+}
+export declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private entries;
+    private maxSize;
+    constructor(options?: MemoryIdempotencyStoreOptions);
+    claim(id: string, ttlMs: number): Promise<boolean>;
+    release(id: string): Promise<void>;
+    onDestroy(): Promise<void>;
+}
+export declare function memoryIdempotencyStore(options?: MemoryIdempotencyStoreOptions): IdempotencyStore;
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAElD;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAElC,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,qCAAqC,CAAA;AAInE,MAAM,WAAW,6BAA6B;IAC5C;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAAQ;gBAEX,OAAO,GAAE,6BAAkC;IAIjD,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBlD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAGjC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,6BAA6B,GAAG,gBAAgB,CAEhG"}

package/dist/idempotency.js

@@ -0,0 +1,42 @@
+/**
+ * DI token for the optional idempotency store.
+ *
+ * Always registered by `MessagingModule.configure()` (value is `null` when
+ * the user did not configure one). MessageBus reads it via `injectOptional`
+ * and only uses the store when a handler has `@Idempotent`.
+ */
+export const IDEMPOTENCY_STORE = 'miia:messaging:idempotency-store';
+const DEFAULT_MAX_SIZE = 10_000;
+export class MemoryIdempotencyStore {
+    entries = new Map(); // id → expiresAtMs
+    maxSize;
+    constructor(options = {}) {
+        this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
+    }
+    async claim(id, ttlMs) {
+        const now = Date.now();
+        const existing = this.entries.get(id);
+        if (existing !== undefined && existing > now)
+            return false;
+        // Stale entry treated as absent. Delete-then-set keeps Map insertion
+        // order accurate for LRU eviction below.
+        this.entries.delete(id);
+        this.entries.set(id, now + ttlMs);
+        if (this.entries.size > this.maxSize) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+        return true;
+    }
+    async release(id) {
+        this.entries.delete(id);
+    }
+    async onDestroy() {
+        this.entries.clear();
+    }
+}
+export function memoryIdempotencyStore(options) {
+    return new MemoryIdempotencyStore(options);
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAyCA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,kCAAkC,CAAA;AAenE,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAE/B,MAAM,OAAO,sBAAsB;IACzB,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAA,CAAC,mBAAmB;IACvD,OAAO,CAAQ;IAEvB,YAAY,UAAyC,EAAE;QACrD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAA;IACpD,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,EAAU,EAAE,KAAa;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACrC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,GAAG,GAAG;YAAE,OAAO,KAAK,CAAA;QAE1D,qEAAqE;QACrE,yCAAyC;QACzC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACvB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,GAAG,KAAK,CAAC,CAAA;QAEjC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAA;YAC/C,IAAI,MAAM,KAAK,SAAS;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACvD,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU;QACtB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACzB,CAAC;IAED,KAAK,CAAC,SAAS;QACb,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IACtB,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAuC;IAC5E,OAAO,IAAI,sBAAsB,CAAC,OAAO,CAAC,CAAA;AAC5C,CAAC"}

package/dist/in-memory-transport.d.ts

@@ -0,0 +1,60 @@
+import { type DispatchMode, type MessageEnvelope, type MessageTransport, type HandlerResult, type RetryConfig, type SubscribeOptions, type Subscription } from './types.js';
+export interface InMemoryTransportOptions {
+    retry?: Partial<RetryConfig>;
+    /**
+     * When true, payload is `structuredClone`d before each handler sees it.
+     * Prevents cross-handler mutation at the cost of one clone per delivery.
+     * Default false (same object identity across handlers - consistent with
+     * Node EventEmitter semantics).
+     */
+    cloneOnPublish?: boolean;
+    /**
+     * Max time `onDestroy()` waits for in-flight handlers to settle before
+     * forcing cleanup. Default 5000ms. Set 0 to skip drain (immediate cleanup).
+     *
+     * The drain phase blocks new deliveries (including scheduled retries) and
+     * awaits all currently-running handlers. Reaching the timeout logs a warn
+     * and continues with cleanup; pending handlers will keep running but their
+     * results are discarded.
+     */
+    drainTimeoutMs?: number;
+}
+/**
+ * In-process message transport. Fire-and-forget delivery via `queueMicrotask`,
+ * exponential backoff retry via `setTimeout`, auto-DLQ via re-publishing to
+ * `<topic>.dlq`.
+ *
+ * NOT persistent. Process crash mid-retry loses pending messages - do not use
+ * for durability-sensitive workloads. Use `@miiajs/messaging-redis` or another
+ * broker-backed transport in production.
+ *
+ * **Dispatch capability:** sliding-only, no competing consumers. The in-memory
+ * transport is single-process: there is no broker to round-robin messages
+ * between multiple handlers in a shared `group`. Auto-derived per-handler
+ * groups work normally (each handler is its own subscription, fan-out is
+ * automatic). Handlers requesting `mode: 'batch'` or sharing an explicit
+ * `group` are rejected at `MessageBus.onReady()`.
+ */
+export declare class InMemoryTransport implements MessageTransport {
+    readonly supportedModes: readonly ["sliding"];
+    readonly defaultMode: DispatchMode;
+    readonly supportsCompetingConsumers = false;
+    private subs;
+    private retry;
+    private cloneOnPublish;
+    private drainTimeoutMs;
+    private logger;
+    private pendingTimers;
+    private pendingDeliveries;
+    private destroying;
+    constructor(options?: InMemoryTransportOptions);
+    publish(envelope: MessageEnvelope): Promise<void>;
+    subscribe(topic: string, handler: (envelope: MessageEnvelope) => Promise<HandlerResult>, _options: SubscribeOptions): Promise<Subscription>;
+    onDestroy(): Promise<void>;
+    /** Tracking wrapper - every (initial and retry) delivery flows through here. */
+    private deliver;
+    private runDelivery;
+    private waitForDrain;
+}
+export declare function inMemoryTransport(options?: InMemoryTransportOptions): MessageTransport;
+//# sourceMappingURL=in-memory-transport.d.ts.map

package/dist/in-memory-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-transport.d.ts","sourceRoot":"","sources":["../src/in-memory-transport.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAA;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AASD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAkB,YAAW,gBAAgB;IACxD,QAAQ,CAAC,cAAc,uBAAyD;IAChF,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAY;IAC9C,QAAQ,CAAC,0BAA0B,SAAQ;IAE3C,OAAO,CAAC,IAAI,CAAgC;IAC5C,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,UAAU,CAAQ;gBAEd,OAAO,GAAE,wBAA6B;IAM5C,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjD,SAAS,CACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,aAAa,CAAC,EAC9D,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,YAAY,CAAC;IAmBlB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAQhC,gFAAgF;IAChF,OAAO,CAAC,OAAO;YAQD,WAAW;YAyCX,YAAY;CAkB3B;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,gBAAgB,CAE1F"}