@zudojs/cqrs 1.1.0 → 1.2.0

package/README.md

@@ -113,6 +113,27 @@ like any other failure. Each middleware may call `next()` at most once.
 succeeds (or fails with its own error). Pass `onTimingError` to see those
 observer failures.
 
+## Result values
+
+`createCommandResult` / `createFailedCommandResult` (and the `Query`
+equivalents) wrap a value with its status and execution metadata, for
+infrastructure that represents failures as values. `unwrapCommandResult`
+returns the value of a successful result and **throws** for a failed one:
+`CommandFailedError` (or `QueryFailedError` from `unwrapQueryResult`), with the
+failure payload on `error.failure` and `error.cause`. Both errors are defined in
+`@zudojs/errors` and re-exported here. Before 1.2 the failure payload was
+returned as if it were the value.
+
+```typescript
+import { unwrapCommandResult, CommandFailedError } from "@zudojs/cqrs";
+
+try {
+  const order = unwrapCommandResult(result);
+} catch (error) {
+  if (error instanceof CommandFailedError) console.error(error.failure);
+}
+```
+
 ## Features
 
 - Command bus for write operations

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

@@ -47,7 +47,11 @@ export declare function isSuccessfulCommandResult<TResult, TCommand extends Comm
  */
 export declare function isFailedCommandResult<TResult, TCommand extends Command = Command>(result: CommandResult<TResult, TCommand>): boolean;
 /**
- * Maps a command result to its underlying value.
+ * Returns the value of a successful command result.
+ *
+ * @throws {CommandFailedError} when the result's status is `"failure"`.
+ *   The failure payload is on `error.failure` (and `error.cause`). Before
+ *   1.2 the payload was returned as if it were the command's value.
  */
 export declare function unwrapCommandResult<TResult, TCommand extends Command = Command>(result: CommandResult<TResult, TCommand>): TResult;
 /**

package/dist/command/commandResult.type.js

@@ -1,3 +1,4 @@
+import { CommandFailedError } from "@zudojs/errors";
 /**
  * Creates a successful command result.
  */
@@ -54,9 +55,16 @@ export function isFailedCommandResult(result) {
     return result.status === "failure";
 }
 /**
- * Maps a command result to its underlying value.
+ * Returns the value of a successful command result.
+ *
+ * @throws {CommandFailedError} when the result's status is `"failure"`.
+ *   The failure payload is on `error.failure` (and `error.cause`). Before
+ *   1.2 the payload was returned as if it were the command's value.
  */
 export function unwrapCommandResult(result) {
+    if (result.status === "failure") {
+        throw new CommandFailedError(String(result.commandType), result.result);
+    }
     return result.result;
 }
 /**

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

@@ -6,6 +6,11 @@ import { CqrsError, ErrorCode, type ErrorMetadata } from "@zudojs/errors";
  * `instanceof CqrsError` matches across both packages.
  */
 export { CqrsError };
+/**
+ * Thrown by `unwrapCommandResult` / `unwrapQueryResult` for a failed
+ * result. Owned by `@zudojs/errors` and re-exported here.
+ */
+export { CommandFailedError, QueryFailedError } from "@zudojs/errors";
 /**
  * Thrown when a CQRS request is invalid.
  *

package/dist/cqrsErrors/cqrsError.base.js

@@ -6,6 +6,11 @@ import { BaseError, CqrsError, ErrorCategory, ErrorCode, ErrorSeverity, } from "
  * `instanceof CqrsError` matches across both packages.
  */
 export { CqrsError };
+/**
+ * Thrown by `unwrapCommandResult` / `unwrapQueryResult` for a failed
+ * result. Owned by `@zudojs/errors` and re-exported here.
+ */
+export { CommandFailedError, QueryFailedError } from "@zudojs/errors";
 /**
  * Thrown when a CQRS request is invalid.
  *

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

@@ -46,7 +46,11 @@ export declare function isSuccessfulQueryResult<TResult, TQuery extends Query =
  */
 export declare function isFailedQueryResult<TResult, TQuery extends Query = Query>(result: QueryResult<TResult, TQuery>): boolean;
 /**
- * Returns the underlying query result value.
+ * Returns the value of a successful query result.
+ *
+ * @throws {QueryFailedError} when the result's status is `"failure"`. The
+ *   failure payload is on `error.failure` (and `error.cause`). Before 1.2
+ *   the payload was returned as if it were the query's value.
  */
 export declare function unwrapQueryResult<TResult, TQuery extends Query = Query>(result: QueryResult<TResult, TQuery>): TResult;
 /**

package/dist/query/queryResult.type.js

@@ -1,3 +1,4 @@
+import { QueryFailedError } from "@zudojs/errors";
 /**
  * Creates a successful query result.
  */
@@ -54,9 +55,16 @@ export function isFailedQueryResult(result) {
     return result.status === "failure";
 }
 /**
- * Returns the underlying query result value.
+ * Returns the value of a successful query result.
+ *
+ * @throws {QueryFailedError} when the result's status is `"failure"`. The
+ *   failure payload is on `error.failure` (and `error.cause`). Before 1.2
+ *   the payload was returned as if it were the query's value.
  */
 export function unwrapQueryResult(result) {
+    if (result.status === "failure") {
+        throw new QueryFailedError(String(result.queryType), result.result);
+    }
     return result.result;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/cqrs",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Command Query Responsibility Segregation (CQRS) primitives for separating read and write operations.",
   "license": "MIT",
   "author": {
@@ -25,13 +25,13 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/events": "1.1.0",
-    "@zudojs/middleware": "1.0.2"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/events": "1.3.0",
+    "@zudojs/middleware": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -45,7 +45,7 @@
     "commands",
     "queries"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-cqrs",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },