@zudojs/messaging 1.1.0 → 1.2.1

package/README.md

@@ -88,8 +88,39 @@ 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`.
+
+Cancellation uses only `AbortSignal` and `setTimeout`, so it works in
+browsers and other non-Node runtimes. 1.2.0 scheduled the abort with Node's
+`setImmediate`, and aborting a dispatch in a browser threw
+`ReferenceError: setImmediate is not defined`; later releases do not.
 
 ## Timeouts
 

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ *
+ * The macrotask is a `setTimeout(…, 0)`, not `setImmediate`: the package is
+ * not Node-only, and browsers have no `setImmediate`, so an abort there
+ * threw a `ReferenceError`. A microtask would not do — the dispatch records
+ * a handler's result several promise hops after the handler returns.
+ */
+export declare function abortRejection(signal: AbortSignal, message: Message): AbortRejection;
+//# sourceMappingURL=dispatcher.abort.d.ts.map

package/dist/dispatcher/dispatcher.abort.js

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ *
+ * The macrotask is a `setTimeout(…, 0)`, not `setImmediate`: the package is
+ * not Node-only, and browsers have no `setImmediate`, so an abort there
+ * threw a `ReferenceError`. A microtask would not do — the dispatch records
+ * a handler's result several promise hops after the handler returns.
+ */
+export function abortRejection(signal, message) {
+    let pending;
+    let onAbort;
+    const promise = new Promise((_resolve, reject) => {
+        onAbort = () => {
+            pending = setTimeout(() => reject(abortErrorFor(signal, message)), 0);
+        };
+        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)
+                clearTimeout(pending);
+        },
+    };
+}
+//# sourceMappingURL=dispatcher.abort.js.map

package/dist/dispatcher/dispatcherCore.js

@@ -7,6 +7,7 @@ import { createMessageContext } from "../messageContext/messageContextType.type.
 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;
@@ -52,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
@@ -67,15 +69,22 @@ 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,
@@ -103,6 +112,7 @@ export class DefaultDispatcher {
         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();

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/messaging",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "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.1",
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/middleware": "1.0.3"
+    "@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"
   },