@zudojs/cqrs 0.1.0 → 1.0.0

package/dist/cqrsDecorators/cqrsDecorators.core.js

@@ -1,3 +1,5 @@
+import { HandlerConfigurationError } from "../cqrsErrors/cqrsError.base.js";
+import { assertHandlerType } from "../cqrsValidation/cqrsValidation.core.js";
 /**
  * Metadata key used to identify CQRS handler configuration.
  */
@@ -28,24 +30,17 @@ export function CqrsHandler(kind, type) {
             kind,
             type,
         });
-        Object.defineProperty(constructor, CQRS_HANDLER_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: metadata,
-        });
-        Object.defineProperty(constructor, CQRS_TYPE_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: type,
-        });
+        defineMetadata(constructor, CQRS_HANDLER_METADATA, metadata);
+        defineMetadata(constructor, CQRS_TYPE_METADATA, type);
     };
 }
 /**
- * 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 function CommandHandler(type) {
+export function CommandHandlerFor(type) {
     validateHandlerMetadata("command", type);
     return (target) => {
         const constructor = target;
@@ -53,30 +48,18 @@ export function CommandHandler(type) {
             kind: "command",
             type,
         });
-        Object.defineProperty(constructor, COMMAND_HANDLER_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: metadata,
-        });
-        Object.defineProperty(constructor, CQRS_HANDLER_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: metadata,
-        });
-        Object.defineProperty(constructor, CQRS_TYPE_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: type,
-        });
+        defineMetadata(constructor, COMMAND_HANDLER_METADATA, metadata);
+        defineMetadata(constructor, CQRS_HANDLER_METADATA, metadata);
+        defineMetadata(constructor, CQRS_TYPE_METADATA, type);
     };
 }
 /**
- * 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 function QueryHandler(type) {
+export function QueryHandlerFor(type) {
     validateHandlerMetadata("query", type);
     return (target) => {
         const constructor = target;
@@ -84,24 +67,9 @@ export function QueryHandler(type) {
             kind: "query",
             type,
         });
-        Object.defineProperty(constructor, QUERY_HANDLER_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: metadata,
-        });
-        Object.defineProperty(constructor, CQRS_HANDLER_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: metadata,
-        });
-        Object.defineProperty(constructor, CQRS_TYPE_METADATA, {
-            configurable: false,
-            enumerable: false,
-            writable: false,
-            value: type,
-        });
+        defineMetadata(constructor, QUERY_HANDLER_METADATA, metadata);
+        defineMetadata(constructor, CQRS_HANDLER_METADATA, metadata);
+        defineMetadata(constructor, CQRS_TYPE_METADATA, type);
     };
 }
 /**
@@ -147,35 +115,86 @@ export function isCqrsHandler(target) {
     return getCqrsHandlerMetadata(target) !== undefined;
 }
 /**
- * Determines whether a class is decorated as a command handler.
+ * Determines whether a class is decorated with `CommandHandlerFor`.
  */
