@zudojs/cqrs 1.2.3 → 1.3.0

package/README.md

@@ -67,6 +67,12 @@ const found = await queryBus.execute<GetUser, User | undefined>({
 Class-based handlers extend `CommandHandler` / `QueryHandler`; any object with an
 `execute()` method is accepted as well.
 
+The result type argument on `execute` (`User` above) is a claim the bus cannot
+check: handlers are resolved by the command's `type` string at run time, so
+`execute<CreateUser, string>` compiles whatever the handler returns, and with no
+type arguments the result is `void`. Keep the claim beside the handler's declared
+result type, or wrap the bus in a typed facade for your command set.
+
 ```typescript
 import { CommandHandler, createCommandBus } from "@zudojs/cqrs";
 
@@ -140,7 +146,7 @@ try {
 - Query bus for read operations
 - Middleware pipeline for both (timing, error normalisation, validation, locking, context enrichment)
 - Function, object and class-based handlers
-- Class decorators (`CommandHandlerFor`, `QueryHandlerFor`, `CqrsHandler`) for handler discovery
+- Class decorators (`CommandHandlerFor`, `QueryHandlerFor`, `CqrsHandler`) that mark handler classes; the buses never read the mark, so register decorated instances with `registerDecoratedHandlers(bus, [new Handler()])` or read them with `collectDecoratedHandlers`
 - Dedicated error classes (`isCqrsError`)
 - Result types for explicit returns
 - Execution contexts with correlation chains

package/dist/command/command.core.d.ts

@@ -29,7 +29,7 @@ export declare abstract class MetadataCommand<TType extends string = string> ext
  * The `type` argument always wins over any `type` key present in the
  * payload, so untrusted payloads cannot reroute the command.
  */
-export declare function createCommand<TType extends string, TPayload extends Record<string, unknown> = Record<never, never>>(type: TType, payload?: TPayload): Readonly<{
+export declare function createCommand<TType extends string, TPayload extends object = Record<never, never>>(type: TType, payload?: TPayload): Readonly<{
     readonly type: TType;
 } & Omit<TPayload, "type">>;
 /**
@@ -47,4 +47,3 @@ export declare function isCommand(value: unknown): value is CommandContract;
  * keeping their discriminator values consistent.
  */
 export declare function commandType<TType extends string>(type: TType): () => TType;
-//# sourceMappingURL=command.core.d.ts.map

package/dist/command/command.core.js

@@ -59,4 +59,3 @@ export function isCommand(value) {
 export function commandType(type) {
     return () => type;
 }
-//# sourceMappingURL=command.core.js.map

package/dist/command/commandBus.core.d.ts

@@ -102,4 +102,3 @@ export declare class CommandBus implements CommandBusContract {
  * Creates a command bus.
  */
 export declare function createCommandBus(options?: CommandBusOptions): CommandBus;
-//# sourceMappingURL=commandBus.core.d.ts.map

package/dist/command/commandBus.core.js

@@ -159,4 +159,3 @@ export class CommandBus {
 export function createCommandBus(options = {}) {
     return new CommandBus(options);
 }
-//# sourceMappingURL=commandBus.core.js.map

package/dist/command/commandHandler.core.d.ts

@@ -46,4 +46,3 @@ export declare function isCommandHandlerLike(value: unknown): value is CommandHa
  * extend the abstract `CommandHandler` class.
  */
 export declare function executeCommandHandler<TCommand extends Command, TResult = void>(handler: CommandHandlerLike<TCommand, TResult>, command: TCommand, context?: CqrsContext): Promise<TResult>;
-//# sourceMappingURL=commandHandler.core.d.ts.map

package/dist/command/commandHandler.core.js

@@ -71,4 +71,3 @@ export async function executeCommandHandler(handler, command, context) {
         handlerType: command.type,
     });
 }
-//# sourceMappingURL=commandHandler.core.js.map

package/dist/command/commandResult.type.d.ts

@@ -58,4 +58,3 @@ export declare function unwrapCommandResult<TResult, TCommand extends Command =
  * Adds execution metadata to an existing command result.
  */
 export declare function withCommandResultMetadata<TResult, TCommand extends Command = Command>(result: CommandResult<TResult, TCommand>, metadata: Readonly<Record<string, unknown>>): CommandResult<TResult, TCommand>;
-//# sourceMappingURL=commandResult.type.d.ts.map

package/dist/command/commandResult.type.js

@@ -91,4 +91,3 @@ function validateCommand(command) {
         throw new TypeError("Command type is required to create a command result.");
     }
 }
-//# sourceMappingURL=commandResult.type.js.map

package/dist/command/index.d.ts

@@ -7,4 +7,3 @@ export * from "./command.core.js";
 export * from "./commandHandler.core.js";
 export * from "./commandBus.core.js";
 export * from "./commandResult.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/command/index.js

@@ -7,4 +7,3 @@ export * from "./command.core.js";
 export * from "./commandHandler.core.js";
 export * from "./commandBus.core.js";
 export * from "./commandResult.type.js";
-//# sourceMappingURL=index.js.map

package/dist/cqrsContext/cqrsContext.core.d.ts

@@ -105,4 +105,3 @@ export declare function sharesCorrelation(first?: CqrsExecutionContext, second?:
  * Converts an execution context into a plain serializable object.
  */
 export declare function serializeExecutionContext(context: CqrsExecutionContext): Record<string, unknown>;
-//# sourceMappingURL=cqrsContext.core.d.ts.map

package/dist/cqrsContext/cqrsContext.core.js

@@ -186,4 +186,3 @@ export function serializeExecutionContext(context) {
             : undefined,
     };
 }
-//# sourceMappingURL=cqrsContext.core.js.map

package/dist/cqrsContext/index.d.ts

@@ -4,4 +4,3 @@
  * CQRS execution context creation and manipulation utilities.
  */
 export * from "./cqrsContext.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cqrsContext/index.js

@@ -4,4 +4,3 @@
  * CQRS execution context creation and manipulation utilities.
  */
 export * from "./cqrsContext.core.js";
-//# sourceMappingURL=index.js.map

package/dist/cqrsDecorators/cqrsDecorators.core.d.ts

@@ -65,15 +65,22 @@ export declare function CqrsHandler<TType extends string>(kind: CqrsHandlerKind,
  *
  * Named `CommandHandlerFor` so it does not collide with the abstract
  * `CommandHandler` class exported from the same package.
+ *
+ * The mark is metadata only: no bus reads it. Registration is explicit —
+ * `commandBus.register(type, new Handler())` — or driven from the mark
+ * with `registerDecoratedHandlers`. The decorator is typed as a legacy
+ * `ClassDecorator` and also works as a standard (TC39) class decorator,
+ * whose second argument it ignores.
  */
-export declare function CommandHandlerFor(type: string): ClassDecorator;
+export declare function CommandHandlerFor<TType extends string>(type: TType): ClassDecorator;
 /**
  * Marks a class as the query handler for `type`.
  *
  * Named `QueryHandlerFor` so it does not collide with the abstract
- * `QueryHandler` class exported from the same package.
+ * `QueryHandler` class exported from the same package. See
+ * {@link CommandHandlerFor} for how the mark is consumed.
  */
-export declare function QueryHandlerFor(type: string): ClassDecorator;
+export declare function QueryHandlerFor<TType extends string>(type: TType): ClassDecorator;
 /**
  * Reads generic CQRS handler metadata from a class.
  */
@@ -105,10 +112,9 @@ export declare function isDecoratedQueryHandler(target: unknown): boolean;
 /**
  * Creates a reusable command handler decorator.
  */
-export declare function createCommandHandlerDecorator(type: string): ClassDecorator;
+export declare function createCommandHandlerDecorator<TType extends string>(type: TType): ClassDecorator;
 /**
  * Creates a reusable query handler decorator.
  */
-export declare function createQueryHandlerDecorator(type: string): ClassDecorator;
+export declare function createQueryHandlerDecorator<TType extends string>(type: TType): ClassDecorator;
 export {};
-//# sourceMappingURL=cqrsDecorators.core.d.ts.map

package/dist/cqrsDecorators/cqrsDecorators.core.js

@@ -39,6 +39,12 @@ export function CqrsHandler(kind, type) {
  *
  * Named `CommandHandlerFor` so it does not collide with the abstract
  * `CommandHandler` class exported from the same package.
+ *
+ * The mark is metadata only: no bus reads it. Registration is explicit —
+ * `commandBus.register(type, new Handler())` — or driven from the mark
+ * with `registerDecoratedHandlers`. The decorator is typed as a legacy
+ * `ClassDecorator` and also works as a standard (TC39) class decorator,
+ * whose second argument it ignores.
  */
 export function CommandHandlerFor(type) {
     validateHandlerMetadata("command", type);
@@ -57,7 +63,8 @@ export function CommandHandlerFor(type) {
  * Marks a class as the query handler for `type`.
  *
  * Named `QueryHandlerFor` so it does not collide with the abstract
- * `QueryHandler` class exported from the same package.
+ * `QueryHandler` class exported from the same package. See
+ * {@link CommandHandlerFor} for how the mark is consumed.
  */
 export function QueryHandlerFor(type) {
     validateHandlerMetadata("query", type);
@@ -73,40 +80,45 @@ export function QueryHandlerFor(type) {
     };
 }
 /**
- * Reads generic CQRS handler metadata from a class.
+ * Reads metadata the class itself was decorated with.
+ *
+ * Only own metadata counts. A subclass of a decorated handler used to
+ * inherit the parent's mark through the prototype chain, so discovery
+ * reported both classes as the handler for the same type and registered
+ * the type twice; a subclass is a handler only when it is decorated itself.
  */
-export function getCqrsHandlerMetadata(target) {
+function ownMetadata(target, key) {
     if (typeof target !== "function") {
         return undefined;
     }
-    return target[CQRS_HANDLER_METADATA] ?? undefined;
+    if (!Object.prototype.hasOwnProperty.call(target, key)) {
+        return undefined;
+    }
+    return target[key];
+}
+/**
+ * Reads generic CQRS handler metadata from a class.
+ */
+export function getCqrsHandlerMetadata(target) {
+    return ownMetadata(target, CQRS_HANDLER_METADATA);
 }
 /**
  * Reads command handler metadata from a class.
  */
 export function getCommandHandlerMetadata(target) {
-    if (typeof target !== "function") {
-        return undefined;
-    }
-    return target[COMMAND_HANDLER_METADATA] ?? undefined;
+    return ownMetadata(target, COMMAND_HANDLER_METADATA);
 }
 /**
  * Reads query handler metadata from a class.
  */
 export function getQueryHandlerMetadata(target) {
-    if (typeof target !== "function") {
-        return undefined;
-    }
-    return target[QUERY_HANDLER_METADATA] ?? undefined;
+    return ownMetadata(target, QUERY_HANDLER_METADATA);
 }
 /**
  * Reads the CQRS type discriminator from a class.
  */
 export function getCqrsType(target) {
-    if (typeof target !== "function") {
-        return undefined;
-    }
-    return target[CQRS_TYPE_METADATA] ?? undefined;
+    return ownMetadata(target, CQRS_TYPE_METADATA);
 }
 /**
  * Determines whether a class is decorated as a CQRS handler.
@@ -197,4 +209,3 @@ function describeMetadata(value) {
     }
     return String(value);
 }
-//# sourceMappingURL=cqrsDecorators.core.js.map

package/dist/cqrsDecorators/cqrsDecorators.discovery.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Turning decorated handler instances into registrations.
+ *
+ * `CommandHandlerFor` / `QueryHandlerFor` only mark a class; no bus reads
+ * the mark. These helpers close the loop: given handler instances, they
+ * read the mark off each instance's class and register it, so the type a
+ * handler is decorated with is the type it is registered under.
+ *
+ * @module cqrsDecorators/discovery
+ */
+import type { CommandHandlerLike, QueryHandlerLike } from "../cqrsTypes/cqrsTypes.type.js";
+import type { HandlerEntry } from "../handlerRegistry/handlerRegistry.core.js";
+/**
+ * Where decorated handlers are registered: a `HandlerRegistry` (anything
+ * with `register(entry)`), or the command and query buses themselves.
+ */
+export type DecoratedHandlerTarget = {
+    register(entry: HandlerEntry): unknown;
+} | {
+    readonly commandBus?: {
+        register(type: string, handler: CommandHandlerLike): unknown;
+    };
+    readonly queryBus?: {
+        register(type: string, handler: QueryHandlerLike): unknown;
+    };
+};
+/**
+ * Reads the registrations a set of decorated handler instances stand for.
+ *
+ * @throws HandlerConfigurationError for an instance whose class carries no
+ *   CQRS mark, so a handler that lost its decorator does not vanish quietly.
+ */
+export declare function collectDecoratedHandlers(handlers: readonly object[]): readonly HandlerEntry[];
+/**
+ * Registers decorated handler instances on a registry or on buses.
+ *
+ * Each instance is registered under the type its class was decorated
+ * with. Duplicate and malformed registrations fail exactly as a direct
+ * `register` call would.
+ *
+ * @example
+ * ```ts
+ * @CommandHandlerFor("PlaceOrder")
+ * class PlaceOrderHandler { execute(command: PlaceOrder) { ... } }
+ *
+ * registerDecoratedHandlers({ commandBus, queryBus }, [new PlaceOrderHandler()]);
+ * ```
+ */
+export declare function registerDecoratedHandlers(target: DecoratedHandlerTarget, handlers: readonly object[]): readonly HandlerEntry[];

package/dist/cqrsDecorators/cqrsDecorators.discovery.js

@@ -0,0 +1,75 @@
+/**
+ * Turning decorated handler instances into registrations.
+ *
+ * `CommandHandlerFor` / `QueryHandlerFor` only mark a class; no bus reads
+ * the mark. These helpers close the loop: given handler instances, they
+ * read the mark off each instance's class and register it, so the type a
+ * handler is decorated with is the type it is registered under.
+ *
+ * @module cqrsDecorators/discovery
+ */
+import { HandlerConfigurationError } from "../cqrsErrors/cqrsError.base.js";
+import { getCqrsHandlerMetadata } from "./cqrsDecorators.core.js";
+/**
+ * Reads the registrations a set of decorated handler instances stand for.
+ *
+ * @throws HandlerConfigurationError for an instance whose class carries no
+ *   CQRS mark, so a handler that lost its decorator does not vanish quietly.
+ */
+export function collectDecoratedHandlers(handlers) {
+    return handlers.map((handler) => {
+        const constructor = handler
+            .constructor;
+        const metadata = getCqrsHandlerMetadata(constructor);
+        if (metadata === undefined) {
+            const name = typeof constructor === "function" && constructor.name
+                ? constructor.name
+                : "<anonymous>";
+            throw new HandlerConfigurationError(`Class "${name}" is not decorated with CommandHandlerFor, QueryHandlerFor or CqrsHandler.`, { className: name });
+        }
+        return metadata.kind === "command"
+            ? {
+                kind: "command",
+                type: metadata.type,
+                handler: handler,
+            }
+            : { kind: "query", type: metadata.type, handler: handler };
+    });
+}
+/**
+ * Registers decorated handler instances on a registry or on buses.
+ *
+ * Each instance is registered under the type its class was decorated
+ * with. Duplicate and malformed registrations fail exactly as a direct
+ * `register` call would.
+ *
+ * @example
+ * ```ts
+ * @CommandHandlerFor("PlaceOrder")
+ * class PlaceOrderHandler { execute(command: PlaceOrder) { ... } }
+ *
+ * registerDecoratedHandlers({ commandBus, queryBus }, [new PlaceOrderHandler()]);
+ * ```
+ */
+export function registerDecoratedHandlers(target, handlers) {
+    const entries = collectDecoratedHandlers(handlers);
+    for (const entry of entries) {
+        if ("register" in target) {
+            target.register(entry);
+            continue;
+        }
+        const bus = entry.kind === "command" ? target.commandBus : target.queryBus;
+        if (bus === undefined) {
+            throw new HandlerConfigurationError(`No ${entry.kind} bus was supplied for handler type "${entry.type}".`, { kind: entry.kind, type: entry.type });
+        }
+        if (entry.kind === "command") {
+            bus
+                .register(entry.type, entry.handler);
+        }
+        else {
+            bus
+                .register(entry.type, entry.handler);
+        }
+    }
+    return entries;
+}

package/dist/cqrsDecorators/index.d.ts

@@ -4,4 +4,4 @@
  * TypeScript decorators for CQRS handler metadata.
  */
 export * from "./cqrsDecorators.core.js";
-//# sourceMappingURL=index.d.ts.map
+export * from "./cqrsDecorators.discovery.js";

package/dist/cqrsDecorators/index.js

@@ -4,4 +4,4 @@
  * TypeScript decorators for CQRS handler metadata.
  */
 export * from "./cqrsDecorators.core.js";
-//# sourceMappingURL=index.js.map
+export * from "./cqrsDecorators.discovery.js";

package/dist/cqrsErrors/cqrsError.base.d.ts

@@ -112,12 +112,13 @@ export declare function isCqrsError(error: unknown): error is CqrsError;
  * Converts an unknown error into a CQRS error.
  *
  * - `CqrsError` instances are returned unchanged.
- * - Other `BaseError` instances keep their code, status, category,
- *   severity, exposure and operational flags (and metadata).
+ * - Other `BaseError` instances — recognised with `isBaseError`, so a
+ *   `BaseError` from a second copy of `@zudojs/errors` counts — keep their
+ *   code, status, category, severity, exposure and operational flags (and
+ *   metadata).
  * - Plain `Error` instances become a non-operational 500 `CqrsError`
  *   using the original message.
  * - Anything else becomes a non-operational 500 `CqrsError` using the
  *   supplied `message`; the original value is attached as `cause`.
  */
 export declare function toCqrsError(error: unknown, message?: string): CqrsError;
-//# sourceMappingURL=cqrsError.base.d.ts.map

package/dist/cqrsErrors/cqrsError.base.js

@@ -1,4 +1,4 @@
-import { BaseError, CqrsError, ErrorCategory, ErrorCode, ErrorSeverity, } from "@zudojs/errors";
+import { CqrsError, ErrorCategory, ErrorCode, ErrorSeverity, isBaseError, } from "@zudojs/errors";
 /**
  * Base error for failures originating from the CQRS package.
  *
@@ -234,8 +234,10 @@ export function isCqrsError(error) {
  * Converts an unknown error into a CQRS error.
  *
  * - `CqrsError` instances are returned unchanged.
- * - Other `BaseError` instances keep their code, status, category,
- *   severity, exposure and operational flags (and metadata).
+ * - Other `BaseError` instances — recognised with `isBaseError`, so a
+ *   `BaseError` from a second copy of `@zudojs/errors` counts — keep their
+ *   code, status, category, severity, exposure and operational flags (and
+ *   metadata).
  * - Plain `Error` instances become a non-operational 500 `CqrsError`
  *   using the original message.
  * - Anything else becomes a non-operational 500 `CqrsError` using the
@@ -245,7 +247,7 @@ export function toCqrsError(error, message = "CQRS execution failed.") {
     if (error instanceof CqrsError) {
         return error;
     }
-    if (error instanceof BaseError) {
+    if (isBaseError(error)) {
         return new CqrsError(error.message, {
             code: error.code,
             category: error.category,
@@ -267,4 +269,3 @@ export function toCqrsError(error, message = "CQRS execution failed.") {
         cause: error,
     });
 }
-//# sourceMappingURL=cqrsError.base.js.map

package/dist/cqrsErrors/index.d.ts

@@ -4,4 +4,3 @@
  * CQRS-specific error types extending BaseError.
  */
 export * from "./cqrsError.base.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cqrsErrors/index.js

@@ -4,4 +4,3 @@
  * CQRS-specific error types extending BaseError.
  */
 export * from "./cqrsError.base.js";
-//# sourceMappingURL=index.js.map

package/dist/cqrsEvents/cqrsEventBus.core.d.ts

@@ -6,4 +6,3 @@
  * middleware, registry, and emitter infrastructure.
  */
 export { EventBus, type EventBusOptions, type EventPublishResult, createEventBus, createStartedEventBus, type PublishOptions, EventBusState, type EventBusEvent, type EventBusListener, } from "@zudojs/events";
-//# sourceMappingURL=cqrsEventBus.core.d.ts.map

package/dist/cqrsEvents/cqrsEventBus.core.js

@@ -6,4 +6,3 @@
  * middleware, registry, and emitter infrastructure.
  */
 export { EventBus, createEventBus, createStartedEventBus, EventBusState, } from "@zudojs/events";
-//# sourceMappingURL=cqrsEventBus.core.js.map

package/dist/cqrsEvents/cqrsEventResult.type.d.ts

@@ -78,4 +78,3 @@ export declare function getEventErrors<TEvent extends Event>(result: EventResult
  * Adds metadata to an event result.
  */
 export declare function withEventResultMetadata<TEvent extends Event>(result: EventResult<TEvent>, metadata: Readonly<Record<string, unknown>>): EventResult<TEvent>;
-//# sourceMappingURL=cqrsEventResult.type.d.ts.map

package/dist/cqrsEvents/cqrsEventResult.type.js

@@ -156,4 +156,3 @@ function validateEvent(event) {
         throw new TypeError("Event ID is required.");
     }
 }
-//# sourceMappingURL=cqrsEventResult.type.js.map

package/dist/cqrsEvents/cqrsEvents.type.d.ts

@@ -16,7 +16,7 @@ export interface CqrsEventExtensions {
  * Extends the base Zudojs Event with aggregate identity and
  * versioning fields used in event-sourced aggregates.
  */
-export type CqrsEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = Event<TPayload> & CqrsEventExtensions;
+export type CqrsEvent<TPayload extends object = Record<string, unknown>> = Event<TPayload> & CqrsEventExtensions;
 /**
  * Input used to create a CQRS event.
  *
@@ -26,7 +26,7 @@ export type CqrsEvent<TPayload extends Record<string, unknown> = Record<string,
  * carries the branded `EventId`/`EventCorrelationId` types of the base
  * `Event` contract.
  */
-export interface CreateCqrsEventInput<TPayload extends Record<string, unknown> = Record<string, unknown>> {
+export interface CreateCqrsEventInput<TPayload extends object = Record<string, unknown>> {
     readonly type: EventType;
     readonly payload: TPayload;
     readonly id?: string;
@@ -66,7 +66,7 @@ export declare function createEventId(): EventId;
  *
  * Extends the base Zudojs event with aggregate fields.
  */
-export declare function createCqrsEvent<TPayload extends Record<string, unknown>>(input: CreateCqrsEventInput<TPayload>): CqrsEvent<TPayload>;
+export declare function createCqrsEvent<TPayload extends object>(input: CreateCqrsEventInput<TPayload>): CqrsEvent<TPayload>;
 /**
  * Returns the type discriminator of an event.
  */
@@ -106,4 +106,3 @@ export type EventHandlerRegistration<TEvent extends CqrsEvent = CqrsEvent> = Cqr
  * @deprecated Use createCqrsEventHandler instead.
  */
 export declare const createEventHandler: typeof createCqrsEventHandler;
-//# sourceMappingURL=cqrsEvents.type.d.ts.map

package/dist/cqrsEvents/cqrsEvents.type.js

@@ -110,4 +110,3 @@ export const createEvent = createCqrsEvent;
  * @deprecated Use createCqrsEventHandler instead.
  */
 export const createEventHandler = createCqrsEventHandler;
-//# sourceMappingURL=cqrsEvents.type.js.map

package/dist/cqrsEvents/index.d.ts

@@ -9,4 +9,3 @@
 export { type CqrsEvent, type CqrsEventExtensions, type CreateCqrsEventInput, type CqrsEventHandler, type CqrsEventHandlerRegistration, createEventId, createCqrsEvent, getEventType, getAggregateId, isCqrsEvent, isAggregateEvent, createCqrsEventHandler, createEvent, type EventHandler, type EventHandlerRegistration, createEventHandler, } from "./cqrsEvents.type.js";
 export { EventBus, type EventBusOptions, type EventPublishResult, createEventBus, createStartedEventBus, type PublishOptions, EventBusState, type EventBusEvent, type EventBusListener, } from "./cqrsEventBus.core.js";
 export { type EventResultStatus, type EventResult, type CreateEventResultOptions, createEventResult, createSuccessfulEventResult, createPartialEventResult, createFailedEventResult, isEventPublished, isEventPartiallyPublished, isEventFailed, hasEventHandlerFailures, allEventHandlersSucceeded, getEventErrors, withEventResultMetadata, } from "./cqrsEventResult.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cqrsEvents/index.js

@@ -9,4 +9,3 @@
 export { createEventId, createCqrsEvent, getEventType, getAggregateId, isCqrsEvent, isAggregateEvent, createCqrsEventHandler, createEvent, createEventHandler, } from "./cqrsEvents.type.js";
 export { EventBus, createEventBus, createStartedEventBus, EventBusState, } from "./cqrsEventBus.core.js";
 export { createEventResult, createSuccessfulEventResult, createPartialEventResult, createFailedEventResult, isEventPublished, isEventPartiallyPublished, isEventFailed, hasEventHandlerFailures, allEventHandlersSucceeded, getEventErrors, withEventResultMetadata, } from "./cqrsEventResult.type.js";
-//# sourceMappingURL=index.js.map

package/dist/cqrsMiddleware/cqrsMiddleware.compose.d.ts

@@ -11,4 +11,3 @@ import type { CqrsMiddleware } from "../cqrsTypes/cqrsTypes.type.js";
  * there.
  */
 export declare function composeMiddleware(middleware: readonly CqrsMiddleware[]): CqrsMiddleware;
-//# sourceMappingURL=cqrsMiddleware.compose.d.ts.map

package/dist/cqrsMiddleware/cqrsMiddleware.compose.js

@@ -30,4 +30,3 @@ export function composeMiddleware(middleware) {
     const run = compose(middleware.map(adapt), async (state) => state.terminal(state.request, state.context), { maxDepth: Number.POSITIVE_INFINITY });
     return async (request, context, terminal) => run({ request, context, terminal });
 }
-//# sourceMappingURL=cqrsMiddleware.compose.js.map

package/dist/cqrsMiddleware/cqrsMiddleware.core.d.ts

@@ -93,7 +93,9 @@ export declare function timingMiddleware(options?: TimingMiddlewareOptions): Tim
  * into `CqrsError` instances.
  *
  * `BaseError` instances (including every CQRS error) pass through
- * unchanged.
+ * unchanged. Recognition uses `isBaseError`, which also accepts a
+ * `BaseError` from a second copy of `@zudojs/errors`; an `instanceof`
+ * check wrapped those as a 500 `CqrsError` and lost their code and status.
  */
 export declare function errorMiddleware(options?: MiddlewareOptions): CqrsMiddleware;
 /**
@@ -153,4 +155,3 @@ export declare function afterMiddleware(callback: (request: Command | Query, res
  * Creates a middleware that runs a callback when execution fails.
  */
 export declare function onErrorMiddleware(callback: (request: Command | Query, error: unknown, context?: CqrsContext) => void | Promise<void>): CqrsMiddleware;
-//# sourceMappingURL=cqrsMiddleware.core.d.ts.map

package/dist/cqrsMiddleware/cqrsMiddleware.core.js

@@ -1,4 +1,4 @@
-import { BaseError } from "@zudojs/errors";
+import { isBaseError } from "@zudojs/errors";
 import { CqrsError, CqrsValidationError, InvalidMiddlewareError, } from "../cqrsErrors/cqrsError.base.js";
 /**
  * Middleware that measures command or query execution time.
@@ -84,7 +84,9 @@ export function timingMiddleware(options = {}) {
  * into `CqrsError` instances.
  *
  * `BaseError` instances (including every CQRS error) pass through
- * unchanged.
+ * unchanged. Recognition uses `isBaseError`, which also accepts a
+ * `BaseError` from a second copy of `@zudojs/errors`; an `instanceof`
+ * check wrapped those as a 500 `CqrsError` and lost their code and status.
  */
 export function errorMiddleware(options = {}) {
     return async (request, context, next) => {
@@ -95,7 +97,7 @@ export function errorMiddleware(options = {}) {
             return await next(request, context);
         }
         catch (error) {
-            if (error instanceof BaseError) {
+            if (isBaseError(error)) {
                 throw error;
             }
             throw new CqrsError(error instanceof Error ? error.message : "CQRS execution failed.", {
@@ -262,4 +264,3 @@ function getRequestType(request) {
     const type = request.type;
     return typeof type === "string" ? type : undefined;
 }
-//# sourceMappingURL=cqrsMiddleware.core.js.map

package/dist/cqrsMiddleware/index.d.ts

@@ -6,4 +6,3 @@
  */
 export * from "./cqrsMiddleware.core.js";
 export * from "./cqrsMiddleware.compose.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cqrsMiddleware/index.js

@@ -6,4 +6,3 @@
  */
 export * from "./cqrsMiddleware.core.js";
 export * from "./cqrsMiddleware.compose.js";
-//# sourceMappingURL=index.js.map

package/dist/cqrsTypes/cqrsTypes.type.d.ts

@@ -101,12 +101,21 @@ export interface CqrsBusOptions {
 }
 /**
  * Command bus contract.
+ *
+ * `TResult` on `execute` is a caller-side claim, not something the bus can
+ * verify: handlers are looked up by the command's `type` string at run
+ * time, so `execute<PlaceOrder, string>` compiles whatever the registered
+ * handler returns, and with no type arguments the result is `void`. Keep
+ * the claim next to the handler's declared result (a `CommandHandler<C, R>`
+ * class, or `createCommandHandler<C, R>`) or wrap the bus in a typed
+ * facade for your command set. Middleware (`CqrsMiddleware`) is untyped for
+ * the same reason: it sees every request the bus carries.
  */
 export interface CommandBus {
     execute<TCommand extends Command, TResult = void>(command: TCommand, context?: CqrsContext): Promise<TResult>;
 }
 /**
- * Query bus contract.
+ * Query bus contract. See {@link CommandBus} for what `TResult` guarantees.
  */
 export interface QueryBus {
     execute<TQuery extends Query, TResult = unknown>(query: TQuery, context?: CqrsContext): Promise<TResult>;
@@ -117,9 +126,11 @@ export interface QueryBus {
  * The payload defaults to an empty object (`Record<never, never>`), so
  * `CommandOf<"Ping">` is satisfied by `{ type: "Ping" }`. A `type` key in
  * the payload is dropped: the discriminator always wins, mirroring
- * `createCommand`.
+ * `createCommand`. Any object type is accepted as the payload, an
+ * `interface` included (a `Record<string, unknown>` bound rejected
+ * interfaces with TS2344).
  */
-export type CommandOf<TType extends string, TPayload extends Record<string, unknown> = Record<never, never>> = Readonly<{
+export type CommandOf<TType extends string, TPayload extends object = Record<never, never>> = Readonly<{
     readonly type: TType;
 } & Omit<TPayload, "type">>;
 /**
@@ -127,7 +138,7 @@ export type CommandOf<TType extends string, TPayload extends Record<string, unkn
  *
  * See `CommandOf` for the payload defaulting and `type` precedence rules.
  */
-export type QueryOf<TType extends string, TPayload extends Record<string, unknown> = Record<never, never>> = Readonly<{
+export type QueryOf<TType extends string, TPayload extends object = Record<never, never>> = Readonly<{
     readonly type: TType;
 } & Omit<TPayload, "type">>;
 /**
@@ -142,4 +153,3 @@ export type CqrsPayload<TRequest extends CqrsRequest> = Omit<TRequest, "type">;
  * Determines whether an unknown value satisfies the basic CQRS request shape.
  */
 export declare function isCqrsRequest(value: unknown): value is CqrsRequest;
-//# sourceMappingURL=cqrsTypes.type.d.ts.map

package/dist/cqrsTypes/cqrsTypes.type.js

@@ -15,4 +15,3 @@ export function isCqrsRequest(value) {
         typeof value.type === "string" &&
         value.type.length > 0);
 }
-//# sourceMappingURL=cqrsTypes.type.js.map

package/dist/cqrsTypes/index.d.ts

@@ -4,4 +4,3 @@
  * Core CQRS type definitions: commands, queries, handlers, middleware, and bus contracts.
  */
 export * from "./cqrsTypes.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cqrsTypes/index.js

@@ -4,4 +4,3 @@
  * Core CQRS type definitions: commands, queries, handlers, middleware, and bus contracts.
  */
 export * from "./cqrsTypes.type.js";
-//# sourceMappingURL=index.js.map

package/dist/cqrsValidation/cqrsValidation.core.d.ts

@@ -29,4 +29,3 @@ export declare function assertExecutableHandler(kind: ValidatedHandlerKind, type
  * Asserts that a value is a middleware function.
  */
 export declare function assertMiddleware(kind: ValidatedHandlerKind, middleware: unknown): asserts middleware is (...args: unknown[]) => unknown;
-//# sourceMappingURL=cqrsValidation.core.d.ts.map

package/dist/cqrsValidation/cqrsValidation.core.js

@@ -50,4 +50,3 @@ export function assertMiddleware(kind, middleware) {
         });
     }
 }
-//# sourceMappingURL=cqrsValidation.core.js.map

package/dist/cqrsValidation/index.d.ts

@@ -4,4 +4,3 @@
  * Shared argument validation used by the buses, registry and decorators.
  */
 export * from "./cqrsValidation.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/cqrsValidation/index.js

@@ -4,4 +4,3 @@
  * Shared argument validation used by the buses, registry and decorators.
  */
 export * from "./cqrsValidation.core.js";
-//# sourceMappingURL=index.js.map

package/dist/handlerRegistry/handlerRegistry.core.d.ts

@@ -137,4 +137,3 @@ export declare class HandlerRegistry {
  * Creates a new handler registry.
  */
 export declare function createHandlerRegistry(): HandlerRegistry;
-//# sourceMappingURL=handlerRegistry.core.d.ts.map

package/dist/handlerRegistry/handlerRegistry.core.js

@@ -224,4 +224,3 @@ function assertHandlerKind(kind) {
 export function createHandlerRegistry() {
     return new HandlerRegistry();
 }
-//# sourceMappingURL=handlerRegistry.core.js.map

package/dist/handlerRegistry/index.d.ts

@@ -4,4 +4,3 @@
  * Central registry for command and query handlers.
  */
 export * from "./handlerRegistry.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/handlerRegistry/index.js

@@ -4,4 +4,3 @@
  * Central registry for command and query handlers.
  */
 export * from "./handlerRegistry.core.js";
-//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -11,7 +11,6 @@ export { type Event, type EventInput, type EventDefinition, type EventType, type
 export * from "./cqrsEvents/index.js";
 export * from "./cqrsMiddleware/index.js";
 export * from "./handlerRegistry/index.js";
-export { type CqrsHandlerKind, type CqrsHandlerMetadata, type CommandHandlerMetadata, type QueryHandlerMetadata, type CqrsClass, type DecoratedCqrsClass, CqrsHandler, CommandHandlerFor, QueryHandlerFor, getCqrsHandlerMetadata, getCommandHandlerMetadata, getQueryHandlerMetadata, getCqrsType, isCqrsHandler, isDecoratedCommandHandler, isDecoratedQueryHandler, createCommandHandlerDecorator, createQueryHandlerDecorator, } from "./cqrsDecorators/index.js";
+export { type CqrsHandlerKind, type CqrsHandlerMetadata, type CommandHandlerMetadata, type QueryHandlerMetadata, type CqrsClass, type DecoratedCqrsClass, CqrsHandler, CommandHandlerFor, QueryHandlerFor, getCqrsHandlerMetadata, getCommandHandlerMetadata, getQueryHandlerMetadata, getCqrsType, isCqrsHandler, isDecoratedCommandHandler, isDecoratedQueryHandler, createCommandHandlerDecorator, collectDecoratedHandlers, registerDecoratedHandlers, type DecoratedHandlerTarget, createQueryHandlerDecorator, } from "./cqrsDecorators/index.js";
 export * from "./cqrsContext/index.js";
 export * from "./cqrsErrors/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,9 +22,8 @@ export * from "./cqrsMiddleware/index.js";
 // Handler Registry
 export * from "./handlerRegistry/index.js";
 // Decorators (explicit list: nothing here may shadow the class exports above)
-export { CqrsHandler, CommandHandlerFor, QueryHandlerFor, getCqrsHandlerMetadata, getCommandHandlerMetadata, getQueryHandlerMetadata, getCqrsType, isCqrsHandler, isDecoratedCommandHandler, isDecoratedQueryHandler, createCommandHandlerDecorator, createQueryHandlerDecorator, } from "./cqrsDecorators/index.js";
+export { CqrsHandler, CommandHandlerFor, QueryHandlerFor, getCqrsHandlerMetadata, getCommandHandlerMetadata, getQueryHandlerMetadata, getCqrsType, isCqrsHandler, isDecoratedCommandHandler, isDecoratedQueryHandler, createCommandHandlerDecorator, collectDecoratedHandlers, registerDecoratedHandlers, createQueryHandlerDecorator, } from "./cqrsDecorators/index.js";
 // Execution Context
 export * from "./cqrsContext/index.js";
 // Errors
 export * from "./cqrsErrors/index.js";
-//# sourceMappingURL=index.js.map

package/dist/query/index.d.ts

@@ -7,4 +7,3 @@ export * from "./query.core.js";
 export * from "./queryHandler.core.js";
 export * from "./queryBus.core.js";
 export * from "./queryResult.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/query/index.js

@@ -7,4 +7,3 @@ export * from "./query.core.js";
 export * from "./queryHandler.core.js";
 export * from "./queryBus.core.js";
 export * from "./queryResult.type.js";
-//# sourceMappingURL=index.js.map

package/dist/query/query.core.d.ts

@@ -28,7 +28,7 @@ export declare abstract class MetadataQuery<TType extends string = string> exten
  * The `type` argument always wins over any `type` key present in the
  * payload, so untrusted payloads cannot reroute the query.
  */
-export declare function createQuery<TType extends string, TPayload extends Record<string, unknown> = Record<never, never>>(type: TType, payload?: TPayload): Readonly<{
+export declare function createQuery<TType extends string, TPayload extends object = Record<never, never>>(type: TType, payload?: TPayload): Readonly<{
     readonly type: TType;
 } & Omit<TPayload, "type">>;
 /**
@@ -50,4 +50,3 @@ export declare function isQuery(value: unknown): value is QueryContract;
  * discriminator values consistent.
  */
 export declare function queryType<TType extends string>(type: TType): () => TType;
-//# sourceMappingURL=query.core.d.ts.map

package/dist/query/query.core.js

@@ -62,4 +62,3 @@ export function isQuery(value) {
 export function queryType(type) {
     return () => type;
 }
-//# sourceMappingURL=query.core.js.map

package/dist/query/queryBus.core.d.ts

@@ -102,4 +102,3 @@ export declare class QueryBus implements QueryBusContract {
  * Creates a query bus.
  */
 export declare function createQueryBus(options?: QueryBusOptions): QueryBus;
-//# sourceMappingURL=queryBus.core.d.ts.map

package/dist/query/queryBus.core.js

@@ -159,4 +159,3 @@ export class QueryBus {
 export function createQueryBus(options = {}) {
     return new QueryBus(options);
 }
-//# sourceMappingURL=queryBus.core.js.map

package/dist/query/queryHandler.core.d.ts

@@ -46,4 +46,3 @@ export declare function isQueryHandlerLike(value: unknown): value is QueryHandle
  * extend the abstract `QueryHandler` class.
  */
 export declare function executeQueryHandler<TQuery extends Query, TResult = unknown>(handler: QueryHandlerLike<TQuery, TResult>, query: TQuery, context?: CqrsContext): Promise<TResult>;
-//# sourceMappingURL=queryHandler.core.d.ts.map

package/dist/query/queryHandler.core.js

@@ -71,4 +71,3 @@ export async function executeQueryHandler(handler, query, context) {
         handlerType: query.type,
     });
 }
-//# sourceMappingURL=queryHandler.core.js.map

package/dist/query/queryResult.type.d.ts

@@ -57,4 +57,3 @@ export declare function unwrapQueryResult<TResult, TQuery extends Query = Query>
  * Adds metadata to an existing query result.
  */
 export declare function withQueryResultMetadata<TResult, TQuery extends Query = Query>(result: QueryResult<TResult, TQuery>, metadata: Readonly<Record<string, unknown>>): QueryResult<TResult, TQuery>;
-//# sourceMappingURL=queryResult.type.d.ts.map

package/dist/query/queryResult.type.js

@@ -91,4 +91,3 @@ function validateQuery(query) {
         throw new TypeError("Query type is required to create a query result.");
     }
 }
-//# sourceMappingURL=queryResult.type.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/cqrs",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Command Query Responsibility Segregation (CQRS) primitives for separating read and write operations.",
   "license": "MIT",
   "author": {
@@ -25,9 +25,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.3.2",
-    "@zudojs/events": "1.3.3",
-    "@zudojs/middleware": "1.1.2"
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/events": "1.4.0",
+    "@zudojs/middleware": "1.1.3"
   },
   "devDependencies": {
     "typescript": "7.0.2",