@zudojs/messaging 0.1.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+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

@@ -15,23 +15,101 @@ import { createMessageBus } from "@zudojs/messaging";
 
 const bus = createMessageBus();
 
-bus.subscribe("user.created", (message) => {
+bus.on("user.created", (message) => {
   console.log("New user:", message.payload);
 });
 
-await bus.publish({
+await bus.send({
   type: "user.created",
   payload: { id: "123" },
 });
+
+bus.dispose();
+```
+
+Use `send` to build and dispatch a message from plain input, or
+`dispatch` when you already hold a `Message`. Both run the middleware
+pipeline before reaching handlers. A disposed bus rejects further use
+with `MessageBusDisposedError`.
+
+## Message identifiers
+
+`MessageId`, `MessageCorrelationId` and `MessageCausationId` are branded
+types, so a plain string from a transport frame or a database row is not
+one. `createMessageId()` mints a new identifier; `toMessageId`,
+`toCorrelationId` and `toCausationId` brand an existing string, rejecting
+blank values:
+
+```typescript
+import { createMessage, toMessageId, toCorrelationId } from "@zudojs/messaging";
+
+const message = createMessage({
+  id: toMessageId(frame.id),
+  type: frame.type,
+  payload: frame.payload,
+  correlationId: toCorrelationId(frame.correlationId),
+});
+```
+
+## Middleware
+
+`use` returns the id `removeMiddleware` takes, so middleware can be taken off
+again. Middleware runs in ascending `priority` order (default 100), with
+registration order breaking ties:
+
+```typescript
+const id = bus.use(logging, { id: "logging", priority: 10 });
+bus.use(validation, { priority: 20 });
+
+bus.removeMiddleware(id); // true
 ```
 
+`enabled: false` registers middleware without running it.
+
+## Handlers
+
+By default a message type may have many handlers and all of them run. Pass
+`allowMultipleHandlers: false` for a command/query bus, where a second handler
+for the same type is a wiring mistake and is rejected at registration:
+
+```typescript
+const bus = createMessageBus({ allowMultipleHandlers: false });
+```
+
+`DispatchResult.handlerResults` records every handler that ran, including the
+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`.
+
+## Timeouts
+
+`timeout` is honoured by the dispatcher itself, so it applies whether you hold
+a bus or a dispatcher. On expiry the dispatch context's `AbortSignal` is
+aborted — a handler watching it can wind down — and the result carries a
+`MessageTimeoutError`:
+
+```typescript
+const result = await bus.dispatch(message, { timeout: 5_000 });
+if (!result.success && result.error instanceof MessageTimeoutError) {
+  // …
+}
+```
+
+`createMessageBus({ defaultTimeout })` sets the default for every dispatch.
+
 ## Features
 
-- Message bus with pub/sub
-- Middleware pipeline for messages
-- Message handlers with dependencies
-- In-memory transport
-- Message serialization
+- Message bus with handler registration and dispatch
+- Middleware pipeline with priorities, removal and per-execution telemetry
+- Named message handlers with priorities
+- Optional single-handler enforcement per message type
+- Per-dispatch timeouts that abort the handler through `AbortSignal`
+- Correlation and causation tracking
+- Branded message identifiers
 
 ## Use Cases
 

package/dist/dispatcher/dispatcherCore.d.ts

@@ -4,7 +4,7 @@
  * @module dispatcher/dispatcherCore
  */
 import type { Message } from "../message/messageType.type.js";
-import type { MessageMiddlewareLike } from "../messageMiddleware/messageMiddlewareType.type.js";
+import type { MessageMiddlewareLike, MessageMiddlewareOptions } from "../messageMiddleware/messageMiddlewareType.type.js";
 import type { Dispatcher, DispatchResult, DispatchOptions } from "./dispatcherType.type.js";
 import { HandlerRegistryStore } from "../handlerRegistry/handlerRegistryStore.js";
 /**
@@ -12,16 +12,51 @@ import { HandlerRegistryStore } from "../handlerRegistry/handlerRegistryStore.js
  */
 export declare class DefaultDispatcher implements Dispatcher {
     private readonly registry;
+    /**
+     * Registered global middleware, in registration order.
+     *
+     * Held as {@link RegisteredMessageMiddleware} rather than bare functions:
+     * without an identity, `removeMiddleware` had nothing to match on and
+     * unconditionally returned false, and the `priority` the interface accepts
+     * had nowhere to live.
+     */
     private readonly globalMiddleware;
+    private middlewareSequence;
     private disposed;
     constructor(registry?: HandlerRegistryStore);
     dispatch<TPayload, TResult>(message: Message<TPayload>, options?: DispatchOptions<TResult>): Promise<DispatchResult<TResult>>;
+    /** A promise that rejects with {@link MessageTimeoutError} and aborts. */
+    private timeoutRejection;
+    /** Global middleware ordered by priority, with disabled entries dropped. */
+    private orderedMiddleware;
     private validateNotDisposed;
+    /**
+     * Resolves the signal handlers observe.
+     *
+     * The dispatcher's own controller is chained to the caller's signal so a
+     * timeout can abort the work without the caller losing its own cancellation.
+     */
     private resolveSignal;
     private executeHandlers;
     private executeHandler;
-    use<TMessage extends Message = Message, TResult = unknown>(middleware: MessageMiddlewareLike<TMessage, TResult>): void;
-    removeMiddleware(_middlewareId: string): boolean;
+    /**
+     * Registers global middleware.
+     *
+     * @param middleware - The middleware to register.
+     * @param options - Identity, priority and enablement.
+     * @returns The identifier {@link DefaultDispatcher.removeMiddleware} takes.
+     * @throws {MessageMiddlewareError} when the requested id is already taken.
+     */
+    use<TMessage extends Message = Message, TResult = unknown>(middleware: MessageMiddlewareLike<TMessage, TResult>, options?: MessageMiddlewareOptions): string;
+    /**
+     * Removes previously registered global middleware.
+     *
+     * @param middlewareId - The id returned by {@link DefaultDispatcher.use}.
+     * @returns Whether a registration was removed.
+     */
+    removeMiddleware(middlewareId: string): boolean;
+    /** The ids of every registered global middleware, in priority order. */
+    listMiddleware(): readonly string[];
     getRegistry(): HandlerRegistryStore;
     dispose(): void;
 }

package/dist/dispatcher/dispatcherCore.js

@@ -6,13 +6,24 @@
 import { createMessageContext } from "../messageContext/messageContextType.type.js";
 import { HandlerRegistryStore } from "../handlerRegistry/handlerRegistryStore.js";
 import { runMessagePipeline } from "../messageMiddleware/messageMiddlewarePipeline.js";
-import { MessageDispatchAbortedError, MessageHandlerError, MessageDispatchError, } from "@zudojs/errors";
+import { MessageDispatchAbortedError, MessageHandlerError, MessageMiddlewareError, MessageTimeoutError, MessageBusDisposedError, } from "@zudojs/errors";
+/** Default priority for middleware that does not declare one. */
+const DEFAULT_MIDDLEWARE_PRIORITY = 100;
 /**
  * Default dispatcher implementation.
  */
 export class DefaultDispatcher {
     registry;
+    /**
+     * Registered global middleware, in registration order.
+     *
+     * Held as {@link RegisteredMessageMiddleware} rather than bare functions:
+     * without an identity, `removeMiddleware` had nothing to match on and
+     * unconditionally returned false, and the `priority` the interface accepts
+     * had nowhere to live.
+     */
     globalMiddleware = [];
+    middlewareSequence = 0;
     disposed = false;
     constructor(registry) {
         this.registry = registry ?? new HandlerRegistryStore();
@@ -20,23 +31,50 @@ export class DefaultDispatcher {
     async dispatch(message, options = {}) {
         const dispatchStart = performance.now();
         this.validateNotDisposed(message);
-        const signal = this.resolveSignal(options.signal);
+        const timeout = options.timeout ?? 0;
+        const controller = new AbortController();
+        const { signal, release } = this.resolveSignal(options.signal, controller);
         const context = createMessageContext(message, {
             ...options.context,
             signal,
         });
+        const ordered = this.orderedMiddleware();
+        const perDispatch = options.middleware ?? [];
         const allMiddleware = [
-            ...this.globalMiddleware,
-            ...(options.middleware ?? []),
+            ...ordered.map((entry) => entry.middleware),
+            ...perDispatch,
+        ];
+        const middlewareIds = [
+            ...ordered.map((entry) => entry.id),
+            ...perDispatch.map((_mw, index) => `dispatch:${index}`),
         ];
         const handlers = this.registry.resolve(message.type);
         const handlerResults = [];
+        let timer;
         try {
-            const pipelineResult = await runMessagePipeline(allMiddleware, async (msg, mwCtx) => this.executeHandlers(msg, handlers, handlerResults, mwCtx.signal), message, {
+            const run = runMessagePipeline(allMiddleware, 
+            // Handlers receive the same context the middleware saw: the one
+            // built from `DispatchOptions.context` (headers, state, correlation
+            // overrides) plus anything a middleware put into `state`. A fresh
+            // context per handler used to drop all of that on the floor.
+            async (msg, mwCtx) => this.executeHandlers(msg, handlers, handlerResults, mwCtx.context), message, {
                 signal: context.signal,
-                metadata: options.context?.headers,
-                state: options.context?.state,
+                metadata: context.headers,
+                state: context.state,
+                middlewareIds,
+                context,
             });
+            // `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;
             return {
                 success: true,
                 value: pipelineResult.result,
@@ -57,36 +95,101 @@ export class DefaultDispatcher {
                 duration: performance.now() - dispatchStart,
             };
         }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            // Detach from the caller's signal, otherwise a long-lived signal
+            // shared across dispatches accumulates one listener per dispatch.
+            release();
+        }
+    }
+    /** A promise that rejects with {@link MessageTimeoutError} and aborts. */
+    timeoutRejection(message, timeout, controller, keepTimer) {
+        return new Promise((_resolve, reject) => {
+            const timer = setTimeout(() => {
+                const error = new MessageTimeoutError(timeout, {
+                    messageType: message.type,
+                    messageId: message.id,
+                });
+                // Abort first so a handler watching its signal can wind down rather
+                // than running on past the dispatch that gave up on it.
+                controller.abort(error);
+                reject(error);
+            }, timeout);
+            if (timer.unref)
+                timer.unref();
+            keepTimer(timer);
+        });
+    }
+    /** Global middleware ordered by priority, with disabled entries dropped. */
+    orderedMiddleware() {
+        return this.globalMiddleware
+            .filter((entry) => entry.enabled)
+            .map((entry, index) => ({ entry, index }))
+            .sort((a, b) => a.entry.priority - b.entry.priority || a.index - b.index)
+            .map(({ entry }) => entry);
     }
-    validateNotDisposed(message) {
+    validateNotDisposed(_message) {
         if (this.disposed)
-            throw new MessageDispatchError(message.type, "Dispatcher has been disposed.");
+            throw new MessageBusDisposedError();
     }
-    resolveSignal(signal) {
-        const resolved = signal ?? new AbortController().signal;
-        if (resolved.aborted)
+    /**
+     * Resolves the signal handlers observe.
+     *
+     * The dispatcher's own controller is chained to the caller's signal so a
+     * timeout can abort the work without the caller losing its own cancellation.
+     */
+    resolveSignal(signal, controller) {
+        if (signal?.aborted)
             throw new MessageDispatchAbortedError();
-        return resolved;
+        if (!signal) {
+            return { signal: controller.signal, release: () => { } };
+        }
+        const onAbort = () => controller.abort(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        return {
+            signal: controller.signal,
+            release: () => signal.removeEventListener("abort", onAbort),
+        };
     }
-    async executeHandlers(message, handlers, handlerResults, signal) {
+    async executeHandlers(message, handlers, handlerResults, context) {
         const results = [];
         for (const handler of handlers) {
-            const result = await this.executeHandler(handler, message, signal);
-            results.push(result);
-            handlerResults.push({
-                handlerId: handler.id,
-                success: true,
-                value: result,
-                duration: 0,
-            });
+            // A dispatch cancelled between handlers is reported as an abort, not
+            // as a failure of the handler that never got to run.
+            if (context.signal.aborted) {
+                throw new MessageDispatchAbortedError(undefined, {
+                    messageType: message.type,
+                    messageId: message.id,
+                });
+            }
+            const start = performance.now();
+            try {
+                const result = await this.executeHandler(handler, message, context);
+                results.push(result);
+                handlerResults.push({
+                    handlerId: handler.id,
+                    success: true,
+                    value: result,
+                    duration: performance.now() - start,
+                });
+            }
+            catch (error) {
+                // A failing handler used to leave no trace at all in handlerResults,
+                // so a caller inspecting them could not tell which handler broke.
+                handlerResults.push({
+                    handlerId: handler.id,
+                    success: false,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    duration: performance.now() - start,
+                });
+                throw error;
+            }
         }
         return results.length === 1 ? results[0] : results;
     }
-    async executeHandler(handler, message, signal) {
+    async executeHandler(handler, message, context) {
         try {
-            if (signal.aborted)
-                throw new MessageDispatchAbortedError();
-            const context = createMessageContext(message, { signal });
             return await handler.handler(message, context);
         }
         catch (error) {
@@ -98,17 +201,57 @@ export class DefaultDispatcher {
             });
         }
     }
-    use(middleware) {
-        this.globalMiddleware.push(middleware);
+    /**
+     * Registers global middleware.
+     *
+     * @param middleware - The middleware to register.
+     * @param options - Identity, priority and enablement.
+     * @returns The identifier {@link DefaultDispatcher.removeMiddleware} takes.
+     * @throws {MessageMiddlewareError} when the requested id is already taken.
+     */
+    use(middleware, options = {}) {
+        const id = options.id ?? `middleware:${++this.middlewareSequence}`;
+        if (this.globalMiddleware.some((entry) => entry.id === id)) {
+            throw new MessageMiddlewareError(`Middleware "${id}" is already registered.`, { middlewareId: id });
+        }
+        const entry = {
+            id,
+            priority: options.priority ?? DEFAULT_MIDDLEWARE_PRIORITY,
+            enabled: options.enabled ?? true,
+            middleware: middleware,
+            ...(options.description !== undefined
+                ? { description: options.description }
+                : {}),
+        };
+        this.globalMiddleware.push(entry);
+        return id;
+    }
+    /**
+     * Removes previously registered global middleware.
+     *
+     * @param middlewareId - The id returned by {@link DefaultDispatcher.use}.
+     * @returns Whether a registration was removed.
+     */
+    removeMiddleware(middlewareId) {
+        const index = this.globalMiddleware.findIndex((entry) => entry.id === middlewareId);
+        if (index === -1)
+            return false;
+        this.globalMiddleware.splice(index, 1);
+        return true;
     }
-    removeMiddleware(_middlewareId) {
-        return false;
+    /** The ids of every registered global middleware, in priority order. */
+    listMiddleware() {
+        return this.globalMiddleware
+            .map((entry, index) => ({ entry, index }))
+            .sort((a, b) => a.entry.priority - b.entry.priority || a.index - b.index)
+            .map(({ entry }) => entry.id);
     }
     getRegistry() {
         return this.registry;
     }
     dispose() {
         this.disposed = true;
+        this.globalMiddleware.length = 0;
     }
 }
 export function createDispatcher(registry) {

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

@@ -8,7 +8,7 @@
  */
 import type { Message } from "../message/messageType.type.js";
 import type { MessageContext, MessageContextOptions } from "../messageContext/messageContextType.type.js";
-import type { MessageMiddlewareLike, MessageMiddlewarePipelineResult } from "../messageMiddleware/messageMiddlewareType.type.js";
+import type { MessageMiddlewareLike, MessageMiddlewareOptions, MessageMiddlewarePipelineResult } from "../messageMiddleware/messageMiddlewareType.type.js";
 /**
  * Result of dispatching a message.
  */
@@ -53,7 +53,12 @@ export interface DispatchOptions<TResult = unknown> {
     readonly context?: MessageContextOptions;
     /** Middleware to apply for this dispatch. */
     readonly middleware?: readonly MessageMiddlewareLike[];
-    /** Timeout in ms. 0 = no timeout. Default: 0. */
+    /**
+     * Timeout in ms. 0 = no timeout. Default: 0.
+     *
+     * On expiry the dispatch is aborted through `context.signal` and the result
+     * carries a `MessageTimeoutError`.
+     */
     readonly timeout?: number;
     /** AbortSignal for cancellation. */
     readonly signal?: AbortSignal;
@@ -71,12 +76,18 @@ export interface Dispatcher {
     dispatch<TPayload, TResult>(message: Message<TPayload>, options?: DispatchOptions<TResult>): Promise<DispatchResult<TResult>>;
     /**
      * Registers middleware for all dispatches.
+     *
+     * Middleware runs in ascending `priority` order (default 100), registration
+     * order breaking ties.
+     *
+     * @returns The identifier {@link Dispatcher.removeMiddleware} takes, which
+     *   is `options.id` when one was supplied.
      */
-    use<TMessage extends Message = Message, TResult = unknown>(middleware: MessageMiddlewareLike<TMessage, TResult>, options?: {
-        priority?: number;
-    }): void;
+    use<TMessage extends Message = Message, TResult = unknown>(middleware: MessageMiddlewareLike<TMessage, TResult>, options?: MessageMiddlewareOptions): string;
     /**
      * Removes middleware by ID.
+     *
+     * @returns Whether a registration was removed.
      */
     removeMiddleware(middlewareId: string): boolean;
 }

package/dist/handlerRegistry/handlerRegistryStore.d.ts

@@ -16,6 +16,16 @@ export declare class HandlerRegistryStore {
     constructor(options?: HandlerRegistryOptions);
     register<TMessage extends Message, TResult>(handler: NamedMessageHandler<TMessage, TResult>): void;
     private validateNotDuplicate;
+    /**
+     * Rejects a second handler for a type when the registry is single-handler.
+     *
+     * `allowMultipleHandlers` was stored and never read, so a registry created
+     * with `allowMultipleHandlers: false` silently fanned a command out to
+     * every handler that had claimed its type.
+     *
+     * @throws {MessageError} when the type already has a handler.
+     */
+    private validateSingleHandlerPerType;
     private indexHandlerTypes;
     unregister(handlerId: string): boolean;
     private removeHandlerFromTypeIndex;

package/dist/handlerRegistry/handlerRegistryStore.js

@@ -3,7 +3,7 @@
  *
  * @module handlerRegistry/handlerRegistryStore
  */
-import { DuplicateMessageHandlerError } from "@zudojs/errors";
+import { createMessageError, DuplicateMessageHandlerError, ErrorCode, } from "@zudojs/errors";
 /**
  * In-memory store for registered message handlers.
  */
@@ -15,12 +15,24 @@ export class HandlerRegistryStore {
         this.options = {
             allowDuplicateHandlerIds: false,
             allowMultipleHandlers: true,
-            requireTypeRegistration: false,
             ...options,
         };
     }
     register(handler) {
         this.validateNotDuplicate(handler.id);
+        // Replacing a handler id must drop the old entry from the type index
+        // first, or the replacement keeps receiving the old handler's types.
+        const previous = this.handlers.get(handler.id);
+        if (previous !== undefined)
+            this.removeHandlerFromTypeIndex(previous);
+        try {
+            this.validateSingleHandlerPerType(handler);
+        }
+        catch (error) {
+            if (previous !== undefined)
+                this.indexHandlerTypes(previous.handler);
+            throw error;
+        }
         const entry = {
             handler,
             registeredAt: new Date(),
@@ -34,6 +46,30 @@ export class HandlerRegistryStore {
             throw new DuplicateMessageHandlerError(handlerId);
         }
     }
+    /**
+     * Rejects a second handler for a type when the registry is single-handler.
+     *
+     * `allowMultipleHandlers` was stored and never read, so a registry created
+     * with `allowMultipleHandlers: false` silently fanned a command out to
+     * every handler that had claimed its type.
+     *
+     * @throws {MessageError} when the type already has a handler.
+     */
+    validateSingleHandlerPerType(handler) {
+        if (this.options.allowMultipleHandlers !== false)
+            return;
+        for (const messageType of handler.messageTypes) {
+            const existing = this.handlersByType.get(messageType);
+            const taken = existing && existing.size > 0 ? [...existing][0] : undefined;
+            if (taken !== undefined) {
+                throw createMessageError(`Message type "${messageType}" already has handler "${taken}" and the registry does not allow multiple handlers.`, {
+                    code: ErrorCode.CONFLICT,
+                    messageType,
+                    handlerId: handler.id,
+                });
+            }
+        }
+    }
     indexHandlerTypes(handler) {
         for (const messageType of handler.messageTypes) {
             let typeSet = this.handlersByType.get(messageType);

package/dist/handlerRegistry/handlerRegistryType.type.d.ts

@@ -15,10 +15,13 @@ import type { Message } from "../message/messageType.type.js";
 export interface HandlerRegistryOptions {
     /** Allow duplicate handler IDs. Default: false. */
     readonly allowDuplicateHandlerIds?: boolean;
-    /** Allow multiple handlers per message type. Default: true. */
+    /**
+     * Allow multiple handlers per message type. Default: true.
+     *
+     * Set false for a command/query registry, where a second handler for the
+     * same type is a wiring mistake rather than a fan-out.
+     */
     readonly allowMultipleHandlers?: boolean;
-    /** Require message type registration before handler. Default: false. */
-    readonly requireTypeRegistration?: boolean;
 }
 /**
  * Registered handler entry.

package/dist/message/index.d.ts

@@ -4,5 +4,5 @@
  * Core message types, factory functions, and identity primitives.
  */
 export type { MessageId, MessageType, MessageTimestamp, MessageSource, MessageCorrelationId, MessageCausationId, MessagePayload, Message, MessageInput, } from "./messageType.type.js";
-export { createMessageId, createMessage, createDerivedMessage, isMessage, getMessageType, getMessagePayload, describeMessage, } from "./messageFactory.js";
+export { createMessageId, toMessageId, toCorrelationId, toCausationId, createMessage, createDerivedMessage, isMessage, getMessageType, getMessagePayload, describeMessage, } from "./messageFactory.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/message/index.js

@@ -3,5 +3,5 @@
  *
  * Core message types, factory functions, and identity primitives.
  */
-export { createMessageId, createMessage, createDerivedMessage, isMessage, getMessageType, getMessagePayload, describeMessage, } from "./messageFactory.js";
+export { createMessageId, toMessageId, toCorrelationId, toCausationId, createMessage, createDerivedMessage, isMessage, getMessageType, getMessagePayload, describeMessage, } from "./messageFactory.js";
 //# sourceMappingURL=index.js.map

package/dist/message/messageFactory.d.ts

@@ -3,12 +3,28 @@
  *
  * @module message/messageFactory
  */
-import type { Message, MessageId, MessageType, MessagePayload, MessageInput } from "./messageType.type.js";
+import type { Message, MessageId, MessageCorrelationId, MessageCausationId, MessageType, MessagePayload, MessageInput } from "./messageType.type.js";
 /**
  * Creates a unique message identifier.
  * Returns a branded MessageId type from @zudojs/constants.
  */
 export declare function createMessageId(): MessageId;
+/**
+ * Brands an existing string as a {@link MessageId}.
+ *
+ * Identifiers arriving from outside the process — a transport frame, a
+ * database row, a log record — are plain strings. This is the supported way
+ * to restore the branded type without an unchecked cast.
+ */
+export declare function toMessageId(value: string): MessageId;
+/**
+ * Brands an existing string as a {@link MessageCorrelationId}.
+ */
+export declare function toCorrelationId(value: string): MessageCorrelationId;
+/**
+ * Brands an existing string as a {@link MessageCausationId}.
+ */
+export declare function toCausationId(value: string): MessageCausationId;
 /**
  * Creates an immutable message.
  */