@shirudo/ddd-kit 1.3.0 → 2.0.0

package/dist/{aggregate-BGdgvqKh.d.ts → aggregate-CePTINEt.d.ts}

@@ -63,8 +63,10 @@ interface IdGenerator<Tag extends string> {
  * subclass: the kit can't know your invariants.
  *
  * Extends `BaseError<Name>`; see `@shirudo/base-error` for the inherited
- * surface (timestamps, cause chains, `toJSON()`, `getUserMessage()`,
- * `isRetryable`, …).
+ * surface (timestamps, cause chains, `toJSON()`, `isRetryable`, …). For
+ * client-safe / localized messages, project errors through the opt-in
+ * `@shirudo/base-error/presentation` subpath at the boundary; the technical
+ * core deliberately carries no user-facing message.
  */
 declare abstract class DomainError<Name extends string = string> extends BaseError<Name> {
 }
@@ -188,10 +190,16 @@ declare class AggregateDeletedError extends BaseError<"AggregateDeletedError"> {
  *
  * Not retryable: retrying won't make the row appear.
  */
+interface AggregateNotFoundErrorOptions {
+    readonly aggregateType: string;
+    readonly id: string;
+    /** Optional lower-level error to preserve in the cause chain. */
+    readonly cause?: unknown;
+}
 declare class AggregateNotFoundError extends InfrastructureError<"AggregateNotFoundError"> {
     readonly aggregateType: string;
     readonly id: string;
-    constructor(aggregateType: string, id: string, cause?: unknown);
+    constructor(options: AggregateNotFoundErrorOptions);
 }
 /**
  * Thrown by a repository's `save()` INSERT path when a row with the
@@ -212,10 +220,16 @@ declare class AggregateNotFoundError extends InfrastructureError<"AggregateNotFo
  * idempotency-key flows load the existing aggregate and treat the
  * request as already-applied.
  */
+interface DuplicateAggregateErrorOptions {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    /** Optional driver-level error to preserve in the cause chain. */
+    readonly cause?: unknown;
+}
 declare class DuplicateAggregateError extends InfrastructureError<"DuplicateAggregateError"> {
     readonly aggregateType: string;
     readonly aggregateId: string;
-    constructor(aggregateType: string, aggregateId: string, cause?: unknown);
+    constructor(options: DuplicateAggregateErrorOptions);
 }
 /**
  * Thrown by `IRepository.save()` when the aggregate's expected version
@@ -235,18 +249,26 @@ declare class DuplicateAggregateError extends InfrastructureError<"DuplicateAggr
  * rule) detects the race. Marks itself as `retryable: true` so the
  * `isRetryable` predicate from `@shirudo/base-error` picks it up.
  */
-declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyConflictError"> {
+interface ConcurrencyConflictErrorOptions {
     readonly aggregateType: string;
     readonly aggregateId: string;
     readonly expectedVersion: number;
     readonly actualVersion: number;
+    /** Optional driver-level error to preserve in the cause chain. */
+    readonly cause?: unknown;
+}
+declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyConflictError"> {
     /**
      * Marks this error as retryable so `isRetryable(err)` returns
      * true. The canonical OCC pattern is to reload the aggregate, re-apply
      * the use case, and retry on this exception.
      */
     readonly retryable: true;
-    constructor(aggregateType: string, aggregateId: string, expectedVersion: number, actualVersion: number, cause?: unknown);
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    constructor(options: ConcurrencyConflictErrorOptions);
 }
 
 /**
@@ -263,9 +285,8 @@ declare class ConcurrencyConflictError extends InfrastructureError<"ConcurrencyC
  */
 type EventIdFactory = () => string;
 /**
- * Replaces the global event-id factory used by `createDomainEvent` and
- * `createDomainEventWithMetadata`. Call once during application bootstrap,
- * for example:
+ * Replaces the global event-id factory used by `createDomainEvent`. Call
+ * once during application bootstrap, for example:
  *
  * ```ts
  * import { ulid } from "ulid";
@@ -341,9 +362,8 @@ declare function resetEventIdFactory(): void;
  */
 type ClockFactory = () => Date;
 /**
- * Replaces the global clock factory used by `createDomainEvent` and
- * `createDomainEventWithMetadata`. Call once during application bootstrap
- * (or per-test in deterministic test suites):
+ * Replaces the global clock factory used by `createDomainEvent`. Call once
+ * during application bootstrap (or per-test in deterministic test suites):
  *
  * ```ts
  * import { setClockFactory } from "@shirudo/ddd-kit";
@@ -583,20 +603,6 @@ interface CreateDomainEventOptions {
  */
 declare function createDomainEvent<T extends string>(type: T, payload?: undefined, options?: CreateDomainEventOptions): DomainEvent<T, void>;
 declare function createDomainEvent<T extends string, P>(type: T, payload: P, options?: CreateDomainEventOptions): DomainEvent<T, P>;
-/**
- * Creates a domain event with metadata for traceability.
- * Convenience function for creating events with correlation and causation IDs.
- *
- * @example
- * ```typescript
- * const event = createDomainEventWithMetadata(
- *   "OrderCreated",
- *   { orderId: "123" },
- *   { correlationId: "corr-123", causationId: "cmd-456", userId: "user-789" }
- * );
- * ```
- */
-declare function createDomainEventWithMetadata<T extends string, P>(type: T, payload: P, metadata: EventMetadata, options?: Omit<CreateDomainEventOptions, "metadata">): DomainEvent<T, P>;
 /**
  * Copies metadata from a source event to a new event.
  * Useful for maintaining correlation chains in event-driven architectures.
@@ -713,4 +719,4 @@ declare function sameVersion<TId extends Id<string>>(a: {
     version: Version;
 }): boolean;
 
-export { type AnyDomainEvent as A, type CreateDomainEventOptions as C, DomainError as D, type EventIdFactory as E, type IAggregateRoot as I, MissingHandlerError as M, UnenrolledChangesError as U, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, setEventIdFactory as e, type ClockFactory as f, setClockFactory as g, withClockFactory as h, resetClockFactory as i, type EventMetadata as j, type DomainEvent as k, createDomainEvent as l, createDomainEventWithMetadata as m, copyMetadata as n, mergeMetadata as o, EventHarvestError as p, AggregateDeletedError as q, resetEventIdFactory as r, sameVersion as s, AggregateNotFoundError as t, DuplicateAggregateError as u, ConcurrencyConflictError as v, withEventIdFactory as w, type IdGenerator as x };
+export { type AnyDomainEvent as A, type CreateDomainEventOptions as C, DomainError as D, type EventIdFactory as E, type IAggregateRoot as I, MissingHandlerError as M, UnenrolledChangesError as U, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, setEventIdFactory as e, type ClockFactory as f, setClockFactory as g, withClockFactory as h, resetClockFactory as i, type EventMetadata as j, type DomainEvent as k, createDomainEvent as l, copyMetadata as m, mergeMetadata as n, EventHarvestError as o, AggregateDeletedError as p, type AggregateNotFoundErrorOptions as q, resetEventIdFactory as r, sameVersion as s, AggregateNotFoundError as t, type DuplicateAggregateErrorOptions as u, DuplicateAggregateError as v, withEventIdFactory as w, type ConcurrencyConflictErrorOptions as x, ConcurrencyConflictError as y, type IdGenerator as z };

package/dist/http.d.ts

@@ -1,31 +1,54 @@
-import { ValidationError, ProblemDetailsOptions, ProblemDetails } from '@shirudo/base-error';
+import { ValidationError } from '@shirudo/base-error';
+import { ProblemDetailsExtensions, ProblemDetails } from '@shirudo/base-error/problem-details';
 
 /** Extension member that carries the collected field issues. */
 type ValidationProblemMember = "errors" | "invalid-params";
 /**
- * Options for {@link toProblemDetails}. Mirrors base-error's
- * `ProblemDetailsOptions` but takes over the `extensions` member to attach the
- * collected field issues, and adds {@link member} to choose the wire key.
+ * Options for {@link toProblemDetails}: the standard RFC 9457 members the
+ * boundary may set, plus {@link member} to choose the wire key for the issues
+ * and {@link extensions} for extra public members merged alongside them.
  */
-interface ValidationProblemOptions extends Omit<ProblemDetailsOptions, "extensions"> {
+interface ValidationProblemOptions {
+    /** URI reference identifying the problem type. Defaults to `"about:blank"`. */
+    type?: string;
+    /** Short, human-readable summary. Default `"Validation Failed"`. */
+    title?: string;
+    /** HTTP status code. Default `422`. */
+    status?: number;
+    /** Human-readable explanation specific to this occurrence. */
+    detail?: string;
+    /** URI reference identifying this specific occurrence. */
+    instance?: string;
     /**
      * Extension member that carries the field issues. Default `"errors"`
      * (`{ message, path, code?, pointer? }` entries). RFC 9457 does not
      * standardize a multi-error member; `errors` is the common convention.
      */
     member?: ValidationProblemMember;
-    /** Extra public extension members merged alongside the issues. */
-    extensions?: Record<string, unknown>;
+    /**
+     * Extra public extension members merged alongside the issues. JSON-safe
+     * by contract (RFC 9457 bodies must serialize); a trace id, for example,
+     * is passed here, not as a recognized top-level field.
+     */
+    extensions?: ProblemDetailsExtensions;
 }
 /**
  * Projects a base-error {@link ValidationError} to an RFC 9457 Problem Details
  * object with the collected field issues attached under an extension member.
+ * The return type is base-error's own
+ * {@link ProblemDetails} (from `@shirudo/base-error/problem-details`), so the
+ * RFC 9457 shape stays a single source of truth across the ecosystem.
  *
- * base-error is **safe by default**: `ValidationError.toProblemDetails()` does
- * not expose the issues on its own: they only cross to a client through the
- * `publicIssues()` whitelist. This helper performs that explicit projection and
+ * base-error is **safe by default**: the issues only cross to a client through
+ * the `publicIssues()` whitelist (`{ message, path, code?, pointer? }`, never
+ * raw validator extras). This helper performs that explicit projection and
  * applies sensible validation defaults (`422`, `"Validation Failed"`), so the
- * common boundary case is a one-liner instead of a footgun.
+ * common boundary case is a one-liner instead of a footgun. The full-fidelity
+ * issues remain available for observability via `error.toLogObject()`.
+ *
+ * For the general error-to-Problem-Details mapping (a public-code catalog with
+ * per-code `type` / `status`), use base-error's `defineProblemDetailsAdapter`
+ * over a `PublicErrorView`. This helper is the narrow validation shortcut.
  *
  * This is a presentation/transport concern and ships from the opt-in
  * `@shirudo/ddd-kit/http` entry point: the core kit stays transport-free.
@@ -37,10 +60,10 @@ interface ValidationProblemOptions extends Omit<ProblemDetailsOptions, "extensio
  * if (result.isErr()) {
  *   return Response.json(toProblemDetails(result.error), { status: 422 });
  * }
- * // → { type, title: "Validation Failed", status: 422,
+ * // → { type: "about:blank", title: "Validation Failed", status: 422,
  * //     errors: [{ message: "must be a valid email", path: ["email"], pointer: "email" }] }
  * ```
  */
-declare function toProblemDetails(error: ValidationError, options?: ValidationProblemOptions): ProblemDetails;
+declare function toProblemDetails(error: ValidationError, options?: ValidationProblemOptions): ProblemDetails<never, ProblemDetailsExtensions>;
 
 export { type ValidationProblemMember, type ValidationProblemOptions, toProblemDetails };

package/dist/http.js

@@ -3,13 +3,21 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 
 // src/http/problem-details.ts
 function toProblemDetails(error, options = {}) {
-  const { member = "errors", extensions, ...rest } = options;
-  return error.toProblemDetails({
-    title: "Validation Failed",
-    status: 422,
-    ...rest,
-    extensions: { ...extensions, [member]: error.publicIssues() }
-  });
+  const {
+    member = "errors",
+    extensions,
+    type = "about:blank",
+    title = "Validation Failed",
+    status = 422,
+    detail,
+    instance
+  } = options;
+  const problem = { type, title, status };
+  if (detail !== void 0) problem.detail = detail;
+  if (instance !== void 0) problem.instance = instance;
+  if (extensions) Object.assign(problem, extensions);
+  problem[member] = error.publicIssues();
+  return problem;
 }
 __name(toProblemDetails, "toProblemDetails");
 

package/dist/http.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/http/problem-details.ts"],"names":[],"mappings":";;;;AAkDO,SAAS,gBAAA,CACf,KAAA,EACA,OAAA,GAAoC,EAAC,EACpB;AACjB,EAAA,MAAM,EAAE,MAAA,GAAS,QAAA,EAAU,UAAA,EAAY,GAAG,MAAK,GAAI,OAAA;AACnD,EAAA,OAAO,MAAM,gBAAA,CAAiB;AAAA,IAC7B,KAAA,EAAO,mBAAA;AAAA,IACP,MAAA,EAAQ,GAAA;AAAA,IACR,GAAG,IAAA;AAAA,IACH,UAAA,EAAY,EAAE,GAAG,UAAA,EAAY,CAAC,MAAM,GAAG,KAAA,CAAM,YAAA,EAAa;AAAE,GAC5D,CAAA;AACF;AAXgB,MAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA","file":"http.js","sourcesContent":["import type {\n\tProblemDetails,\n\tProblemDetailsOptions,\n\tValidationError,\n} from \"@shirudo/base-error\";\n\n/** Extension member that carries the collected field issues. */\nexport type ValidationProblemMember = \"errors\" | \"invalid-params\";\n\n/**\n * Options for {@link toProblemDetails}. Mirrors base-error's\n * `ProblemDetailsOptions` but takes over the `extensions` member to attach the\n * collected field issues, and adds {@link member} to choose the wire key.\n */\nexport interface ValidationProblemOptions\n\textends Omit<ProblemDetailsOptions, \"extensions\"> {\n\t/**\n\t * Extension member that carries the field issues. Default `\"errors\"`\n\t * (`{ message, path, code?, pointer? }` entries). RFC 9457 does not\n\t * standardize a multi-error member; `errors` is the common convention.\n\t */\n\tmember?: ValidationProblemMember;\n\t/** Extra public extension members merged alongside the issues. */\n\textensions?: Record<string, unknown>;\n}\n\n/**\n * Projects a base-error {@link ValidationError} to an RFC 9457 Problem Details\n * object with the collected field issues attached under an extension member.\n *\n * base-error is **safe by default**: `ValidationError.toProblemDetails()` does\n * not expose the issues on its own: they only cross to a client through the\n * `publicIssues()` whitelist. This helper performs that explicit projection and\n * applies sensible validation defaults (`422`, `\"Validation Failed\"`), so the\n * common boundary case is a one-liner instead of a footgun.\n *\n * This is a presentation/transport concern and ships from the opt-in\n * `@shirudo/ddd-kit/http` entry point: the core kit stays transport-free.\n *\n * @example\n * ```ts\n * import { toProblemDetails } from \"@shirudo/ddd-kit/http\";\n *\n * if (result.isErr()) {\n *   return Response.json(toProblemDetails(result.error), { status: 422 });\n * }\n * // → { type, title: \"Validation Failed\", status: 422,\n * //     errors: [{ message: \"must be a valid email\", path: [\"email\"], pointer: \"email\" }] }\n * ```\n */\nexport function toProblemDetails(\n\terror: ValidationError,\n\toptions: ValidationProblemOptions = {},\n): ProblemDetails {\n\tconst { member = \"errors\", extensions, ...rest } = options;\n\treturn error.toProblemDetails({\n\t\ttitle: \"Validation Failed\",\n\t\tstatus: 422,\n\t\t...rest,\n\t\textensions: { ...extensions, [member]: error.publicIssues() },\n\t});\n}\n"]}
+{"version":3,"sources":["../src/http/problem-details.ts"],"names":[],"mappings":";;;;AAuEO,SAAS,gBAAA,CACf,KAAA,EACA,OAAA,GAAoC,EAAC,EACa;AAClD,EAAA,MAAM;AAAA,IACL,MAAA,GAAS,QAAA;AAAA,IACT,UAAA;AAAA,IACA,IAAA,GAAO,aAAA;AAAA,IACP,KAAA,GAAQ,mBAAA;AAAA,IACR,MAAA,GAAS,GAAA;AAAA,IACT,MAAA;AAAA,IACA;AAAA,GACD,GAAI,OAAA;AAEJ,EAAA,MAAM,OAAA,GAAmC,EAAE,IAAA,EAAM,KAAA,EAAO,MAAA,EAAO;AAC/D,EAAA,IAAI,MAAA,KAAW,MAAA,EAAW,OAAA,CAAQ,MAAA,GAAS,MAAA;AAC3C,EAAA,IAAI,QAAA,KAAa,MAAA,EAAW,OAAA,CAAQ,QAAA,GAAW,QAAA;AAC/C,EAAA,IAAI,UAAA,EAAY,MAAA,CAAO,MAAA,CAAO,OAAA,EAAS,UAAU,CAAA;AAIjD,EAAA,OAAA,CAAQ,MAAM,CAAA,GAAI,KAAA,CAAM,YAAA,EAAa;AAErC,EAAA,OAAO,OAAA;AACR;AAxBgB,MAAA,CAAA,gBAAA,EAAA,kBAAA,CAAA","file":"http.js","sourcesContent":["import type { ValidationError } from \"@shirudo/base-error\";\nimport type {\n\tProblemDetails,\n\tProblemDetailsExtensions,\n} from \"@shirudo/base-error/problem-details\";\n\n/** Extension member that carries the collected field issues. */\nexport type ValidationProblemMember = \"errors\" | \"invalid-params\";\n\n/**\n * Options for {@link toProblemDetails}: the standard RFC 9457 members the\n * boundary may set, plus {@link member} to choose the wire key for the issues\n * and {@link extensions} for extra public members merged alongside them.\n */\nexport interface ValidationProblemOptions {\n\t/** URI reference identifying the problem type. Defaults to `\"about:blank\"`. */\n\ttype?: string;\n\t/** Short, human-readable summary. Default `\"Validation Failed\"`. */\n\ttitle?: string;\n\t/** HTTP status code. Default `422`. */\n\tstatus?: number;\n\t/** Human-readable explanation specific to this occurrence. */\n\tdetail?: string;\n\t/** URI reference identifying this specific occurrence. */\n\tinstance?: string;\n\t/**\n\t * Extension member that carries the field issues. Default `\"errors\"`\n\t * (`{ message, path, code?, pointer? }` entries). RFC 9457 does not\n\t * standardize a multi-error member; `errors` is the common convention.\n\t */\n\tmember?: ValidationProblemMember;\n\t/**\n\t * Extra public extension members merged alongside the issues. JSON-safe\n\t * by contract (RFC 9457 bodies must serialize); a trace id, for example,\n\t * is passed here, not as a recognized top-level field.\n\t */\n\textensions?: ProblemDetailsExtensions;\n}\n\n/**\n * Projects a base-error {@link ValidationError} to an RFC 9457 Problem Details\n * object with the collected field issues attached under an extension member.\n * The return type is base-error's own\n * {@link ProblemDetails} (from `@shirudo/base-error/problem-details`), so the\n * RFC 9457 shape stays a single source of truth across the ecosystem.\n *\n * base-error is **safe by default**: the issues only cross to a client through\n * the `publicIssues()` whitelist (`{ message, path, code?, pointer? }`, never\n * raw validator extras). This helper performs that explicit projection and\n * applies sensible validation defaults (`422`, `\"Validation Failed\"`), so the\n * common boundary case is a one-liner instead of a footgun. The full-fidelity\n * issues remain available for observability via `error.toLogObject()`.\n *\n * For the general error-to-Problem-Details mapping (a public-code catalog with\n * per-code `type` / `status`), use base-error's `defineProblemDetailsAdapter`\n * over a `PublicErrorView`. This helper is the narrow validation shortcut.\n *\n * This is a presentation/transport concern and ships from the opt-in\n * `@shirudo/ddd-kit/http` entry point: the core kit stays transport-free.\n *\n * @example\n * ```ts\n * import { toProblemDetails } from \"@shirudo/ddd-kit/http\";\n *\n * if (result.isErr()) {\n *   return Response.json(toProblemDetails(result.error), { status: 422 });\n * }\n * // → { type: \"about:blank\", title: \"Validation Failed\", status: 422,\n * //     errors: [{ message: \"must be a valid email\", path: [\"email\"], pointer: \"email\" }] }\n * ```\n */\nexport function toProblemDetails(\n\terror: ValidationError,\n\toptions: ValidationProblemOptions = {},\n): ProblemDetails<never, ProblemDetailsExtensions> {\n\tconst {\n\t\tmember = \"errors\",\n\t\textensions,\n\t\ttype = \"about:blank\",\n\t\ttitle = \"Validation Failed\",\n\t\tstatus = 422,\n\t\tdetail,\n\t\tinstance,\n\t} = options;\n\n\tconst problem: Record<string, unknown> = { type, title, status };\n\tif (detail !== undefined) problem.detail = detail;\n\tif (instance !== undefined) problem.instance = instance;\n\tif (extensions) Object.assign(problem, extensions);\n\t// `PublicIssue.path` is `ReadonlyArray<PropertyKey>`, so the issue array is\n\t// not statically a `ProblemDetailsJsonValue`; the wire form only ever\n\t// carries string/number path segments, so this is JSON-safe in practice.\n\tproblem[member] = error.publicIssues();\n\n\treturn problem as ProblemDetails<never, ProblemDetailsExtensions>;\n}\n"]}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as Id, A as AnyDomainEvent, I as IAggregateRoot, V as Version, b as AggregateSnapshot, C as CreateDomainEventOptions, c as IEventSourcedAggregate, D as DomainError, d as InfrastructureError } from './aggregate-BGdgvqKh.js';
-export { q as AggregateDeletedError, t as AggregateNotFoundError, f as ClockFactory, v as ConcurrencyConflictError, k as DomainEvent, u as DuplicateAggregateError, p as EventHarvestError, E as EventIdFactory, j as EventMetadata, x as IdGenerator, M as MissingHandlerError, U as UnenrolledChangesError, n as copyMetadata, l as createDomainEvent, m as createDomainEventWithMetadata, o as mergeMetadata, i as resetClockFactory, r as resetEventIdFactory, s as sameVersion, g as setClockFactory, e as setEventIdFactory, h as withClockFactory, w as withEventIdFactory } from './aggregate-BGdgvqKh.js';
+import { a as Id, A as AnyDomainEvent, I as IAggregateRoot, V as Version, b as AggregateSnapshot, C as CreateDomainEventOptions, c as IEventSourcedAggregate, D as DomainError, d as InfrastructureError } from './aggregate-CePTINEt.js';
+export { p as AggregateDeletedError, t as AggregateNotFoundError, q as AggregateNotFoundErrorOptions, f as ClockFactory, y as ConcurrencyConflictError, x as ConcurrencyConflictErrorOptions, k as DomainEvent, v as DuplicateAggregateError, u as DuplicateAggregateErrorOptions, o as EventHarvestError, E as EventIdFactory, j as EventMetadata, z as IdGenerator, M as MissingHandlerError, U as UnenrolledChangesError, m as copyMetadata, l as createDomainEvent, n as mergeMetadata, i as resetClockFactory, r as resetEventIdFactory, s as sameVersion, g as setClockFactory, e as setEventIdFactory, h as withClockFactory, w as withEventIdFactory } from './aggregate-CePTINEt.js';
 import { Result } from '@shirudo/result';
 import { BaseError, ValidationError } from '@shirudo/base-error';
 import { DeepEqualExceptOptions } from './utils.js';
