@zudojs/cqrs 0.1.0 → 1.0.0

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

@@ -10,28 +10,109 @@ npm install @zudojs/cqrs
 
 ## Quick Start
 
+Commands and queries are plain objects with a `type` discriminator. Give the
+bus explicit generics (or a typed handler) so the payload and result types
+flow through `register` and `execute`.
+
 ```typescript
-import { createCommandBus, createQueryBus } from "@zudojs/cqrs";
+import {
+  createCommandBus,
+  createQueryBus,
+  createQueryHandler,
+  type CommandOf,
+  type QueryOf,
+} from "@zudojs/cqrs";
+
+interface User {
+  id: string;
+  name: string;
+}
+
+type CreateUser = CommandOf<"CreateUser", { name: string }>;
+type GetUser = QueryOf<"GetUser", { id: string }>;
 
 const commandBus = createCommandBus();
 const queryBus = createQueryBus();
 
-commandBus.register("CreateUser", async (command) => {
-  return userRepository.create(command.data);
+// Function handler with explicit generics
+commandBus.register<CreateUser, User>("CreateUser", async (command) => {
+  return userRepository.create({ name: command.name });
+});
+
+// Typed handler object created with a factory
+queryBus.register(
+  "GetUser",
+  createQueryHandler<GetUser, User | undefined>("GetUser", async (query) =>
+    userRepository.findById(query.id),
+  ),
+);
+
+const user = await commandBus.execute<CreateUser, User>({
+  type: "CreateUser",
+  name: "Alice",
 });
 
-queryBus.register("GetUser", async (query) => {
-  return userRepository.findById(query.id);
+const found = await queryBus.execute<GetUser, User | undefined>({
+  type: "GetUser",
+  id: user.id,
+});
+```
+
+Class-based handlers extend `CommandHandler` / `QueryHandler`; any object with an
+`execute()` method is accepted as well.
+
+```typescript
+import { CommandHandler, createCommandBus } from "@zudojs/cqrs";
+
+class CreateUserHandler extends CommandHandler<CreateUser, User> {
+  readonly commandType = "CreateUser";
+
+  async execute(command: CreateUser): Promise<User> {
+    return userRepository.create({ name: command.name });
+  }
+}
+
+createCommandBus().register("CreateUser", new CreateUserHandler());
+```
+
+## Middleware
+
+```typescript
+import {
+  createCommandBus,
+  timingMiddleware,
+  errorMiddleware,
+  isCqrsError,
+} from "@zudojs/cqrs";
+
+const timing = timingMiddleware({
+  onTiming: ({ request, durationMs }) =>
+    console.log(`${request.type} took ${durationMs.toFixed(1)}ms`),
 });
+
+const bus = createCommandBus({ middleware: [timing, errorMiddleware()] });
+
+try {
+  await bus.execute({ type: "Unknown" });
+} catch (error) {
+  isCqrsError(error); // true — CommandHandlerNotFoundError
+}
 ```
 
+Validation and handler resolution run at the end of the middleware pipeline,
+so middleware observes `InvalidCommandError` / `CommandHandlerNotFoundError`
+like any other failure. Each middleware may call `next()` at most once.
+
 ## Features
 
 - Command bus for write operations
 - Query bus for read operations
-- Middleware pipeline for both
-- Command and query handlers
+- 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
+- Dedicated error classes (`isCqrsError`)
 - Result types for explicit returns
+- Execution contexts with correlation chains
 
 ## Use Cases
 

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

@@ -25,10 +25,13 @@ export declare abstract class MetadataCommand<TType extends string = string> ext
 }
 /**
  * Creates a simple immutable command object.
+ *
+ * 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<string, never>>(type: TType, payload?: TPayload): Readonly<{
+export declare function createCommand<TType extends string, TPayload extends Record<string, unknown> = Record<never, never>>(type: TType, payload?: TPayload): Readonly<{
     readonly type: TType;
-} & TPayload>;
+} & Omit<TPayload, "type">>;
 /**
  * Returns the command type discriminator.
  */

package/dist/command/command.core.js

@@ -1,3 +1,4 @@
+import { isCqrsRequest } from "../cqrsTypes/cqrsTypes.type.js";
 /**
  * Base abstract command.
  *
@@ -18,16 +19,23 @@ export class MetadataCommand extends Command {
     metadata;
     constructor(type, options = {}) {
         super(type);
-        this.metadata = options.metadata;
+        this.metadata = options.metadata
+            ? Object.freeze({
+                ...options.metadata,
+            })
+            : undefined;
     }
 }
 /**
  * Creates a simple immutable command object.
+ *
+ * The `type` argument always wins over any `type` key present in the
+ * payload, so untrusted payloads cannot reroute the command.
  */
 export function createCommand(type, payload) {
     return Object.freeze({
-        type,
         ...(payload ?? {}),
+        type,
     });
 }
 /**
@@ -40,11 +48,7 @@ export function getCommandType(command) {
  * Determines whether a value is a command.
  */
 export function isCommand(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "type" in value &&
-        typeof value.type === "string" &&
-        value.type.length > 0);
+    return isCqrsRequest(value);
 }
 /**
  * Creates a command type factory.

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

@@ -19,8 +19,14 @@ export interface CommandRegistration<TCommand extends Command = Command, TResult
 /**
  * Command bus implementation.
  *
- * The command bus resolves a handler by command type and executes it
- * through the registered middleware pipeline.
+ * The command bus runs every command through the registered middleware
+ * pipeline. Request validation and handler resolution happen at the end
+ * of the pipeline, so middleware observes `InvalidCommandError` and
+ * `CommandHandlerNotFoundError` like any other failure and may substitute
+ * the command (and therefore the handler) by forwarding a different
+ * request to `next()`.
+ *
+ * All failures are `CqrsError` instances (`isCqrsError(error) === true`).
  */
 export declare class CommandBus implements CommandBusContract {
     private readonly handlers;
@@ -29,6 +35,10 @@ export declare class CommandBus implements CommandBusContract {
     constructor(options?: CommandBusOptions);
     /**
      * Registers a command handler.
+     *
+     * @throws InvalidHandlerTypeError when the type is empty or padded with whitespace.
+     * @throws HandlerConfigurationError when the handler is not callable.
+     * @throws DuplicateHandlerError when a handler already exists for the type.
      */
     register<TCommand extends Command, TResult = void>(commandType: TCommand["type"], handler: CommandHandlerLike<TCommand, TResult>): this;
     /**
@@ -36,7 +46,7 @@ export declare class CommandBus implements CommandBusContract {
      */
     registerMany(registrations: readonly CommandRegistration[]): this;
     /**
-     * Replaces an existing command handler.
+     * Replaces an existing command handler (or registers a new one).
      */
     replace<TCommand extends Command, TResult = void>(commandType: TCommand["type"], handler: CommandHandlerLike<TCommand, TResult>): this;
     /**
@@ -52,7 +62,10 @@ export declare class CommandBus implements CommandBusContract {
      */
     getHandler<TCommand extends Command, TResult = void>(commandType: TCommand["type"]): CommandHandlerLike<TCommand, TResult> | undefined;
     /**
-     * Executes a command.
+     * Executes a command through the middleware pipeline.
+     *
+     * @throws InvalidCommandError when the command delivered to the end of the pipeline is malformed.
+     * @throws CommandHandlerNotFoundError when no handler is registered for its type.
      */
     execute<TCommand extends Command, TResult = void>(command: TCommand, context?: CqrsContext): Promise<TResult>;
     /**
@@ -72,9 +85,10 @@ export declare class CommandBus implements CommandBusContract {
      */
     getCommandTypes(): readonly string[];
     /**
-     * Builds the command execution pipeline.
+     * Terminal pipeline step: validates the delivered command, resolves
+     * its handler and executes it.
      */
-    private buildPipeline;
+    private dispatch;
     /**
      * Resolves the execution context.
      */

package/dist/command/commandBus.core.js

@@ -1,31 +1,43 @@
-import { BaseError, ErrorCategory, ErrorCode, ErrorSeverity, } from "@zudojs/errors";
-import { CommandHandler, executeCommandHandler, } from "../command/commandHandler.core.js";
+import { executeCommandHandler } from "../command/commandHandler.core.js";
+import { CommandHandlerNotFoundError, DuplicateHandlerError, InvalidCommandError, } from "../cqrsErrors/cqrsError.base.js";
+import { composeMiddleware } from "../cqrsMiddleware/cqrsMiddleware.core.js";
+import { assertExecutableHandler, assertHandlerType, assertMiddleware, } from "../cqrsValidation/cqrsValidation.core.js";
 /**
  * Command bus implementation.
  *
- * The command bus resolves a handler by command type and executes it
- * through the registered middleware pipeline.
+ * The command bus runs every command through the registered middleware
+ * pipeline. Request validation and handler resolution happen at the end
+ * of the pipeline, so middleware observes `InvalidCommandError` and
+ * `CommandHandlerNotFoundError` like any other failure and may substitute
+ * the command (and therefore the handler) by forwarding a different
+ * request to `next()`.
+ *
+ * All failures are `CqrsError` instances (`isCqrsError(error) === true`).
  */
 export class CommandBus {
     handlers = new Map();
     middleware;
     contextFactory;
     constructor(options = {}) {
-        this.middleware = [...(options.middleware ?? [])];
+        const middleware = [...(options.middleware ?? [])];
+        for (const entry of middleware) {
+            assertMiddleware("command", entry);
+        }
+        this.middleware = middleware;
         this.contextFactory = options.contextFactory;
     }
     /**
      * Registers a command handler.
+     *
+     * @throws InvalidHandlerTypeError when the type is empty or padded with whitespace.
+     * @throws HandlerConfigurationError when the handler is not callable.
+     * @throws DuplicateHandlerError when a handler already exists for the type.
      */
     register(commandType, handler) {
-        if (!commandType.trim()) {
-            throw new TypeError("Command type cannot be empty.");
-        }
-        if (!handler) {
-            throw new TypeError(`A handler is required for command "${commandType}".`);
-        }
+        assertHandlerType("command", commandType);
+        assertExecutableHandler("command", commandType, handler);
         if (this.handlers.has(commandType)) {
-            throw new Error(`A handler is already registered for command "${commandType}".`);
+            throw new DuplicateHandlerError("command", commandType);
         }
         this.handlers.set(commandType, handler);
         return this;
@@ -40,12 +52,11 @@ export class CommandBus {
         return this;
     }
     /**
-     * Replaces an existing command handler.
+     * Replaces an existing command handler (or registers a new one).
      */
     replace(commandType, handler) {
-        if (!commandType.trim()) {
-            throw new TypeError("Command type cannot be empty.");
-        }
+        assertHandlerType("command", commandType);
+        assertExecutableHandler("command", commandType, handler);
         this.handlers.set(commandType, handler);
         return this;
     }
@@ -68,35 +79,22 @@ export class CommandBus {
         return this.handlers.get(commandType);
     }
     /**
-     * Executes a command.
+     * Executes a command through the middleware pipeline.
+     *
+     * @throws InvalidCommandError when the command delivered to the end of the pipeline is malformed.
+     * @throws CommandHandlerNotFoundError when no handler is registered for its type.
      */
     async execute(command, context) {
-        this.validateCommand(command);
-        const handler = this.getHandler(command.type);
-        if (!handler) {
-            throw new BaseError(`No handler is registered for command "${command.type}".`, {
-                code: ErrorCode.COMMAND_HANDLER_NOT_FOUND,
-                category: ErrorCategory.SYSTEM,
-                severity: ErrorSeverity.ERROR,
-                statusCode: 500,
-                expose: false,
-                isOperational: true,
-                metadata: {
-                    commandType: command.type,
-                },
-            });
-        }
         const executionContext = await this.resolveContext(context);
-        const pipeline = this.buildPipeline(handler);
-        return pipeline(command, executionContext);
+        const pipeline = composeMiddleware(this.middleware);
+        const result = await pipeline(command, executionContext, (request, requestContext) => this.dispatch(request, requestContext));
+        return result;
     }
     /**
      * Adds middleware to the end of the pipeline.
      */
     use(middleware) {
-        if (typeof middleware !== "function") {
-            throw new TypeError("Command middleware must be a function.");
-        }
+        assertMiddleware("command", middleware);
         this.middleware.push(middleware);
         return this;
     }
@@ -119,16 +117,16 @@ export class CommandBus {
         return [...this.handlers.keys()];
     }
     /**
-     * Builds the command execution pipeline.
+     * Terminal pipeline step: validates the delivered command, resolves
+     * its handler and executes it.
      */
-    buildPipeline(handler) {
-        let next = async (command, context) => executeCommandHandler(handler, command, context);
-        for (let index = this.middleware.length - 1; index >= 0; index--) {
-            const middleware = this.middleware[index];
-            const current = next;
-            next = async (command, context) => middleware(command, context, current);
+    async dispatch(request, context) {
+        this.validateCommand(request);
+        const handler = this.handlers.get(request.type);
+        if (!handler) {
+            throw new CommandHandlerNotFoundError(request.type);
         }
-        return next;
+        return executeCommandHandler(handler, request, context);
     }
     /**
      * Resolves the execution context.
@@ -147,24 +145,11 @@ export class CommandBus {
      */
     validateCommand(command) {
         if (!command || typeof command !== "object") {
-            throw new BaseError("A valid command is required.", {
-                code: ErrorCode.INVALID_COMMAND,
-                category: ErrorCategory.VALIDATION,
-                severity: ErrorSeverity.WARNING,
-                statusCode: 400,
-                expose: true,
-                isOperational: true,
-            });
+            throw new InvalidCommandError("A valid command is required.");
         }
-        if (typeof command.type !== "string" || command.type.trim().length === 0) {
-            throw new BaseError("Command type is required.", {
-                code: ErrorCode.INVALID_COMMAND,
-                category: ErrorCategory.VALIDATION,
-                severity: ErrorSeverity.WARNING,
-                statusCode: 400,
-                expose: true,
-                isOperational: true,
-            });
+        const type = command.type;
+        if (typeof type !== "string" || type.trim().length === 0) {
+            throw new InvalidCommandError("Command type is required.");
         }
     }
 }

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

@@ -1,4 +1,4 @@
-import type { CommandHandler as CommandHandlerContract, Command, CqrsContext } from "../cqrsTypes/cqrsTypes.type.js";
+import type { CommandHandler as CommandHandlerContract, CommandHandlerLike, Command, CqrsContext } from "../cqrsTypes/cqrsTypes.type.js";
 /**
  * Abstract base class for command handlers.
  *
@@ -34,10 +34,16 @@ export declare function createCommandHandler<TCommand extends Command, TResult =
 export declare function isCommandHandler(value: unknown): value is CommandHandler;
 /**
  * Determines whether a value can be used as a command handler.
+ *
+ * Accepts handler functions, `CommandHandler` instances and any plain
+ * object exposing an `execute` method (the `CommandHandler` interface).
  */
-export declare function isCommandHandlerLike(value: unknown): value is CommandHandler | ((command: Command, context?: CqrsContext) => unknown);
+export declare function isCommandHandlerLike(value: unknown): value is CommandHandlerLike;
 /**
  * Executes either an object-based or function-based command handler.
+ *
+ * Object handlers only need an `execute` method; they do not have to
+ * extend the abstract `CommandHandler` class.
  */
-export declare function executeCommandHandler<TCommand extends Command, TResult = void>(handler: CommandHandler<TCommand, TResult> | ((command: TCommand, context?: CqrsContext) => TResult | Promise<TResult>), command: TCommand, context?: CqrsContext): Promise<TResult>;
+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

@@ -1,3 +1,5 @@
+import { HandlerConfigurationError } from "../cqrsErrors/cqrsError.base.js";
+import { isExecutableHandler } from "../cqrsValidation/cqrsValidation.core.js";
 /**
  * Abstract base class for command handlers.
  *
@@ -15,7 +17,10 @@ export class FunctionCommandHandler extends CommandHandler {
     constructor(commandType, handler) {
         super();
         if (typeof handler !== "function") {
-            throw new TypeError("Command handler must be a function.");
+            throw new HandlerConfigurationError("Command handler must be a function.", {
+                handlerKind: "command",
+                handlerType: commandType,
+            });
         }
         this.commandType = commandType;
         this.handler = handler;
@@ -38,20 +43,32 @@ export function isCommandHandler(value) {
 }
 /**
  * Determines whether a value can be used as a command handler.
+ *
+ * Accepts handler functions, `CommandHandler` instances and any plain
+ * object exposing an `execute` method (the `CommandHandler` interface).
  */
 export function isCommandHandlerLike(value) {
-    return value instanceof CommandHandler || typeof value === "function";
+    return isExecutableHandler(value);
 }
 /**
  * Executes either an object-based or function-based command handler.
+ *
+ * Object handlers only need an `execute` method; they do not have to
+ * extend the abstract `CommandHandler` class.
  */
 export async function executeCommandHandler(handler, command, context) {
-    if (handler instanceof CommandHandler) {
-        return await handler.execute(command, context);
-    }
     if (typeof handler === "function") {
         return await handler(command, context);
     }
-    throw new TypeError(`Invalid command handler for "${command.type}".`);
+    if (typeof handler === "object" &&
+        handler !== null &&
+        typeof handler
+            .execute === "function") {
+        return await handler.execute(command, context);
+    }
+    throw new HandlerConfigurationError(`Invalid command handler for "${command.type}": expected a function or an object with an execute() method.`, {
+        handlerKind: "command",
+        handlerType: command.type,
+    });
 }
 //# sourceMappingURL=commandHandler.core.js.map

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

@@ -32,10 +32,21 @@ export interface CreateExecutionContextInput {
 export declare function createRequestId(): string;
 /**
  * Creates an immutable CQRS execution context.
+ *
+ * Every context belongs to a correlation chain: when no `correlationId`
+ * is supplied the context starts a new chain using its own `requestId`,
+ * so children created with `createChildExecutionContext` always share a
+ * correlation with their root.
  */
 export declare function createExecutionContext(input?: CreateExecutionContextInput): CqrsExecutionContext;
 /**
  * Creates a child execution context while preserving correlation data.
+ *
+ * The child inherits the parent's correlation id; a parent without one
+ * (for example a hand-built object) contributes its `requestId` instead,
+ * and a fresh id is generated as a last resort, so `sharesCorrelation`
+ * holds between every parent and child. `metadata` is only set when the
+ * parent or the overrides supplied some.
  */
 export declare function createChildExecutionContext(parent: CqrsExecutionContext, overrides?: CreateExecutionContextInput): CqrsExecutionContext;
 /**

package/dist/cqrsContext/cqrsContext.core.js

@@ -11,11 +11,17 @@ export function createRequestId() {
 }
 /**
  * Creates an immutable CQRS execution context.
+ *
+ * Every context belongs to a correlation chain: when no `correlationId`
+ * is supplied the context starts a new chain using its own `requestId`,
+ * so children created with `createChildExecutionContext` always share a
+ * correlation with their root.
  */
 export function createExecutionContext(input = {}) {
+    const requestId = input.requestId ?? createRequestId();
     const context = {
-        requestId: input.requestId ?? createRequestId(),
-        correlationId: input.correlationId,
+        requestId,
+        correlationId: input.correlationId ?? requestId,
         causationId: input.causationId,
         userId: input.userId,
         tenantId: input.tenantId,
@@ -30,19 +36,31 @@ export function createExecutionContext(input = {}) {
 }
 /**
  * Creates a child execution context while preserving correlation data.
+ *
+ * The child inherits the parent's correlation id; a parent without one
+ * (for example a hand-built object) contributes its `requestId` instead,
+ * and a fresh id is generated as a last resort, so `sharesCorrelation`
+ * holds between every parent and child. `metadata` is only set when the
+ * parent or the overrides supplied some.
  */
 export function createChildExecutionContext(parent, overrides = {}) {
+    const hasMetadata = parent.metadata !== undefined || overrides.metadata !== undefined;
     return createExecutionContext({
         requestId: overrides.requestId,
-        correlationId: overrides.correlationId ?? parent.correlationId,
+        correlationId: overrides.correlationId ??
+            parent.correlationId ??
+            parent.requestId ??
+            createRequestId(),
         causationId: overrides.causationId ?? parent.requestId ?? parent.causationId,
         userId: overrides.userId ?? parent.userId,
         tenantId: overrides.tenantId ?? parent.tenantId,
         source: overrides.source ?? parent.source,
-        metadata: {
-            ...(parent.metadata ?? {}),
-            ...(overrides.metadata ?? {}),
-        },
+        metadata: hasMetadata
+            ? {
+                ...(parent.metadata ?? {}),
+                ...(overrides.metadata ?? {}),
+            }
+            : undefined,
     });
 }
 /**

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

@@ -61,13 +61,19 @@ export type DecoratedCqrsClass<TInstance = object> = CqrsClass<TInstance> & {
  */
 export declare function CqrsHandler<TType extends string>(kind: CqrsHandlerKind, type: TType): ClassDecorator;
 /**
- * Marks a class as a command handler.
+ * Marks a class as the command handler for `type`.
+ *
+ * Named `CommandHandlerFor` so it does not collide with the abstract
+ * `CommandHandler` class exported from the same package.
  */
-export declare function CommandHandler(type: string): ClassDecorator;
+export declare function CommandHandlerFor(type: string): ClassDecorator;
 /**
- * Marks a class as a query handler.
+ * 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.
  */
-export declare function QueryHandler(type: string): ClassDecorator;
+export declare function QueryHandlerFor(type: string): ClassDecorator;
 /**
  * Reads generic CQRS handler metadata from a class.
  */
@@ -89,13 +95,13 @@ export declare function getCqrsType(target: unknown): string | undefined;
  */
 export declare function isCqrsHandler(target: unknown): boolean;
 /**
- * Determines whether a class is decorated as a command handler.
+ * Determines whether a class is decorated with `CommandHandlerFor`.
  */
-export declare function isCommandHandler(target: unknown): boolean;
+export declare function isDecoratedCommandHandler(target: unknown): boolean;
 /**
- * Determines whether a class is decorated as a query handler.
+ * Determines whether a class is decorated with `QueryHandlerFor`.
  */
-export declare function isQueryHandler(target: unknown): boolean;
+export declare function isDecoratedQueryHandler(target: unknown): boolean;
 /**
  * Creates a reusable command handler decorator.
  */