@zudojs/cqrs 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,12 @@
 
 Command Query Responsibility Segregation (CQRS) primitives for separating read and write operations.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-cqrs](https://zudojs.oyinlola.site/docs/packages-cqrs) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-cqrs.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -103,6 +109,10 @@ 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.
 
+`onTiming` is an observer: if it throws, the command or query still
+succeeds (or fails with its own error). Pass `onTimingError` to see those
+observer failures.
+
 ## Features
 
 - Command bus for write operations

package/dist/command/commandBus.core.js

@@ -1,6 +1,6 @@
 import { executeCommandHandler } from "../command/commandHandler.core.js";
 import { CommandHandlerNotFoundError, DuplicateHandlerError, InvalidCommandError, } from "../cqrsErrors/cqrsError.base.js";
-import { composeMiddleware } from "../cqrsMiddleware/cqrsMiddleware.core.js";
+import { composeMiddleware } from "../cqrsMiddleware/cqrsMiddleware.compose.js";
 import { assertExecutableHandler, assertHandlerType, assertMiddleware, } from "../cqrsValidation/cqrsValidation.core.js";
 /**
  * Command bus implementation.

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

@@ -1,10 +1,11 @@
-import { BaseError, ErrorCode, type BaseErrorOptions, type ErrorMetadata } from "@zudojs/errors";
+import { CqrsError, ErrorCode, type ErrorMetadata } from "@zudojs/errors";
 /**
  * Base error for failures originating from the CQRS package.
+ *
+ * Owned by `@zudojs/errors` and re-exported here, so
+ * `instanceof CqrsError` matches across both packages.
  */
-export declare class CqrsError extends BaseError {
-    constructor(message: string, options?: BaseErrorOptions);
-}
+export { CqrsError };
 /**
  * Thrown when a CQRS request is invalid.
  *

package/dist/cqrsErrors/cqrsError.base.js

@@ -1,20 +1,11 @@
-import { BaseError, ErrorCategory, ErrorCode, ErrorSeverity, } from "@zudojs/errors";
+import { BaseError, CqrsError, ErrorCategory, ErrorCode, ErrorSeverity, } from "@zudojs/errors";
 /**
  * Base error for failures originating from the CQRS package.
+ *
+ * Owned by `@zudojs/errors` and re-exported here, so
+ * `instanceof CqrsError` matches across both packages.
  */
-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,
-        });
-    }
-}
+export { CqrsError };
 /**
  * Thrown when a CQRS request is invalid.
  *

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

@@ -0,0 +1,14 @@
+/**
+ * CQRS middleware composition, built on `compose` from `@zudojs/middleware`.
+ */
+import type { CqrsMiddleware } from "../cqrsTypes/cqrsTypes.type.js";
+/**
+ * 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;
+//# sourceMappingURL=cqrsMiddleware.compose.d.ts.map

package/dist/cqrsMiddleware/cqrsMiddleware.compose.js

@@ -0,0 +1,33 @@
+/**
+ * CQRS middleware composition, built on `compose` from `@zudojs/middleware`.
+ */
+import { compose } from "@zudojs/middleware";
+import { MiddlewareExecutionError } from "../cqrsErrors/cqrsError.base.js";
+/** Adapts one CQRS middleware to the shared `(context, next)` shape. */
+function adapt(middleware) {
+    return async (state, next) => {
+        let called = false;
+        return middleware(state.request, state.context, (request, context) => {
+            if (called) {
+                return Promise.reject(new MiddlewareExecutionError());
+            }
+            called = true;
+            state.request = request;
+            state.context = context;
+            return next();
+        });
+    };
+}
+/**
+ * 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 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

@@ -45,12 +45,19 @@ export interface CqrsTiming {
 export interface TimingMiddlewareOptions extends MiddlewareOptions {
     /**
      * Receives the measurement after each execution (success or failure).
-     * Errors thrown by the callback propagate to the caller.
+     * The callback is an observer: if it throws or rejects, the error is
+     * passed to `onTimingError` (when given) and otherwise discarded. It
+     * never changes the outcome of the command or query.
      *
      * Optional: measurements are always exposed through
      * `TimingMiddleware.lastTiming` as well.
      */
     readonly onTiming?: (timing: CqrsTiming) => void | Promise<void>;
+    /**
+     * Receives any error thrown by `onTiming`. Errors thrown here are
+     * discarded as well.
+     */
+    readonly onTimingError?: (error: unknown, timing: CqrsTiming) => void;
     /**
      * Monotonic clock in milliseconds. Defaults to `performance.now()`.
      */
@@ -104,7 +111,12 @@ export declare function contextMiddleware(options?: MiddlewareOptions): CqrsMidd
  * `acquire` must resolve to a release function.
  */
 export interface CqrsLock {
-    acquire(key: string): (() => void) | Promise<() => void>;
+    /**
+     * The release function may be synchronous or return a promise; the
+     * middleware awaits it. A rejected release surfaces as a `CqrsError`
+     * (when the handler succeeded) rather than an unhandled rejection.
+     */
+    acquire(key: string): (() => void | Promise<void>) | Promise<() => void | Promise<void>>;
 }
 /**
  * Options for `lockMiddleware`.
@@ -129,15 +141,6 @@ export declare function commandMiddleware(middleware: CommandMiddleware): CqrsMi
  * Adapts query-specific middleware to generic CQRS middleware.
  */
 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;
 /**
  * Creates a middleware that runs a callback before execution.
  */

