@zudojs/messaging 1.0.2 → 1.2.0

package/README.md

@@ -88,8 +88,34 @@ one that failed, with its real duration.
 Handlers receive the dispatch context as their second argument: the
 `headers`, `state` and correlation/causation overrides passed through
 `DispatchOptions.context`, plus anything a middleware stored in
-`context.state`. A dispatch cancelled through its `AbortSignal` between
-handlers fails with `MessageDispatchAbortedError`.
+`context.state`.
+
+`send()` also puts a `correlationId` or `causationId` given in
+`options.context` on the message it builds (unless the input carries its
+own), so `createDerivedMessage(message, …)` in a handler stays in the same
+chain:
+
+```typescript
+bus.on("order.placed", (message) => {
+  const next = createDerivedMessage(message, { type: "invoice.requested", payload: {} });
+  next.correlationId; // "req-42"
+});
+
+await bus.send(
+  { type: "order.placed", payload: order },
+  { context: { correlationId: toCorrelationId("req-42") } },
+);
+```
+
+## Cancellation
+
+A dispatch whose `AbortSignal` fires fails with `MessageDispatchAbortedError`
+(`success: false`), whenever the abort lands: between handlers, or during the
+last or only one — even if that handler ignores the signal and returns
+normally. Like a timeout, it settles promptly rather than waiting for a handler
+that ignores its signal. `handlerResults` still lists every handler that
+finished. Before 1.2.0 an abort during the last handler was reported as
+`success: true`.
 
 ## Timeouts
 

package/dist/dispatcher/dispatcher.abort.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turning an aborted dispatch signal into a failed dispatch.
+ *
+ * A timeout rejected the dispatch as soon as it fired, but a caller's abort
+ * only stopped the *next* handler from starting: when it arrived during the
+ * last or only handler, and that handler returned normally, the dispatch was
+ * reported as `success: true`.
+ *
+ * @module dispatcher/dispatcher.abort
+ */
+import type { Message } from "../message/messageType.type.js";
+/** A rejection armed on a signal, and the means to disarm it. */
+export interface AbortRejection {
+    /** Rejects once the signal aborts; never resolves. */
+    readonly promise: Promise<never>;
+    /** Detaches from the signal and cancels a pending rejection. */
+    readonly dispose: () => void;
+}
+/**
+ * The error a dispatch fails with once `signal` has aborted.
+ *
+ * A timeout aborts with its own {@link MessageTimeoutError}, which is kept;
+ * any other abort is reported as {@link MessageDispatchAbortedError}.
+ */
+export declare function abortErrorFor(signal: AbortSignal, message: Message): Error;
+/** Throws the dispatch's abort error when `signal` has aborted. */
+export declare function assertDispatchNotAborted(signal: AbortSignal, message: Message): void;
+/**
+ * A promise that rejects when `signal` aborts, so a dispatch settles
+ * promptly — as it does on a timeout — even while a handler that ignores its
+ * signal is still running.
+ *
+ * The rejection waits one macrotask. A handler that aborts and then returns
+ * synchronously has its result recorded first, so `handlerResults` still
+ * lists every handler that finished.
+ */
+export declare function abortRejection(signal: AbortSignal, message: Message): AbortRejection;
+//# sourceMappingURL=dispatcher.abort.d.ts.map

package/dist/dispatcher/dispatcher.abort.js