-export function isCommandHandler(target) {
+export function isDecoratedCommandHandler(target) {
     return getCommandHandlerMetadata(target) !== undefined;
 }
 /**
- * Determines whether a class is decorated as a query handler.
+ * Determines whether a class is decorated with `QueryHandlerFor`.
  */
-export function isQueryHandler(target) {
+export function isDecoratedQueryHandler(target) {
     return getQueryHandlerMetadata(target) !== undefined;
 }
 /**
  * Creates a reusable command handler decorator.
  */
 export function createCommandHandlerDecorator(type) {
-    return CommandHandler(type);
+    return CommandHandlerFor(type);
 }
 /**
  * Creates a reusable query handler decorator.
  */
 export function createQueryHandlerDecorator(type) {
-    return QueryHandler(type);
+    return QueryHandlerFor(type);
 }
 /**
  * Validates decorator arguments.
  */
 function validateHandlerMetadata(kind, type) {
-    if (typeof type !== "string" || type.trim().length === 0) {
-        throw new TypeError(`${kind} handler type cannot be empty.`);
+    assertHandlerType(kind, type);
+}
+/**
+ * Defines immutable metadata on a constructor.
+ *
+ * Re-applying a decorator that carries identical metadata is a no-op, so
+ * stacking `CqrsHandler("command", "A")` with `CommandHandlerFor("A")`
+ * works. Conflicting metadata throws `HandlerConfigurationError`.
+ */
+function defineMetadata(constructor, key, value) {
+    if (Object.prototype.hasOwnProperty.call(constructor, key)) {
+        const existing = constructor[key];
+        if (isSameMetadata(existing, value)) {
+            return;
+        }
+        throw new HandlerConfigurationError(`Class "${constructor.name || "<anonymous>"}" already carries conflicting CQRS handler metadata (${describeMetadata(existing)} vs ${describeMetadata(value)}).`, {
+            className: constructor.name,
+            existing: describeMetadata(existing),
+            incoming: describeMetadata(value),
+        });
+    }
+    Object.defineProperty(constructor, key, {
+        configurable: false,
+        enumerable: false,
+        writable: false,
+        value,
+    });
+}
+/**
+ * Compares two metadata values structurally.
+ */
+function isSameMetadata(existing, incoming) {
+    if (typeof incoming === "string") {
+        return existing === incoming;
+    }
+    if (typeof existing !== "object" || existing === null) {
+        return false;
+    }
+    const current = existing;
+    return (current.kind === incoming.kind &&
+        current.type === incoming.type);
+}
+/**
+ * Renders metadata for error messages.
+ */
+function describeMetadata(value) {
+    if (typeof value === "string") {
+        return `"${value}"`;
+    }
+    if (typeof value === "object" && value !== null) {
+        const metadata = value;
+        return `${String(metadata.kind)}:"${String(metadata.type)}"`;
     }
+    return String(value);
 }
 //# sourceMappingURL=cqrsDecorators.core.js.map

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

@@ -1,14 +1,31 @@
-import { BaseError, type ErrorMetadata } from "@zudojs/errors";
+import { BaseError, ErrorCode, type BaseErrorOptions, type ErrorMetadata } from "@zudojs/errors";
 /**
  * Base error for failures originating from the CQRS package.
  */
 export declare class CqrsError extends BaseError {
-    constructor(message: string, options?: ConstructorParameters<typeof BaseError>[1]);
+    constructor(message: string, options?: BaseErrorOptions);
 }
 /**
  * Thrown when a CQRS request is invalid.
+ *
+ * The error code defaults to `ERR_INVALID_INPUT`; request-specific
+ * subclasses (`InvalidCommandError`, `InvalidQueryError`) narrow it.
  */
 export declare class CqrsValidationError extends CqrsError {
+    constructor(message?: string, metadata?: ErrorMetadata, code?: ErrorCode | string);
+}
+/**
+ * Thrown by the command bus when a command is malformed
+ * (not an object, or missing a non-empty `type`).
+ */
+export declare class InvalidCommandError extends CqrsValidationError {
+    constructor(message?: string, metadata?: ErrorMetadata);
+}
+/**
+ * Thrown by the query bus when a query is malformed
+ * (not an object, or missing a non-empty `type`).
+ */
+export declare class InvalidQueryError extends CqrsValidationError {
     constructor(message?: string, metadata?: ErrorMetadata);
 }
 /**
@@ -56,6 +73,13 @@ export declare class InvalidHandlerTypeError extends CqrsValidationError {
     readonly handlerKind: "command" | "query" | "event";
     constructor(handlerKind: "command" | "query" | "event", handlerType: unknown);
 }
+/**
+ * Thrown when a registry operation receives an unsupported handler kind.
+ */
+export declare class InvalidHandlerKindError extends CqrsValidationError {
+    readonly handlerKind: string;
+    constructor(handlerKind: unknown);
+}
 /**
  * Thrown when CQRS middleware is invalid.
  */
@@ -80,6 +104,14 @@ export declare class HandlerConfigurationError extends CqrsError {
 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).
+ * - 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

@@ -5,32 +5,53 @@ import { BaseError, ErrorCategory, ErrorCode, ErrorSeverity, } from "@zudojs/err
 export class CqrsError extends BaseError {
     constructor(message, options = {}) {
         super(message, {
+            ...options,
             code: options.code ?? ErrorCode.INTERNAL_ERROR,
             category: options.category ?? ErrorCategory.SYSTEM,
             severity: options.severity ?? ErrorSeverity.ERROR,
             statusCode: options.statusCode ?? 500,
             expose: options.expose ?? false,
             isOperational: options.isOperational ?? true,
-            ...options,
         });
     }
 }
 /**
  * Thrown when a CQRS request is invalid.
+ *
+ * The error code defaults to `ERR_INVALID_INPUT`; request-specific
+ * subclasses (`InvalidCommandError`, `InvalidQueryError`) narrow it.
  */
 export class CqrsValidationError extends CqrsError {
-    constructor(message = "The CQRS request is invalid.", metadata) {
+    constructor(message = "The CQRS request is invalid.", metadata, code = ErrorCode.INVALID_INPUT) {
         super(message, {
-            code: ErrorCode.INVALID_INPUT,
+            code,
             category: ErrorCategory.VALIDATION,
             severity: ErrorSeverity.WARNING,
             statusCode: 400,
             expose: true,
             isOperational: true,
-            metadata: metadata,
+            metadata,
         });
     }
 }
+/**
+ * Thrown by the command bus when a command is malformed
+ * (not an object, or missing a non-empty `type`).
+ */
+export class InvalidCommandError extends CqrsValidationError {
+    constructor(message = "The command is invalid.", metadata) {
+        super(message, metadata, ErrorCode.INVALID_COMMAND);
+    }
+}
+/**
+ * Thrown by the query bus when a query is malformed
+ * (not an object, or missing a non-empty `type`).
+ */
+export class InvalidQueryError extends CqrsValidationError {
+    constructor(message = "The query is invalid.", metadata) {
+        super(message, metadata, ErrorCode.INVALID_QUERY);
+    }
+}
 /**
  * Thrown when a command handler cannot be resolved.
  */
@@ -155,6 +176,18 @@ export class InvalidHandlerTypeError extends CqrsValidationError {
         this.handlerKind = handlerKind;
     }
 }
+/**
+ * Thrown when a registry operation receives an unsupported handler kind.
+ */
+export class InvalidHandlerKindError extends CqrsValidationError {
+    handlerKind;
+    constructor(handlerKind) {
+        super(`Unsupported handler kind "${String(handlerKind)}". Expected "command" or "query".`, {
+            handlerKind: String(handlerKind),
+        });
+        this.handlerKind = String(handlerKind);
+    }
+}
 /**
  * Thrown when CQRS middleware is invalid.
  */
@@ -191,7 +224,7 @@ export class HandlerConfigurationError extends CqrsError {
             statusCode: 500,
             expose: false,
             isOperational: true,
-            metadata: metadata,
+            metadata,
         });
     }
 }
@@ -203,11 +236,31 @@ 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).
+ * - 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 function toCqrsError(error, message = "CQRS execution failed.") {
     if (error instanceof CqrsError) {
         return error;
     }
+    if (error instanceof BaseError) {
+        return new CqrsError(error.message, {
+            code: error.code,
+            category: error.category,
+            severity: error.severity,
+            statusCode: error.statusCode,
+            expose: error.expose,
+            isOperational: error.isOperational,
+            metadata: error.metadata,
+            cause: error,
+        });
+    }
     return new CqrsError(error instanceof Error ? error.message : message, {
         code: ErrorCode.INTERNAL_ERROR,
         category: ErrorCategory.SYSTEM,

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

@@ -1,4 +1,4 @@
-import type { Event, EventId, EventType, EventCorrelationId } from "@zudojs/events";
+import type { Event, EventId, EventType } from "@zudojs/events";
 /**
  * CQRS-specific event extensions.
  *
@@ -19,15 +19,21 @@ export interface CqrsEventExtensions {
 export type CqrsEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = Event<TPayload> & CqrsEventExtensions;
 /**
  * Input used to create a CQRS event.
+ *
+ * Identifiers are accepted as plain strings so values coming from a
+ * `CqrsContext` (`requestId`, `correlationId`, `causationId`) and from
+ * `createEventId()` can be passed without casts; the created event still
+ * carries the branded `EventId`/`EventCorrelationId` types of the base
+ * `Event` contract.
  */
 export interface CreateCqrsEventInput<TPayload extends Record<string, unknown> = Record<string, unknown>> {
     readonly type: EventType;
     readonly payload: TPayload;
-    readonly id?: EventId;
+    readonly id?: string;
     readonly timestamp?: Date | number;
     readonly source?: string;
-    readonly correlationId?: EventCorrelationId;
-    readonly causationId?: EventCorrelationId;
+    readonly correlationId?: string;
+    readonly causationId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly aggregateId?: string;
     readonly aggregateType?: string;
@@ -51,9 +57,10 @@ export interface CqrsEventHandlerRegistration<TEvent extends CqrsEvent = CqrsEve
 /**
  * Creates a unique CQRS event identifier.
  *
- * Delegates to the base Zudojs event ID generator.
+ * Delegates to the base Zudojs event ID generator and returns its
+ * branded `EventId` (assignable to `string`).
  */
-export declare function createEventId(): string;
+export declare function createEventId(): EventId;
 /**
  * Creates an immutable CQRS event.
  *

package/dist/cqrsEvents/cqrsEvents.type.js

@@ -2,7 +2,8 @@ import { createEvent as baseCreateEvent, createEventId as baseCreateEventId, isE
 /**
  * Creates a unique CQRS event identifier.
  *
- * Delegates to the base Zudojs event ID generator.
+ * Delegates to the base Zudojs event ID generator and returns its
+ * branded `EventId` (assignable to `string`).
  */
 export function createEventId() {
     return baseCreateEventId();
@@ -31,8 +32,17 @@ export function createCqrsEvent(input) {
         causationId: input.causationId,
         metadata: input.metadata,
     });
+    // A CQRS domain event type is a durable identifier: it is written
+    // into event streams and matched by aggregate reducers, so
+    // "UserCreated" must survive round-tripping verbatim. The base
+    // event factory lower-cases and collapses separators for bus
+    // routing, which is right for pub/sub topics but destructive for
+    // domain names (it also collides "UserCreated" with "usercreated").
+    // Routing still works: the registry normalizes the lookup key on
+    // both registration and dispatch.
     const event = {
         ...base,
+        type: input.type.trim(),
         aggregateId: input.aggregateId,
         aggregateType: input.aggregateType,
         version: input.version,

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

@@ -10,17 +10,88 @@ export interface MiddlewareOptions {
     readonly name?: string;
     readonly enabled?: boolean;
 }
+/**
+ * Measurement reported by `timingMiddleware` after every execution.
+ */
+export interface CqrsTiming {
+    /**
+     * Name given to the middleware (`options.name`, default `"timing"`).
+     */
+    readonly name: string;
+    /**
+     * The request that was executed.
+     */
+    readonly request: Command | Query;
+    /**
+     * The execution context the middleware received.
+     */
+    readonly context: CqrsContext | undefined;
+    /**
+     * Wall-clock duration of everything downstream of the middleware.
+     */
+    readonly durationMs: number;
+    /**
+     * Whether the downstream execution resolved (`true`) or threw.
+     */
+    readonly succeeded: boolean;
+    /**
+     * The error thrown downstream, when `succeeded` is `false`.
+     */
+    readonly error?: unknown;
+}
+/**
+ * Options for `timingMiddleware`.
+ */
+export interface TimingMiddlewareOptions extends MiddlewareOptions {
+    /**
+     * Receives the measurement after each execution (success or failure).
+     * Errors thrown by the callback propagate to the caller.
+     *
+     * Optional: measurements are always exposed through
+     * `TimingMiddleware.lastTiming` as well.
+     */
+    readonly onTiming?: (timing: CqrsTiming) => void | Promise<void>;
+    /**
+     * Monotonic clock in milliseconds. Defaults to `performance.now()`.
+     */
+    readonly now?: () => number;
+}
+/**
+ * Middleware returned by `timingMiddleware`.
+ *
+ * Besides acting as ordinary middleware it exposes the most recent
+ * measurement, so timings are observable even without an `onTiming`
+ * callback.
+ */
+export interface TimingMiddleware extends CqrsMiddleware {
+    /**
+     * Measurement of the most recent execution, or `undefined` before the
+     * first execution completes.
+     */
+    readonly lastTiming: CqrsTiming | undefined;
+    /**
+     * Number of executions measured so far.
+     */
+    readonly count: number;
+}
 /**
  * Middleware that measures command or query execution time.
+ *
+ * Every measurement is reported through `options.onTiming` (when given)
+ * and stored on the returned middleware as `lastTiming`.
  */
-export declare function timingMiddleware(options?: MiddlewareOptions): CqrsMiddleware;
+export declare function timingMiddleware(options?: TimingMiddlewareOptions): TimingMiddleware;
 /**
  * Middleware that catches unknown exceptions and normalizes them
- * into BaseError instances.
+ * into `CqrsError` instances.
+ *
+ * `BaseError` instances (including every CQRS error) pass through
+ * unchanged.
  */
 export declare function errorMiddleware(options?: MiddlewareOptions): CqrsMiddleware;
 /**
- * Middleware that validates the basic CQRS request structure.
+ * Middleware that validates the basic CQRS request structure and throws
+ * `CqrsValidationError` when it is malformed.
  */
 export declare function validationMiddleware(options?: MiddlewareOptions): CqrsMiddleware;
 /**
@@ -28,16 +99,28 @@ export declare function validationMiddleware(options?: MiddlewareOptions): CqrsM
  */
 export declare function contextMiddleware(options?: MiddlewareOptions): CqrsMiddleware;
 /**
- * Middleware that prevents concurrent execution of the same request type
- * when used with a shared lock implementation.
+ * Lock implementation used by `lockMiddleware`.
+ *
+ * `acquire` must resolve to a release function.
  */
 export interface CqrsLock {
     acquire(key: string): (() => void) | Promise<() => void>;
 }
 /**
- * Creates locking middleware.
+ * Options for `lockMiddleware`.
+ */
+export interface LockMiddlewareOptions extends MiddlewareOptions {
+    /**
+     * Derives the lock key from the request. Defaults to `request.type`,
+     * which serialises every request of that type.
+     */
+    readonly key?: (request: Command | Query, context?: CqrsContext) => string;
+}
+/**
+ * Creates locking middleware that prevents concurrent execution of
+ * requests sharing the same lock key.
  */
-export declare function lockMiddleware(lock: CqrsLock, options?: MiddlewareOptions): CqrsMiddleware;
+export declare function lockMiddleware(lock: CqrsLock, options?: LockMiddlewareOptions): CqrsMiddleware;
 /**
  * Adapts command-specific middleware to generic CQRS middleware.
  */
@@ -48,6 +131,11 @@ export declare function commandMiddleware(middleware: CommandMiddleware): CqrsMi
 export declare function queryMiddleware(middleware: QueryMiddleware): CqrsMiddleware;
 /**
  * Combines multiple middleware functions into a single middleware.
+ *
+ * Each middleware may call `next()` at most once per execution; a second
+ * call throws `MiddlewareExecutionError`. The command and query buses
+ * build their pipelines with this function, so the same rule applies
+ * there.
  */
 export declare function composeMiddleware(middleware: readonly CqrsMiddleware[]): CqrsMiddleware;
 /**