@@ -1006,6 +1006,8 @@ interface Command {
  *
  * @template C - The command type (must extend Command)
  * @template R - The result type
+ * @template E - The error channel type. Defaults to `string`; widen it (e.g.
+ *   to a `DomainError` union) to carry typed failures through the bus.
  *
  * @example
  * ```typescript
@@ -1040,7 +1042,7 @@ interface Command {
  * });
  * ```
  */
-type CommandHandler<C extends Command, R> = (cmd: C) => Promise<Result<R, string>>;
+type CommandHandler<C extends Command, R, E = string> = (cmd: C) => Promise<Result<R, E>>;
 
 /**
  * Type map for command types to their return types.
@@ -1059,6 +1061,30 @@ type CommandHandler<C extends Command, R> = (cmd: C) => Promise<Result<R, string
  * ```
  */
 type CommandTypeMap = Record<string, unknown>;
+/**
+ * Construction options for {@link CommandBus}.
+ *
+ * @template E - The error channel type of the bus.
+ */
+interface CommandBusOptions<E = string> {
+    /**
+     * Maps a thrown value (a handler that throws, or dispatch to an
+     * unregistered command type) into the bus's error channel `E`. Defaults to
+     * {@link describeThrown}, which renders any thrown value as a `string`.
+     * base-error's `toStructuredError` fits this slot directly when `E` is a
+     * `StructuredError`.
+     */
+    errorMapper?: (thrown: unknown) => E;
+}
+/**
+ * Constructor arguments for {@link CommandBus}. When `E` is the default
+ * `string`, options are optional (the built-in {@link describeThrown} mapper
+ * applies). When `E` is widened, an `errorMapper` is required, so a typed
+ * channel can never silently fall back to string values.
+ */
+type CommandBusArgs<E> = [E] extends [string] ? [options?: CommandBusOptions<E>] : [options: CommandBusOptions<E> & {
+    errorMapper: (thrown: unknown) => E;
+}];
 /**
  * Command Bus interface for dispatching commands to their handlers.
  * Provides a centralized way to execute commands with handler registration.
@@ -1083,18 +1109,18 @@ type CommandTypeMap = Record<string, unknown>;
  * // result: Result<unknown, string>
  * ```
  */
-interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
+interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap, E = string> {
     /**
      * Executes a command by dispatching it to the registered handler.
      * When a type map is provided, the return type is inferred from the command type.
      *
      * @param command - The command to execute
-     * @returns Result containing the success value or error message
+     * @returns Result containing the success value or an error of type `E`
      */
     execute<C extends Command & {
         type: keyof TMap & string;
-    }>(command: C): Promise<Result<TMap[C["type"]], string>>;
-    execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
+    }>(command: C): Promise<Result<TMap[C["type"]], E>>;
+    execute<C extends Command, R>(command: C): Promise<Result<R, E>>;
     /**
      * Registers a handler for a specific command type.
      *
@@ -1111,7 +1137,7 @@ interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
         type: K;
     } = Command & {
         type: K;
-    }>(commandType: K, handler: CommandHandler<C, TMap[K]>): void;
+    }>(commandType: K, handler: CommandHandler<C, TMap[K], E>): void;
 }
 /**
  * Simple in-memory command bus implementation.
@@ -1149,17 +1175,19 @@ interface ICommandBus<TMap extends CommandTypeMap = CommandTypeMap> {
  * const result = await bus.execute({ type: "CreateOrder", ... });
  * ```
  */
-declare class CommandBus<TMap extends CommandTypeMap = CommandTypeMap> implements ICommandBus<TMap> {
+declare class CommandBus<TMap extends CommandTypeMap = CommandTypeMap, E = string> implements ICommandBus<TMap, E> {
     private readonly handlers;
+    private readonly errorMapper;
+    constructor(...args: CommandBusArgs<E>);
     register<K extends keyof TMap & string, C extends Command & {
         type: K;
     } = Command & {
         type: K;
-    }>(commandType: K, handler: CommandHandler<C, TMap[K]>): void;
+    }>(commandType: K, handler: CommandHandler<C, TMap[K], E>): void;
     execute<C extends Command & {
         type: keyof TMap & string;
-    }>(command: C): Promise<Result<TMap[C["type"]], string>>;
-    execute<C extends Command, R>(command: C): Promise<Result<R, string>>;
+    }>(command: C): Promise<Result<TMap[C["type"]], E>>;
+    execute<C extends Command, R>(command: C): Promise<Result<R, E>>;
 }
 
 /**
@@ -2034,6 +2062,30 @@ declare class UnitOfWork<Evt extends AnyDomainEvent, TCtx, TRepos extends Record
  * ```
  */
 type QueryTypeMap = Record<string, unknown>;