package/dist/cqrsMiddleware/cqrsMiddleware.core.js

@@ -1,5 +1,5 @@
 import { BaseError } from "@zudojs/errors";
-import { CqrsError, CqrsValidationError, InvalidMiddlewareError, MiddlewareExecutionError, } from "../cqrsErrors/cqrsError.base.js";
+import { CqrsError, CqrsValidationError, InvalidMiddlewareError, } from "../cqrsErrors/cqrsError.base.js";
 /**
  * Middleware that measures command or query execution time.
  *
@@ -10,6 +10,10 @@ export function timingMiddleware(options = {}) {
     if (options.onTiming !== undefined && typeof options.onTiming !== "function") {
         throw new InvalidMiddlewareError("timingMiddleware onTiming must be a function.");
     }
+    if (options.onTimingError !== undefined &&
+        typeof options.onTimingError !== "function") {
+        throw new InvalidMiddlewareError("timingMiddleware onTimingError must be a function.");
+    }
     if (options.now !== undefined && typeof options.now !== "function") {
         throw new InvalidMiddlewareError("timingMiddleware now must be a function.");
     }
@@ -21,9 +25,20 @@ export function timingMiddleware(options = {}) {
     const record = async (timing) => {
         lastTiming = timing;
         count += 1;
-        if (onTiming) {
+        if (!onTiming) {
+            return;
+        }
+        try {
             await onTiming(timing);
         }
+        catch (error) {
+            try {
+                options.onTimingError?.(error, timing);
+            }
+            catch {
+                return;
+            }
+        }
     };
     const middleware = async (request, context, next) => {
         if (options.enabled === false) {
@@ -154,12 +169,35 @@ export function lockMiddleware(lock, options = {}) {
                 lockKey: key,
             });
         }
+        // `release()` may be asynchronous (a Redis DEL, say). It used to be
+        // called and dropped, so a rejected release was an unhandled promise
+        // rejection — which terminates the process under Node's defaults.
+        let result;
         try {
-            return await next(request, context);
+            result = await next(request, context);
+        }
+        catch (error) {
+            try {
+                await release();
+            }
+            catch {
+                // The handler's failure is the one the caller needs to see.
+            }
+            throw error;
+        }
+        try {
+            await release();
         }
-        finally {
-            release();
+        catch (error) {
+            throw new CqrsError(`CQRS lock release failed (key "${key}").`, {
+                cause: error,
+                metadata: {
+                    lockKey: key,
+                    requestType: getRequestType(request),
+                },
+            });
         }
+        return result;
     };
 }
 /**
@@ -178,32 +216,6 @@ export function queryMiddleware(middleware) {
         return middleware(request, context, async (query, nextContext) => next(query, nextContext));
     };
 }
-/**
- * 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 function composeMiddleware(middleware) {
-    const stack = [...middleware];
-    return async (request, context, terminal) => {
-        let index = -1;
-        const dispatch = async (currentIndex, currentRequest, currentContext) => {
-            if (currentIndex <= index) {
-                throw new MiddlewareExecutionError();
-            }
-            index = currentIndex;
-            const current = stack[currentIndex];
-            if (!current) {
-                return terminal(currentRequest, currentContext);
-            }
-            return current(currentRequest, currentContext, (nextRequest, nextContext) => dispatch(currentIndex + 1, nextRequest, nextContext));
-        };
-        return dispatch(0, request, context);
-    };
-}
 /**
  * Creates a middleware that runs a callback before execution.
  */

package/dist/cqrsMiddleware/index.d.ts

@@ -5,4 +5,5 @@
  * context enrichment, lifecycle callbacks, and composition.
  */
 export * from "./cqrsMiddleware.core.js";
+export * from "./cqrsMiddleware.compose.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cqrsMiddleware/index.js

@@ -5,4 +5,5 @@
  * context enrichment, lifecycle callbacks, and composition.
  */
 export * from "./cqrsMiddleware.core.js";
+export * from "./cqrsMiddleware.compose.js";
 //# sourceMappingURL=index.js.map

package/dist/query/queryBus.core.js

@@ -1,6 +1,6 @@
 import { executeQueryHandler } from "../query/queryHandler.core.js";
 import { QueryHandlerNotFoundError, DuplicateHandlerError, InvalidQueryError, } from "../cqrsErrors/cqrsError.base.js";
-import { composeMiddleware } from "../cqrsMiddleware/cqrsMiddleware.core.js";
+import { composeMiddleware } from "../cqrsMiddleware/cqrsMiddleware.compose.js";
 import { assertExecutableHandler, assertHandlerType, assertMiddleware, } from "../cqrsValidation/cqrsValidation.core.js";
 /**
  * Query bus implementation.

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/cqrs",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Command Query Responsibility Segregation (CQRS) primitives for separating read and write operations.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,8 +25,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/events": "1.0.0"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/events": "1.1.0",
+    "@zudojs/middleware": "1.0.2"
   },
   "devDependencies": {
     "typescript": "7.0.2",