@miiajs/messaging 0.1.0

package/dist/in-memory-transport.js

@@ -0,0 +1,143 @@
+import { Logger } from '@miiajs/core';
+import { dlqTopic, nextBackoffMs } from './retry.js';
+import { DEFAULT_RETRY, } from './types.js';
+const DEFAULT_DRAIN_TIMEOUT_MS = 5000;
+/**
+ * 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 class InMemoryTransport {
+    supportedModes = ['sliding'];
+    defaultMode = 'sliding';
+    supportsCompetingConsumers = false;
+    subs = new Map();
+    retry;
+    cloneOnPublish;
+    drainTimeoutMs;
+    logger = new Logger('InMemoryTransport');
+    pendingTimers = new Set();
+    pendingDeliveries = new Set();
+    destroying = false;
+    constructor(options = {}) {
+        this.retry = { ...DEFAULT_RETRY, ...options.retry };
+        this.cloneOnPublish = options.cloneOnPublish ?? false;
+        this.drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+    }
+    async publish(envelope) {
+        const subs = this.subs.get(envelope.topic);
+        if (!subs || subs.length === 0)
+            return;
+        // Fire-and-forget: resolve immediately, handlers run in microtask.
+        queueMicrotask(() => {
+            for (const sub of subs) {
+                this.deliver(sub, envelope);
+            }
+        });
+    }
+    async subscribe(topic, handler, _options) {
+        // SubscribeOptions.group and .concurrency are meaningless in a single
+        // process - local fan-out always delivers to every subscriber.
+        const sub = { topic, handler };
+        const list = this.subs.get(topic) ?? [];
+        list.push(sub);
+        this.subs.set(topic, list);
+        return {
+            unsubscribe: async () => {
+                const list = this.subs.get(topic);
+                if (!list)
+                    return;
+                const idx = list.indexOf(sub);
+                if (idx >= 0)
+                    list.splice(idx, 1);
+                if (list.length === 0)
+                    this.subs.delete(topic);
+            },
+        };
+    }
+    async onDestroy() {
+        this.destroying = true;
+        await this.waitForDrain();
+        for (const timer of this.pendingTimers)
+            clearTimeout(timer);
+        this.pendingTimers.clear();
+        this.subs.clear();
+    }
+    /** Tracking wrapper - every (initial and retry) delivery flows through here. */
+    deliver(sub, envelope) {
+        if (this.destroying)
+            return; // refuse new work during shutdown
+        const promise = this.runDelivery(sub, envelope);
+        this.pendingDeliveries.add(promise);
+        promise.finally(() => this.pendingDeliveries.delete(promise));
+    }
+    async runDelivery(sub, envelope) {
+        const delivered = this.cloneOnPublish ? { ...envelope, payload: structuredClone(envelope.payload) } : envelope;
+        let result;
+        try {
+            result = await sub.handler(delivered);
+        }
+        catch (err) {
+            result = { status: 'nack', error: err instanceof Error ? err : new Error(String(err)) };
+        }
+        if (result.status === 'ack')
+            return;
+        // Nack: retry or DLQ.
+        if (envelope.meta.attempt < this.retry.maxAttempts) {
+            const delay = nextBackoffMs(envelope.meta.attempt, this.retry);
+            const timer = setTimeout(() => {
+                this.pendingTimers.delete(timer);
+                // Retry routes back through deliver() so it's tracked in pendingDeliveries.
+                this.deliver(sub, {
+                    ...envelope,
+                    meta: { ...envelope.meta, attempt: envelope.meta.attempt + 1 },
+                });
+            }, delay);
+            this.pendingTimers.add(timer);
+            return;
+        }
+        // Final failure.
+        this.logger.error(`Message ${envelope.id} on ${envelope.topic} exhausted ${this.retry.maxAttempts} attempts`, result.error.stack ?? result.error.message);
+        if (this.retry.dlq) {
+            await this.publish({
+                ...envelope,
+                topic: dlqTopic(envelope.topic),
+                meta: { ...envelope.meta, lastError: result.error.message },
+            });
+        }
+    }
+    async waitForDrain() {
+        if (this.drainTimeoutMs <= 0 || this.pendingDeliveries.size === 0)
+            return;
+        const drainPromise = Promise.allSettled([...this.pendingDeliveries]);
+        let timer = null;
+        const timeoutPromise = new Promise((r) => {
+            timer = setTimeout(() => r('timeout'), this.drainTimeoutMs);
+        });
+        try {
+            const result = await Promise.race([drainPromise.then(() => 'drained'), timeoutPromise]);
+            if (result === 'timeout') {
+                this.logger.warn(`Drain timeout: ${this.pendingDeliveries.size} handler(s) still in flight`);
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+}
+export function inMemoryTransport(options = {}) {
+    return new InMemoryTransport(options);
+}
+//# sourceMappingURL=in-memory-transport.js.map

package/dist/in-memory-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-transport.js","sourceRoot":"","sources":["../src/in-memory-transport.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { MessageBus } from './message-bus.js';
+export { Idempotent, IDEMPOTENT, On, ON } from './decorators.js';
+export type { IdempotentMeta, OnMeta } from './decorators.js';
+export { IDEMPOTENCY_STORE, MemoryIdempotencyStore, memoryIdempotencyStore } from './idempotency.js';
+export type { IdempotencyStore, MemoryIdempotencyStoreOptions } from './idempotency.js';
+export { DEFAULT_RETRY, MESSAGE_TRANSPORT } from './types.js';
+export type { DispatchMode, MessageEnvelope, MessageMeta, MessageTransport, HandlerResult, RetryConfig, SubscribeOptions, Subscription, } from './types.js';
+export { dlqTopic, nextBackoffMs } from './retry.js';
+export { deriveGroupName } from './group-name.js';
+export type { DeriveGroupNameInput } from './group-name.js';
+export { InMemoryTransport, inMemoryTransport } from './in-memory-transport.js';
+export type { InMemoryTransportOptions } from './in-memory-transport.js';
+export { MessagingModule } from './messaging.module.js';
+export type { DispatchDefaults, MessagingModuleOptions } from './messaging.module.js';
+export { getMessageBusToken, getMessageTransportToken, getIdempotencyStoreToken } from './tokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAA;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAE7D,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACpG,YAAY,EAAE,gBAAgB,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAA;AAEvF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAC7D,YAAY,EACV,YAAY,EACZ,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEpD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,YAAY,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAE3D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC/E,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAExE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAErF,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// @miiajs/messaging - public API
+export { MessageBus } from './message-bus.js';
+export { Idempotent, IDEMPOTENT, On, ON } from './decorators.js';
+export { IDEMPOTENCY_STORE, MemoryIdempotencyStore, memoryIdempotencyStore } from './idempotency.js';
+export { DEFAULT_RETRY, MESSAGE_TRANSPORT } from './types.js';
+export { dlqTopic, nextBackoffMs } from './retry.js';
+export { deriveGroupName } from './group-name.js';
+export { InMemoryTransport, inMemoryTransport } from './in-memory-transport.js';
+export { MessagingModule } from './messaging.module.js';
+export { getMessageBusToken, getMessageTransportToken, getIdempotencyStoreToken } from './tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAEjC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAA;AAGhE,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAGpG,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAY7D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEpD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGjD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAG/E,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAGvD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA"}

package/dist/message-bus.d.ts

@@ -0,0 +1,83 @@
+import type { IdempotencyStore } from './idempotency.js';
+import { type DispatchMode, type MessageMeta, type MessageTransport } from './types.js';
+/** Bus-level dispatch defaults forwarded from `MessagingModuleOptions.dispatch`. */
+interface DispatchDefaults {
+    mode?: DispatchMode;
+    concurrency?: number;
+}
+/** Options bag for the `MessageBus` constructor 4th argument. */
+interface MessageBusOptions {
+    dispatch?: DispatchDefaults | null;
+    appName?: string | null;
+}
+/**
+ * Central message bus. Inject from any provider:
+ *
+ * ```ts
+ * @Injectable()
+ * class OrderService {
+ *   private bus = inject(MessageBus)
+ *
+ *   async placeOrder(order: Order) {
+ *     await this.bus.publish('order.placed', order)
+ *   }
+ * }
+ * ```
+ *
+ * `@On` handlers are discovered via `DiscoveryService` during `onReady()`.
+ * Each `@On` becomes its own broker subscription with an auto-derived
+ * consumer group `<topic>__<ClassName>_<methodName>` (or
+ * `<appName>:<topic>__<ClassName>_<methodName>` when `MessagingModule.configure`
+ * provides `appName`). Handlers run independently - retry, ack/nack,
+ * mode/concurrency are isolated per handler.
+ *
+ * For multi-bus setups, use `MessagingModule.configure(opts, name)` and inject
+ * the named bus via `inject<MessageBus>(getMessageBusToken(name))`. Handlers
+ * target a specific bus via `@On(topic, { bus: name })`.
+ *
+ * `MessageBus.publish` and `MessageTransport.publish` share the method name
+ * but live at different layers: `MessageBus.publish(topic, payload, meta)`
+ * is the high-level API that fills in `id`/`timestamp`/`attempt` and hands
+ * a fully-formed envelope to `MessageTransport.publish(envelope)`. Both can
+ * appear in stack traces; signature shape (envelope vs payload+meta) makes
+ * the layer obvious.
+ */
+export declare class MessageBus {
+    private transport;
+    private idempotencyStore;
+    private busName;
+    private options;
+    private discovery;
+    private resolver;
+    private logger;
+    private subscriptions;
+    constructor(transport: MessageTransport, idempotencyStore: IdempotencyStore | null, busName: string | null, options?: MessageBusOptions);
+    onReady(): Promise<void>;
+    private getIdempotentMeta;
+    /**
+     * Publish a message. Meta fields are optional and additive - the framework
+     * fills in `id`, `timestamp`, and `attempt`. Composes onto
+     * `MessageTransport.publish(envelope)` internally.
+     *
+     * For distributed tracing, populate `traceparent` (and optionally `tracestate`)
+     * from your tracing library so consumers can continue the trace.
+     *
+     * @example
+     * ```ts
+     * import { trace } from '@opentelemetry/api'
+     *
+     * const span = trace.getActiveSpan()
+     * const ctx = span?.spanContext()
+     * await bus.publish('order.placed', order, {
+     *   traceparent: ctx
+     *     ? `00-${ctx.traceId}-${ctx.spanId}-${ctx.traceFlags.toString(16).padStart(2, '0')}`
+     *     : undefined,
+     * })
+     * ```
+     */
+    publish<T>(topic: string, payload: T, meta?: Partial<Pick<MessageMeta, 'correlationId' | 'causationId' | 'traceparent' | 'tracestate'>>): Promise<void>;
+    onDestroy(): Promise<void>;
+    private dispatch;
+}
+export {};
+//# sourceMappingURL=message-bus.d.ts.map

package/dist/message-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-bus.d.ts","sourceRoot":"","sources":["../src/message-bus.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,OAAO,EACL,KAAK,YAAY,EAGjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EAEtB,MAAM,YAAY,CAAA;AAEnB,oFAAoF;AACpF,UAAU,gBAAgB;IACxB,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,iEAAiE;AACjE,UAAU,iBAAiB;IACzB,QAAQ,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAClC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,UAAU;IASnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;IAVjB,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,QAAQ,CAAmB;IAEnC,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,aAAa,CAAqB;gBAGhC,SAAS,EAAE,gBAAgB,EAC3B,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,EACzC,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,OAAO,GAAE,iBAAsB;IAKnC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA8G9B,OAAO,CAAC,iBAAiB;IAKzB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,CAAC,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,EACV,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,GAAG,aAAa,GAAG,aAAa,GAAG,YAAY,CAAC,CAAC,GAChG,OAAO,CAAC,IAAI,CAAC;IAcV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;YAOlB,QAAQ;CA6CvB"}

package/dist/message-bus.js

@@ -0,0 +1,218 @@
+import { randomUUID } from 'node:crypto';
+import { DiscoveryService, getMeta, inject, Logger, Resolver } from '@miiajs/core';
+import { IDEMPOTENT, ON } from './decorators.js';
+import { deriveGroupName } from './group-name.js';
+import { getMessageBusToken } from './tokens.js';
+import {} from './types.js';
+/**
+ * Central message bus. Inject from any provider:
+ *
+ * ```ts
+ * @Injectable()
+ * class OrderService {
+ *   private bus = inject(MessageBus)
+ *
+ *   async placeOrder(order: Order) {
+ *     await this.bus.publish('order.placed', order)
+ *   }
+ * }
+ * ```
+ *
+ * `@On` handlers are discovered via `DiscoveryService` during `onReady()`.
+ * Each `@On` becomes its own broker subscription with an auto-derived
+ * consumer group `<topic>__<ClassName>_<methodName>` (or
+ * `<appName>:<topic>__<ClassName>_<methodName>` when `MessagingModule.configure`
+ * provides `appName`). Handlers run independently - retry, ack/nack,
+ * mode/concurrency are isolated per handler.
+ *
+ * For multi-bus setups, use `MessagingModule.configure(opts, name)` and inject
+ * the named bus via `inject<MessageBus>(getMessageBusToken(name))`. Handlers
+ * target a specific bus via `@On(topic, { bus: name })`.
+ *
+ * `MessageBus.publish` and `MessageTransport.publish` share the method name
+ * but live at different layers: `MessageBus.publish(topic, payload, meta)`
+ * is the high-level API that fills in `id`/`timestamp`/`attempt` and hands
+ * a fully-formed envelope to `MessageTransport.publish(envelope)`. Both can
+ * appear in stack traces; signature shape (envelope vs payload+meta) makes
+ * the layer obvious.
+ */
+export class MessageBus {
+    transport;
+    idempotencyStore;
+    busName;
+    options;
+    // Field-init for shared globals (idiomatic MiiaJS pattern).
+    discovery = inject(DiscoveryService);
+    resolver = inject(Resolver);
+    // Logger init in constructor body because it depends on busName.
+    logger;
+    subscriptions = [];
+    constructor(transport, idempotencyStore, busName, options = {}) {
+        this.transport = transport;
+        this.idempotencyStore = idempotencyStore;
+        this.busName = busName;
+        this.options = options;
+        this.logger = new Logger(busName ? `MessageBus:${busName}` : 'MessageBus');
+    }
+    async onReady() {
+        const allHandlers = this.discovery.getMethodsWithMeta(ON);
+        // Validation: every referenced bus name must point to a registered bus.
+        // Each bus instance runs this check; first onReady to fail throws.
+        for (const h of allHandlers) {
+            const refBus = h.metadata.bus ?? null;
+            const token = getMessageBusToken(refBus ?? undefined);
+            if (!this.resolver.has(token)) {
+                throw new Error(`[messaging] @On on ${h.ctor.name}.${h.methodName} references bus '${refBus ?? '<default>'}', ` +
+                    `but no MessagingModule.configure(opts${refBus ? `, '${refBus}'` : ''}) is registered.`);
+            }
+        }
+        // Filter to handlers targeting THIS bus.
+        const handlers = allHandlers.filter((h) => (h.metadata.bus ?? null) === this.busName);
+        const transportName = this.transport.constructor.name;
+        const dispatchDefaults = this.options.dispatch ?? null;
+        const appName = this.options.appName ?? null;
+        for (const h of handlers) {
+            const meta = h.metadata;
+            // Startup validation: @Idempotent without configured store → fail fast.
+            const idemMeta = this.getIdempotentMeta(h.ctor, h.methodName);
+            if (idemMeta && !this.idempotencyStore) {
+                throw new Error(`[messaging] @Idempotent on ${h.ctor.name}.${h.methodName} requires an IdempotencyStore. ` +
+                    `Pass \`idempotency: memoryIdempotencyStore()\` (dev) or ` +
+                    `\`idempotency: redisIdempotencyStore({...})\` (prod) to MessagingModule.configure().`);
+            }
+            // broadcast and explicit group are conceptually opposite intents.
+            if (meta.broadcast && meta.group) {
+                throw new Error(`[messaging] @On on ${h.ctor.name}.${h.methodName}: broadcast and group are mutually exclusive. ` +
+                    `Use broadcast for cluster-wide fan-out, or group for an explicit competing-consumers pool, not both.`);
+            }
+            // @Idempotent default key is `${envelope.id}:${ctor}.${method}` - shared
+            // across replicas. With broadcast, every replica receives a copy; the
+            // first replica claims the key and the rest see a stale claim → silent
+            // skip → broadcast effectively becomes "first wins". Reject at startup
+            // unless the user provided an explicit key callback (presumably scoped
+            // per-process).
+            if (meta.broadcast && idemMeta && !idemMeta.key) {
+                throw new Error(`[messaging] @On on ${h.ctor.name}.${h.methodName} combines broadcast: true with @Idempotent ` +
+                    `using the default key, but the default key is shared across replicas - the first replica to ` +
+                    `claim it would silently skip the handler on every other replica, breaking broadcast semantics. ` +
+                    `Either remove @Idempotent (broadcast usually targets non-idempotent local state like cache invalidation) ` +
+                    `or provide an explicit \`key\` callback that scopes the claim per replica.`);
+            }
+            // Explicit broker group requires the transport to support
+            // competing-consumers semantic (broker round-robin within a group).
+            if (meta.group && !this.transport.supportsCompetingConsumers) {
+                throw new Error(`[messaging] @On on ${h.ctor.name}.${h.methodName} on bus '${this.busName ?? '<default>'}' ` +
+                    `declares explicit group '${meta.group}', but transport ${transportName} does not support ` +
+                    `competing consumers. Either remove the group option (use the auto-derived per-handler group) ` +
+                    `or use a transport with broker-side consumer groups (e.g. RedisStreamsTransport).`);
+            }
+            const effectiveMode = meta.mode ?? dispatchDefaults?.mode ?? this.transport.defaultMode;
+            const effectiveConcurrency = meta.concurrency ?? dispatchDefaults?.concurrency ?? 1;
+            if (!this.transport.supportedModes.includes(effectiveMode)) {
+                const supported = this.transport.supportedModes.map((m) => `'${m}'`).join(', ');
+                throw new Error(`[messaging] @On on ${h.ctor.name}.${h.methodName} on bus '${this.busName ?? '<default>'}' ` +
+                    `for topic '${meta.topic}' requests dispatch mode '${effectiveMode}' which is not supported by ` +
+                    `${transportName}. Supported modes: [${supported}].`);
+            }
+            if (effectiveConcurrency <= 0 || !Number.isFinite(effectiveConcurrency)) {
+                throw new Error(`[messaging] @On on ${h.ctor.name}.${h.methodName} for topic '${meta.topic}' resolves to ` +
+                    `concurrency=${effectiveConcurrency}, which is invalid. Concurrency must be a positive integer ` +
+                    `(minimum 1).`);
+            }
+            const group = deriveGroupName({
+                topic: meta.topic,
+                ctorName: h.ctor.name,
+                methodName: h.methodName,
+                appName,
+                explicitGroup: meta.group,
+                broadcast: meta.broadcast,
+            });
+            const sub = await this.transport.subscribe(meta.topic, async (envelope) => this.dispatch(h, envelope), {
+                group,
+                concurrency: effectiveConcurrency,
+                mode: effectiveMode,
+                broadcast: meta.broadcast,
+            });
+            this.subscriptions.push(sub);
+        }
+    }
+    getIdempotentMeta(ctor, methodName) {
+        const map = getMeta(ctor, IDEMPOTENT);
+        return map?.get(methodName);
+    }
+    /**
+     * Publish a message. Meta fields are optional and additive - the framework
+     * fills in `id`, `timestamp`, and `attempt`. Composes onto
+     * `MessageTransport.publish(envelope)` internally.
+     *
+     * For distributed tracing, populate `traceparent` (and optionally `tracestate`)
+     * from your tracing library so consumers can continue the trace.
+     *
+     * @example
+     * ```ts
+     * import { trace } from '@opentelemetry/api'
+     *
+     * const span = trace.getActiveSpan()
+     * const ctx = span?.spanContext()
+     * await bus.publish('order.placed', order, {
+     *   traceparent: ctx
+     *     ? `00-${ctx.traceId}-${ctx.spanId}-${ctx.traceFlags.toString(16).padStart(2, '0')}`
+     *     : undefined,
+     * })
+     * ```
+     */
+    async publish(topic, payload, meta) {
+        const envelope = {
+            id: randomUUID(),
+            topic,
+            payload,
+            meta: {
+                timestamp: Date.now(),
+                attempt: 1,
+                ...meta,
+            },
+        };
+        await this.transport.publish(envelope);
+    }
+    async onDestroy() {
+        for (const sub of this.subscriptions) {
+            await sub.unsubscribe();
+        }
+        this.subscriptions = [];
+    }
+    async dispatch(h, envelope) {
+        const callHandler = () => h.instance[h.methodName](envelope.payload, envelope.meta);
+        const idemMeta = this.getIdempotentMeta(h.ctor, h.methodName);
+        if (!idemMeta) {
+            try {
+                await callHandler();
+                return { status: 'ack' };
+            }
+            catch (err) {
+                this.logger.error(`Handler ${h.ctor.name}.${h.methodName} failed for ${envelope.topic} (attempt ${envelope.meta.attempt})`, err instanceof Error ? (err.stack ?? err.message) : String(err));
+                return { status: 'nack', error: err instanceof Error ? err : new Error(String(err)) };
+            }
+        }
+        // @Idempotent path: claim → run → release on failure.
+        // Per-handler default key avoids cross-handler conflicts; user can override
+        // via `key` to widen scope (e.g. share across handlers).
+        const id = idemMeta.key?.(envelope.payload, envelope.meta) ?? `${envelope.id}:${h.ctor.name}.${h.methodName}`;
+        const claimed = await this.idempotencyStore.claim(id, idemMeta.ttl);
+        if (!claimed)
+            return { status: 'ack' }; // already processed - silently skip
+        try {
+            await callHandler();
+            return { status: 'ack' };
+        }
+        catch (err) {
+            // Release so a retry can re-claim and re-process. Failure to release
+            // is logged but does not mask the original handler error.
+            await this.idempotencyStore.release(id).catch((releaseErr) => {
+                this.logger.error(`Failed to release idempotency claim ${id}`, String(releaseErr));
+            });
+            this.logger.error(`Handler ${h.ctor.name}.${h.methodName} failed for ${envelope.topic} (attempt ${envelope.meta.attempt})`, err instanceof Error ? (err.stack ?? err.message) : String(err));
+            return { status: 'nack', error: err instanceof Error ? err : new Error(String(err)) };
+        }
+    }
+}
+//# sourceMappingURL=message-bus.js.map

package/dist/message-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-bus.js","sourceRoot":"","sources":["../src/message-bus.ts"],"names":[],"mappings":"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"}

package/dist/messaging.module.d.ts

@@ -0,0 +1,76 @@
+import type { ConfiguredModule, OptionsOrFactory } from '@miiajs/core';
+import { type IdempotencyStore } from './idempotency.js';
+import { type DispatchMode, type MessageTransport } from './types.js';
+/**
+ * Bus-level defaults for dispatch behavior. Per-handler `@On({ mode, concurrency })`
+ * overrides these; if neither this nor the handler declares a value, the
+ * transport's `defaultMode` and a concurrency of `1` apply.
+ */
+export interface DispatchDefaults {
+    mode?: DispatchMode;
+    concurrency?: number;
+}
+export interface MessagingModuleOptions {
+    transport: MessageTransport;
+    /**
+     * Optional idempotency store for `@Idempotent` handlers. MessageBus throws
+     * at startup if any handler is annotated with `@Idempotent` but no store
+     * is configured here.
+     */
+    idempotency?: IdempotencyStore;
+    /**
+     * Bus-wide dispatch defaults. Resolution chain at `MessageBus.onReady()`:
+     *
+     *   `@On({ mode, concurrency })` > this `dispatch` > `transport.defaultMode` (and 1).
+     */
+    dispatch?: DispatchDefaults;
+    /**
+     * Application namespace for auto-derived consumer group names. When set,
+     * groups become `${appName}:${topic}__${ClassName}_${methodName}`. Use to
+     * avoid collisions when multiple services share a broker and have handlers
+     * with overlapping class names - without `appName`, their auto-derived
+     * groups collide and the broker round-robins messages between unrelated
+     * services.
+     *
+     * Does NOT prefix:
+     * - topics (those are shared cross-service contract)
+     * - explicit `@On({ group: '...' })` (user-controlled, full-qualified)
+     *
+     * Recommended for any production deployment with shared infrastructure.
+     */
+    appName?: string;
+}
+/**
+ * Dynamic module that registers a message transport, optional idempotency
+ * store, and `MessageBus` in the container.
+ *
+ * Pass an optional `name` to register a **named bus** alongside the default
+ * one - useful when an app needs more than one transport (Kafka + Redis,
+ * internal in-memory bus + external Redis, etc.). Handlers target a specific
+ * bus via `@On(topic, { bus: name })`.
+ *
+ * @example
+ * ```ts
+ * // Static form, default bus
+ * MessagingModule.configure({ transport: inMemoryTransport() })
+ *
+ * // Factory form with DI access
+ * MessagingModule.configure((resolve) => ({
+ *   transport: redisStreamsTransport({
+ *     url: resolve(ConfigService).getOrThrow('REDIS_URL'),
+ *   }),
+ * }))
+ *
+ * // Multi-bus: default + named
+ * MessagingModule.configure({ transport: redisStreamsTransport({ url: '...' }) })
+ * MessagingModule.configure({ transport: kafkaTransport({ ... }) }, 'kafka')
+ *
+ * // In a handler
+ * @On('order.placed')                      // default bus
+ * @On('legacy.user', { bus: 'kafka' })     // named bus
+ * ```
+ */
+export declare class MessagingModule {
+    static configure(optionsOrFactory: OptionsOrFactory<MessagingModuleOptions>, name?: string): ConfiguredModule;
+}
+//# sourceMappingURL=messaging.module.d.ts.map

package/dist/messaging.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.module.d.ts","sourceRoot":"","sources":["../src/messaging.module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAe,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAGnF,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAErE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,YAAY,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,gBAAgB,CAAA;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,eAAe;IAC1B,MAAM,CAAC,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB;CAqC9G"}