+/**
+ * Construction options for {@link QueryBus}.
+ *
+ * @template E - The error channel type of the bus.
+ */
+interface QueryBusOptions<E = string> {
+    /**
+     * Maps a thrown value (a handler that throws, or dispatch to an
+     * unregistered query type) into the bus's error channel `E`. Defaults to
+     * {@link describeThrown}, which renders any thrown value as a `string`.
+     * base-error's `toStructuredError` fits this slot directly when `E` is a
+     * `StructuredError`.
+     */
+    errorMapper?: (thrown: unknown) => E;
+}
+/**
+ * Constructor arguments for {@link QueryBus}. When `E` is the default `string`,
+ * options are optional (the built-in {@link describeThrown} mapper applies).
+ * When `E` is widened, an `errorMapper` is required, so a typed channel can
+ * never silently fall back to string values.
+ */
+type QueryBusArgs<E> = [E] extends [string] ? [options?: QueryBusOptions<E>] : [options: QueryBusOptions<E> & {
+    errorMapper: (thrown: unknown) => E;
+}];
 /**
  * Query Bus interface for dispatching queries to their handlers.
  * Provides a centralized way to execute queries with handler registration.
@@ -2057,7 +2109,7 @@ type QueryTypeMap = Record<string, unknown>;
  * // result: Result<unknown, string>
  * ```
  */
-interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
+interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap, E = string> {
     /**
      * Executes a query by dispatching it to the registered handler.
      * When a type map is provided, the return type is inferred from the query type.
@@ -2067,8 +2119,8 @@ interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
      */
     execute<Q extends Query & {
         type: keyof TMap & string;
-    }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
-    execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
+    }>(query: Q): Promise<Result<TMap[Q["type"]], E>>;
+    execute<Q extends Query, R>(query: Q): Promise<Result<R, E>>;
     /**
      * Executes a query by dispatching it to the registered handler.
      * Throws an error if no handler is registered.
@@ -2135,8 +2187,10 @@ interface IQueryBus<TMap extends QueryTypeMap = QueryTypeMap> {
  * const result = await bus.execute({ type: "GetOrder", orderId: "123" });
  * ```
  */
-declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQueryBus<TMap> {
+declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap, E = string> implements IQueryBus<TMap, E> {
     private readonly handlers;
+    private readonly errorMapper;
+    constructor(...args: QueryBusArgs<E>);
     register<K extends keyof TMap & string, Q extends Query & {
         type: K;
     } = Query & {
@@ -2144,8 +2198,8 @@ declare class QueryBus<TMap extends QueryTypeMap = QueryTypeMap> implements IQue
     }>(queryType: K, handler: QueryHandler<Q, TMap[K]>): void;
     execute<Q extends Query & {
         type: keyof TMap & string;
-    }>(query: Q): Promise<Result<TMap[Q["type"]], string>>;
-    execute<Q extends Query, R>(query: Q): Promise<Result<R, string>>;
+    }>(query: Q): Promise<Result<TMap[Q["type"]], E>>;
+    execute<Q extends Query, R>(query: Q): Promise<Result<R, E>>;
     executeUnsafe<Q extends Query & {
         type: keyof TMap & string;
     }>(query: Q): Promise<TMap[Q["type"]]>;
@@ -2792,4 +2846,4 @@ declare abstract class ValueObject<T extends object> implements IValueObject<T>
  */
 declare function voValidated<T>(t: T, validate: (issues: ValidationError, value: T) => void, message?: string): Result<VO<T>, ValidationError>;
 
-export { type AggregateClass, type AggregateConfig, AggregateRoot, AggregateSnapshot, AnyDomainEvent, type Command, CommandBus, type CommandHandler, CommitError, CreateDomainEventOptions, DeepEqualExceptOptions, DomainError, Entity, type EventBus, EventBusImpl, type EventHandler, EventSourcedAggregate, IAggregateRoot, type ICommandBus, type IEntity, IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IUnitOfWorkRepository, type IValueObject, Id, type Identifiable, IdentityMap, InMemoryOutbox, InfrastructureError, NestedUnitOfWorkError, type OnceOptions, type Outbox, type OutboxRecord, type Query, QueryBus, type QueryHandler, type RepositoryFactories, type RetryPolicy, RetryingTransactionScope, RollbackError, type RunOptions, TransactionClosedError, type TransactionScope, type TransactionalOptions, UnitOfWork, type UnitOfWorkContext, type UnitOfWorkDeps, type UnitOfWorkSession, type VO, ValueObject, Version, computeBackoffDelay, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, removeEntityById, replaceEntityById, sameEntity, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withCommit };
+export { type AggregateClass, type AggregateConfig, AggregateRoot, AggregateSnapshot, AnyDomainEvent, type Command, CommandBus, type CommandBusOptions, type CommandHandler, CommitError, CreateDomainEventOptions, DeepEqualExceptOptions, DomainError, Entity, type EventBus, EventBusImpl, type EventHandler, EventSourcedAggregate, IAggregateRoot, type ICommandBus, type IEntity, IEventSourcedAggregate, type IQueryBus, type IQueryableRepository, type IRepository, type IUnitOfWorkRepository, type IValueObject, Id, type Identifiable, IdentityMap, InMemoryOutbox, InfrastructureError, NestedUnitOfWorkError, type OnceOptions, type Outbox, type OutboxRecord, type Query, QueryBus, type QueryBusOptions, type QueryHandler, type RepositoryFactories, type RetryPolicy, RetryingTransactionScope, RollbackError, type RunOptions, TransactionClosedError, type TransactionScope, type TransactionalOptions, UnitOfWork, type UnitOfWorkContext, type UnitOfWorkDeps, type UnitOfWorkSession, type VO, ValueObject, Version, computeBackoffDelay, deepFreeze, entityIds, findEntityById, freezeShallow, hasEntityId, removeEntityById, replaceEntityById, sameEntity, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withCommit };

package/dist/index.js

@@ -711,13 +711,6 @@ function createDomainEvent(type, payload, options) {
   return deepFreeze(event);
 }
 __name(createDomainEvent, "createDomainEvent");
-function createDomainEventWithMetadata(type, payload, metadata, options) {
-  return createDomainEvent(type, payload, {
-    ...options,
-    metadata
-  });
-}
-__name(createDomainEventWithMetadata, "createDomainEventWithMetadata");
 function copyMetadata(sourceEvent, additionalMetadata) {
   return {
     ...sourceEvent.metadata ?? {},
@@ -1483,52 +1476,38 @@ var AggregateDeletedError = class extends BaseError {
   }
 };
 var AggregateNotFoundError = class extends InfrastructureError {
-  constructor(aggregateType, id, cause) {
-    super(`Aggregate not found: ${aggregateType}(${id})`, cause, {
-      name: "AggregateNotFoundError"
-    });
-    this.aggregateType = aggregateType;
-    this.id = id;
-    this.withUserMessage(
-      `The requested ${aggregateType} could not be found.`
-    );
-  }
   static {
     __name(this, "AggregateNotFoundError");
   }
-};
-var DuplicateAggregateError = class extends InfrastructureError {
-  constructor(aggregateType, aggregateId, cause) {
+  aggregateType;
+  id;
+  constructor(options) {
     super(
-      `Duplicate aggregate: ${aggregateType}(${aggregateId}) already exists`,
-      cause,
-      { name: "DuplicateAggregateError" }
-    );
-    this.aggregateType = aggregateType;
-    this.aggregateId = aggregateId;
-    this.withUserMessage(
-      `This ${aggregateType} already exists. It may have been created by a concurrent request.`
+      `Aggregate not found: ${options.aggregateType}(${options.id})`,
+      options.cause,
+      { name: "AggregateNotFoundError" }
     );
+    this.aggregateType = options.aggregateType;
+    this.id = options.id;
   }
+};
+var DuplicateAggregateError = class extends InfrastructureError {
   static {
     __name(this, "DuplicateAggregateError");
   }
-};
-var ConcurrencyConflictError = class extends InfrastructureError {
-  constructor(aggregateType, aggregateId, expectedVersion, actualVersion, cause) {
+  aggregateType;
+  aggregateId;
+  constructor(options) {
     super(
-      `Concurrency conflict on ${aggregateType}(${aggregateId}): expected version ${expectedVersion}, actual ${actualVersion}`,
-      cause,
-      { name: "ConcurrencyConflictError" }
-    );
-    this.aggregateType = aggregateType;
-    this.aggregateId = aggregateId;
-    this.expectedVersion = expectedVersion;
-    this.actualVersion = actualVersion;
-    this.withUserMessage(
-      "This resource was updated by another request. Please reload and try again."
+      `Duplicate aggregate: ${options.aggregateType}(${options.aggregateId}) already exists`,
+      options.cause,
+      { name: "DuplicateAggregateError" }
     );
+    this.aggregateType = options.aggregateType;
+    this.aggregateId = options.aggregateId;
   }
+};
+var ConcurrencyConflictError = class extends InfrastructureError {
   static {
     __name(this, "ConcurrencyConflictError");
   }
@@ -1538,6 +1517,21 @@ var ConcurrencyConflictError = class extends InfrastructureError {
    * the use case, and retry on this exception.
    */
   retryable = true;
+  aggregateType;
+  aggregateId;
+  expectedVersion;
+  actualVersion;
+  constructor(options) {
+    super(
+      `Concurrency conflict on ${options.aggregateType}(${options.aggregateId}): expected version ${options.expectedVersion}, actual ${options.actualVersion}`,
+      options.cause,
+      { name: "ConcurrencyConflictError" }
+    );
+    this.aggregateType = options.aggregateType;
+    this.aggregateId = options.aggregateId;
+    this.expectedVersion = options.expectedVersion;
+    this.actualVersion = options.actualVersion;
+  }
 };
 
 // src/aggregate/event-sourced-aggregate.ts
@@ -1676,6 +1670,10 @@ var CommandBus = class {
     __name(this, "CommandBus");
   }
   handlers = /* @__PURE__ */ new Map();
+  errorMapper;
+  constructor(...args) {
+    this.errorMapper = args[0]?.errorMapper ?? describeThrown;
+  }
   register(commandType, handler) {
     if (this.handlers.has(commandType)) {
       throw new Error(
@@ -1687,12 +1685,16 @@ var CommandBus = class {
   async execute(command) {
     const handler = this.handlers.get(command.type);
     if (!handler) {
-      return err(`No handler registered for command type: ${command.type}`);
+      return err(
+        this.errorMapper(
+          new Error(`No handler registered for command type: ${command.type}`)
+        )
+      );
     }
     try {
       return await handler(command);
     } catch (error) {
-      return err(describeThrown(error));
+      return err(this.errorMapper(error));
     }
   }
 };
@@ -2165,6 +2167,10 @@ var QueryBus = class {
     __name(this, "QueryBus");
   }
   handlers = /* @__PURE__ */ new Map();
+  errorMapper;
+  constructor(...args) {
+    this.errorMapper = args[0]?.errorMapper ?? describeThrown;
+  }
   register(queryType, handler) {
     if (this.handlers.has(queryType)) {
       throw new Error(
@@ -2176,13 +2182,17 @@ var QueryBus = class {
   async execute(query) {
     const handler = this.handlers.get(query.type);
     if (!handler) {
-      return err(`No handler registered for query type: ${query.type}`);
+      return err(
+        this.errorMapper(
+          new Error(`No handler registered for query type: ${query.type}`)
+        )
+      );
     }
     try {
       const result = await handler(query);
       return ok(result);
     } catch (error) {
-      return err(describeThrown(error));
+      return err(this.errorMapper(error));
     }
   }
   async executeUnsafe(query) {
@@ -2428,6 +2438,6 @@ function voValidated(t, validate, message = "Validation failed") {
 }
 __name(voValidated, "voValidated");
 
-export { AggregateDeletedError, AggregateNotFoundError, AggregateRoot, CommandBus, CommitError, ConcurrencyConflictError, DomainError, DuplicateAggregateError, Entity, EventBusImpl, EventHarvestError, EventSourcedAggregate, IdentityMap, InMemoryOutbox, InfrastructureError, MissingHandlerError, NestedUnitOfWorkError, QueryBus, RetryingTransactionScope, RollbackError, TransactionClosedError, UnenrolledChangesError, UnitOfWork, ValueObject, computeBackoffDelay, copyMetadata, createDomainEvent, createDomainEventWithMetadata, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
+export { AggregateDeletedError, AggregateNotFoundError, AggregateRoot, CommandBus, CommitError, ConcurrencyConflictError, DomainError, DuplicateAggregateError, Entity, EventBusImpl, EventHarvestError, EventSourcedAggregate, IdentityMap, InMemoryOutbox, InfrastructureError, MissingHandlerError, NestedUnitOfWorkError, QueryBus, RetryingTransactionScope, RollbackError, TransactionClosedError, UnenrolledChangesError, UnitOfWork, ValueObject, computeBackoffDelay, copyMetadata, createDomainEvent, deepEqual, deepEqualExcept, deepFreeze, deepOmit, entityIds, findEntityById, freezeShallow, hasEntityId, mergeMetadata, removeEntityById, replaceEntityById, resetClockFactory, resetEventIdFactory, sameEntity, sameVersion, setClockFactory, setEventIdFactory, updateEntityById, vo, voEquals, voEqualsExcept, voValidated, voWithValidation, withClockFactory, withCommit, withEventIdFactory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map