@@ -0,0 +1,62 @@
+/**
+ * Turning an aborted dispatch signal into a failed dispatch.
+ *
+ * A timeout rejected the dispatch as soon as it fired, but a caller's abort
+ * only stopped the *next* handler from starting: when it arrived during the
+ * last or only handler, and that handler returned normally, the dispatch was
+ * reported as `success: true`.
+ *
+ * @module dispatcher/dispatcher.abort
+ */
+import { MessageDispatchAbortedError, MessageTimeoutError, } from "@zudojs/errors";
+/**
+ * The error a dispatch fails with once `signal` has aborted.
+ *
+ * A timeout aborts with its own {@link MessageTimeoutError}, which is kept;
+ * any other abort is reported as {@link MessageDispatchAbortedError}.
+ */
+export function abortErrorFor(signal, message) {
+    if (signal.reason instanceof MessageTimeoutError)
+        return signal.reason;
+    return new MessageDispatchAbortedError(undefined, {
+        messageType: message.type,
+        messageId: message.id,
+    });
+}
+/** Throws the dispatch's abort error when `signal` has aborted. */
+export function assertDispatchNotAborted(signal, message) {
+    if (signal.aborted)
+        throw abortErrorFor(signal, message);
+}
+/**
+ * A promise that rejects when `signal` aborts, so a dispatch settles
+ * promptly — as it does on a timeout — even while a handler that ignores its
+ * signal is still running.
+ *
+ * The rejection waits one macrotask. A handler that aborts and then returns
+ * synchronously has its result recorded first, so `handlerResults` still
+ * lists every handler that finished.
+ */
+export function abortRejection(signal, message) {
+    let pending;
+    let onAbort;
+    const promise = new Promise((_resolve, reject) => {
+        onAbort = () => {
+            pending = setImmediate(() => reject(abortErrorFor(signal, message)));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    // The race owns this promise's outcome; a rejection that loses the race
+    // must not surface as unhandled.
+    promise.catch(() => { });
+    return {
+        promise,
+        dispose: () => {
+            if (onAbort)
+                signal.removeEventListener("abort", onAbort);
+            if (pending !== undefined)
+                clearImmediate(pending);
+        },
+    };
+}
+//# sourceMappingURL=dispatcher.abort.js.map

package/dist/dispatcher/dispatcherCore.js

@@ -4,8 +4,10 @@
  * @module dispatcher/dispatcherCore
  */
 import { createMessageContext } from "../messageContext/messageContextType.type.js";
+import { resolveMessageHandler } from "../messageHandler/messageHandlerType.type.js";
 import { HandlerRegistryStore } from "../handlerRegistry/handlerRegistryStore.js";
 import { runMessagePipeline } from "../messageMiddleware/messageMiddlewarePipeline.js";
+import { abortRejection, assertDispatchNotAborted, } from "./dispatcher.abort.js";
 import { MessageDispatchAbortedError, MessageHandlerError, MessageMiddlewareError, MessageTimeoutError, MessageBusDisposedError, } from "@zudojs/errors";
 /** Default priority for middleware that does not declare one. */
 const DEFAULT_MIDDLEWARE_PRIORITY = 100;
@@ -51,6 +53,7 @@ export class DefaultDispatcher {
         const handlers = this.registry.resolve(message.type);
         const handlerResults = [];
         let timer;
+        const aborted = abortRejection(context.signal, message);
         try {
             const run = runMessagePipeline(allMiddleware, 
             // Handlers receive the same context the middleware saw: the one
@@ -66,21 +69,32 @@ export class DefaultDispatcher {
             });
             // `DispatchOptions.timeout` was documented on the dispatcher but only
             // ever honoured by the bus wrapper, so anyone holding a dispatcher
-            // directly got no timeout at all.
-            const pipelineResult = timeout > 0
-                ? await Promise.race([
-                    run,
-                    this.timeoutRejection(message, timeout, controller, (t) => {
-                        timer = t;
-                    }),
-                ])
-                : await run;
+            // directly got no timeout at all. An abort settles the dispatch the
+            // same way: promptly, and as a failure.
+            const pipelineResult = await Promise.race([
+                run,
+                aborted.promise,
+                ...(timeout > 0
+                    ? [
+                        this.timeoutRejection(message, timeout, controller, (t) => {
+                            timer = t;
+                        }),
+                    ]
+                    : []),
+            ]);
+            // A handler that returned normally after the abort does not make the
+            // dispatch a success: it was cancelled.
+            assertDispatchNotAborted(context.signal, message);
             return {
                 success: true,
                 value: pipelineResult.result,
                 message,
                 context,
-                handlerResults,
+                // A copy, not the live array: on a timeout the dispatch settles
+                // while a handler is still running, and that handler later pushed
+                // a `success: true` record into the result the caller was already
+                // holding for a dispatch that had failed.
+                handlerResults: [...handlerResults],
                 middlewareResult: pipelineResult,
                 duration: performance.now() - dispatchStart,
             };
@@ -91,13 +105,14 @@ export class DefaultDispatcher {
                 error: error instanceof Error ? error : new Error(String(error)),
                 message,
                 context,
-                handlerResults,
+                handlerResults: [...handlerResults],
                 duration: performance.now() - dispatchStart,
             };
         }
         finally {
             if (timer !== undefined)
                 clearTimeout(timer);
+            aborted.dispose();
             // Detach from the caller's signal, otherwise a long-lived signal
             // shared across dispatches accumulates one listener per dispatch.
             release();
@@ -190,7 +205,11 @@ export class DefaultDispatcher {
     }
     async executeHandler(handler, message, context) {
         try {
-            return await handler.handler(message, context);
+            // Handlers may be a plain function or an object with a `handle`
+            // method. Calling `handler.handler(...)` directly made the object
+            // form crash on every dispatch, so it goes through the same
+            // normaliser the public type advertises.
+            return await resolveMessageHandler(handler.handler)(message, context);
         }
         catch (error) {
             throw new MessageHandlerError(`Handler "${handler.id}" failed: ${error instanceof Error ? error.message : String(error)}`, {

package/dist/dispatcher/dispatcherType.type.d.ts

@@ -9,6 +9,7 @@
 import type { Message } from "../message/messageType.type.js";
 import type { MessageContext, MessageContextOptions } from "../messageContext/messageContextType.type.js";
 import type { MessageMiddlewareLike, MessageMiddlewareOptions, MessageMiddlewarePipelineResult } from "../messageMiddleware/messageMiddlewareType.type.js";
+import type { HandlerRegistryStore } from "../handlerRegistry/handlerRegistryStore.js";
 /**
  * Result of dispatching a message.
  */
@@ -90,5 +91,18 @@ export interface Dispatcher {
      * @returns Whether a registration was removed.
      */
     removeMiddleware(middlewareId: string): boolean;
+    /**
+     * The ids of every registered global middleware, in the order they run.
+     */
+    listMiddleware(): readonly string[];
+    /**
+     * The handler registry this dispatcher resolves handlers from.
+     */
+    getRegistry(): HandlerRegistryStore;
+    /**
+     * Releases the dispatcher: drops all middleware and rejects any further
+     * dispatch with `MessageBusDisposedError`.
+     */
+    dispose(): void;
 }
 //# sourceMappingURL=dispatcherType.type.d.ts.map

package/dist/messageBus/messageBusCore.js

@@ -46,7 +46,15 @@ export class InMemoryMessageBus {
         }
     }
     async send(input, options = {}) {
-        return this.dispatch(createMessage(input), options);
+        // Identifiers given through the dispatch context belong on the message
+        // too; otherwise `createDerivedMessage` in a handler starts a new chain.
+        const context = options.context;
+        const message = createMessage({
+            ...input,
+            correlationId: input.correlationId ?? context?.correlationId,
+            causationId: input.causationId ?? context?.causationId,
+        });
+        return this.dispatch(message, options);
     }
     on(messageType, handler, options = {}) {
         // A clock-derived id collided whenever two handlers for the same type

package/dist/messageBus/messageBusType.type.d.ts

@@ -40,6 +40,10 @@ export interface MessageBus {
     dispatch<TPayload, TResult>(message: Message<TPayload>, options?: DispatchOptions<TResult>): Promise<DispatchResult<TResult>>;
     /**
      * Convenience method: creates and dispatches a message from input.
+     *
+     * A `correlationId` or `causationId` given in `options.context` is also
+     * put on the message when the input carries none, so a message derived
+     * from it in a handler stays in the same chain.
      */
     send<TPayload, TResult>(input: MessageInput<TPayload>, options?: DispatchOptions<TResult>): Promise<DispatchResult<TResult>>;
     /**

package/dist/messageHandler/messageHandlerType.type.d.ts

@@ -35,8 +35,13 @@ export interface NamedMessageHandler<TMessage extends Message = Message, TResult
     readonly id: string;
     /** Human-readable name for debugging. */
     readonly name: string;
-    /** The handler function. */
-    readonly handler: MessageHandler<TMessage, TResult>;
+    /**
+     * The handler itself: a function, or an object with a `handle` method.
+     *
+     * The dispatcher normalises both forms through
+     * {@link resolveMessageHandler} before invoking them.
+     */
+    readonly handler: MessageHandlerLike<TMessage, TResult>;
     /** Message types this handler processes. */
     readonly messageTypes: readonly string[];
     /** Execution priority (lower = earlier). Default: 100. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/messaging",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "In-process message bus infrastructure with handlers, middleware, and publish/subscribe patterns.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,16 +19,16 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/middleware": "1.0.2"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/middleware": "1.1.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "author": {
@@ -44,7 +44,7 @@
     "message-bus",
     "pubsub"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-messaging",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },