@shirudo/ddd-kit 1.3.0 → 2.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @shirudo/ddd-kit
 
-Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canonical building blocks (Value Objects, Entities, Aggregate Roots, Domain Events, Repositories, and CQRS handlers) without a framework or runtime lock-in. ESM-only; runs on Node 18+, Cloudflare Workers, Vercel Edge, Deno, and Bun.
+Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canonical building blocks (Value Objects, Entities, Aggregate Roots, Domain Events, Repositories, and CQRS handlers) without a framework or runtime lock-in. ESM-only; runs on Node 20+, Cloudflare Workers, Vercel Edge, Deno, and Bun.
 
-> **Stable: 1.0**
+> **Stable: 2.1**
 >
 > The public API is stable and follows [Semantic Versioning](https://semver.org/). Breaking changes bump the major and ship with a migration path in the [CHANGELOG](https://github.com/shi-rudo/ddd-kit-ts/blob/main/CHANGELOG.md).
 
@@ -15,11 +15,13 @@ Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canon
 - **Entities:** identity + lifecycle, with collection helpers branded by `Id<Tag>`.
 - **Aggregate Roots:** state-stored (`AggregateRoot`) and event-sourced (`EventSourcedAggregate`), with optimistic-concurrency versioning.
 - **Domain Events:** typed, deeply frozen, carry metadata for traceability and schema evolution.
+- **Domain State Machine:** finite, named domain states with typed context, guards, reducers, terminal states, and value outputs for aggregate lifecycles and process managers.
 - **Repositories:** technology-agnostic persistence ports with an Identity-Map contract and OCC.
 - **CQRS:** zero-config in-memory `CommandBus` / `QueryBus`, plus `CommandHandler` / `QueryHandler` types for external brokers.
 - **Unit of Work:** opt-in `UnitOfWork` facade with tx-bound repositories, repository-side enrollment, a per-operation Identity Map, and aggregate-level dirty tracking (`changedKeys` / `hasChanges`) for partial writes. Honestly speaking: a transaction coordinator with registration and Identity Map; writes stay explicit by design (no auto-flush).
 - **Outbox:** `withCommit` harvests pending events inside the transaction, stamps them with the aggregate's commit version, and publishes them atomically.
-- **Repository contract tests:** `@shirudo/ddd-kit/testing` ships the suite every adapter must pass: OCC is a testable contract, not a documented pattern.
+- **Event Store:** `EventStore` port with expectedVersion-guarded appends and snapshot catch-up reads, plus `InMemoryEventStore` as the reference implementation.
+- **Repository contract tests:** `@shirudo/ddd-kit/testing` ships the suites (state-stored and event-sourced) every adapter must pass: OCC is a testable contract, not a documented pattern.
 - **Result-first boundary:** a typed error hierarchy on [`@shirudo/base-error`](https://www.npmjs.com/package/@shirudo/base-error) and `Result` from [`@shirudo/result`](https://www.npmjs.com/package/@shirudo/result); `voValidated` collects field violations and renders RFC 9457 via the opt-in `@shirudo/ddd-kit/http` entry.
 
 ## Installation
@@ -58,6 +60,7 @@ Each building block has a dedicated guide. Start with [Design Decisions](https:/
 | Aggregate Roots, factories, reconstitution | [Aggregate Roots](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/aggregates.md) |
 | Event sourcing (`apply`, replay, snapshots) | [Event Sourcing](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/event-sourcing.md) |
 | Domain Events (`createDomainEvent`, metadata) | [Domain Events](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/domain-events.md) |
+| Domain State Machine (`DomainStateMachine`, `transitionDomainState`) | [Domain State Machine](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/domain-state-machine.md) |
 | Errors: throw vs Result, `ValidationError`, RFC 9457 | [Result vs Throw](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/result-vs-throw.md) |
 | Commands, queries, buses | [CQRS & Buses](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/cqrs-and-buses.md) |
 | Repositories, Identity Map, OCC | [Repository](https://github.com/shi-rudo/ddd-kit-ts/blob/main/docs/guide/repository.md) |

package/dist/{aggregate-BGdgvqKh.d.ts → aggregate-DFi6HlEh.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> {
 }
@@ -104,6 +106,29 @@ declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
     readonly eventType: string;
     constructor(eventType: string, cause?: unknown);
 }
+/**
+ * Thrown by `EventSourcedAggregate.loadFromHistory` and
+ * `restoreFromSnapshotWithEvents` when the replay target is not fresh:
+ * the aggregate carries unflushed `pendingEvents`, or (for
+ * `loadFromHistory`) an in-memory version that was never persisted.
+ * Replaying onto such an instance would `markRestored` a
+ * `persistedVersion` that counts unpersisted history: repository routing
+ * flips from INSERT to UPDATE (or appends with a wrong expected version)
+ * and harvested events would claim a version baseline the stream does
+ * not carry.
+ *
+ * Deliberately **not** a `DomainError` or `InfrastructureError` (same
+ * posture as {@link MissingHandlerError}): a deterministic programming
+ * bug in how the aggregate was constructed before replay. It propagates
+ * as a throw instead of riding the replay methods' `Result` channel, so
+ * a generic corrupted-stream handler cannot absorb it. Reconstitution
+ * belongs on a bare instance: construct the aggregate without
+ * factory-recorded events or prior mutations, then replay.
+ */
+declare class UnreplayableAggregateError extends BaseError<"UnreplayableAggregateError"> {
+    readonly aggregateId: string;
+    constructor(aggregateId: string, reason: string);
+}
 /**
  * Thrown by `withCommit` when an event harvested from an aggregate cannot
  * be safely committed: it is missing `aggregateId` / `aggregateType`
@@ -129,6 +154,34 @@ declare class EventHarvestError extends BaseError<"EventHarvestError"> {
     /** The `type` of the offending event, for programmatic routing. */
     eventType?: string | undefined);
 }
+/** Constructor options for {@link UnregisteredHandlerError}. */
+interface UnregisteredHandlerErrorOptions {
+    /** Which bus rejected the dispatch. */
+    readonly busKind: "command" | "query";
+    /** The message type no handler was registered for. */
+    readonly messageType: string;
+}
+/**
+ * Produced by the in-memory `CommandBus` / `QueryBus` when a message is
+ * dispatched for a type no handler was registered under: a wiring bug
+ * (typo in the type string, missing `register` call at bootstrap), not
+ * a domain or infrastructure failure.
+ *
+ * Extends `BaseError` directly (same crash-loud family as
+ * {@link MissingHandlerError}): a generic `catch (e instanceof
+ * DomainError)` handler must not absorb it. For 2.x compatibility the
+ * buses still deliver it through their error CHANNEL (`err(...)` via the
+ * `errorMapper`, so the default string channel keeps its exact message)
+ * rather than throwing; the named type exists so a typed error channel
+ * can route it explicitly instead of pattern-matching message strings.
+ * `QueryBus.executeUnsafe` throws it directly. v3 makes `execute` throw
+ * it too.
+ */
+declare class UnregisteredHandlerError extends BaseError<"UnregisteredHandlerError"> {
+    readonly busKind: "command" | "query";
+    readonly messageType: string;
+    constructor(options: UnregisteredHandlerErrorOptions);
+}
 /**
  * Thrown at the end of a `UnitOfWork.run` when an aggregate that was
  * loaded into the identity map during the operation carries unflushed
@@ -188,10 +241,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 +271,46 @@ 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 on snapshot restore (`restoreFromSnapshot`,
+ * `restoreFromSnapshotWithEvents`) when the stored snapshot carries a
+ * different schema version than the aggregate's declared
+ * `snapshotSchemaVersion` and no `migrateSnapshotState` override handles
+ * the upgrade. Without the check, a snapshot written against an older
+ * `TSnapshotState` shape would surface as an undefined-field crash on
+ * the first method call after a much later restore.
+ *
+ * `InfrastructureError` because the storage boundary served outdated
+ * data; the schema evolving past stored snapshots is an expected
+ * lifecycle event, not a programming bug. NOT retryable: the recovery
+ * is a code path, not a repeat. Either override `migrateSnapshotState`
+ * on the aggregate (upgrade old shapes in place), or catch this error
+ * in the repository, discard the snapshot, and refold from the full
+ * event stream / reload from the source of truth.
+ */
+interface SnapshotSchemaMismatchErrorOptions {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedSchemaVersion: number;
+    readonly actualSchemaVersion: number;
+}
+declare class SnapshotSchemaMismatchError extends InfrastructureError<"SnapshotSchemaMismatchError"> {
+    readonly aggregateType: string;
+    readonly aggregateId: string;
+    readonly expectedSchemaVersion: number;
+    readonly actualSchemaVersion: number;
+    constructor(options: SnapshotSchemaMismatchErrorOptions);
 }
 /**
  * Thrown by `IRepository.save()` when the aggregate's expected version
@@ -235,18 +330,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 +366,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";
@@ -333,62 +435,6 @@ declare function withEventIdFactory<T>(factory: EventIdFactory, fn: () => T): T;
  * Intended for use in test `afterEach` hooks.
  */
 declare function resetEventIdFactory(): void;
-/**
- * Clock function producing a fresh `Date` for each call. The library
- * defaults to `() => new Date()`; override globally via `setClockFactory`
- * for deterministic event-sourcing tests, time-travel debugging, or any
- * scenario where `occurredAt` must be reproducible.
- */
-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):
- *
- * ```ts
- * import { setClockFactory } from "@shirudo/ddd-kit";
- *
- * setClockFactory(() => new Date("2026-01-01T00:00:00Z"));
- * ```
- *
- * The per-call `options.occurredAt` override always wins over this
- * factory. Symmetric to `setEventIdFactory`.
- *
- * Module-scoped: see {@link setEventIdFactory} for the global-state
- * caveats. For test isolation prefer {@link withClockFactory}; for
- * multi-tenant request isolation prefer the per-call
- * `options.occurredAt`.
- */
-declare function setClockFactory(factory: ClockFactory): void;
-/**
- * Scoped variant of {@link setClockFactory}: installs `factory`, runs
- * `fn`, then restores the previous factory in a `finally` block.
- * Synchronous-only, with the same constraints (and same runtime thenable
- * guard) as {@link withEventIdFactory}.
- *
- * **When to prefer the per-call `options.occurredAt` instead.** Same
- * trade-off as {@link withEventIdFactory}: passing `{ occurredAt }`
- * to `createDomainEvent` is the strongest isolation for single-event
- * cases. The scoped helper is for events constructed deep inside
- * domain methods where threading an explicit timestamp is awkward.
- *
- * @example
- * ```ts
- * it("stamps events with a fixed clock", () => {
- *   const fixed = new Date("2026-01-01T00:00:00Z");
- *   withClockFactory(() => fixed, () => {
- *     const e = createDomainEvent("X", { v: 1 });
- *     expect(e.occurredAt).toEqual(fixed);
- *   });
- * });
- * ```
- */
-declare function withClockFactory<T>(factory: ClockFactory, fn: () => T): T;
-/**
- * Restores the default clock factory (`() => new Date()`).
- * Intended for use in test `afterEach` hooks.
- */
-declare function resetClockFactory(): void;
 /**
  * Metadata associated with a domain event for traceability and correlation.
  * Used in event-driven architectures to track event flow across services.
@@ -492,11 +538,16 @@ interface DomainEvent<T extends string, P = void> {
      * `CreateDomainEventOptions.aggregateVersion`; a pre-set value is
      * never overwritten.
      *
-     * Consumers use it for ordering ("apply projections up to aggregate
-     * version N"), idempotency watermarks, debugging, and integration
-     * logs. Optional at the type level: events created outside an
-     * aggregate (system/integration events) and events from older kit
-     * versions don't carry it.
+     * Consumers use it for cross-commit ordering and debugging. It is NOT
+     * a per-event idempotency key: all events of one commit share the
+     * stamp, so a position cursor keyed on it alone would silently skip
+     * every event after the first within a commit (e.g. after a crash
+     * between two same-version events). Dedup keys belong on `eventId`;
+     * as a watermark this value is per-commit only (advance it after
+     * processing ALL events of that version; see the outbox guide).
+     * Optional at the type level: events created outside an aggregate
+     * (system/integration events) and events from older kit versions
+     * don't carry it.
      */
     aggregateVersion?: number;
     /**
@@ -555,6 +606,14 @@ interface CreateDomainEventOptions {
  * Creates a domain event with default values.
  * Sets occurredAt to current date and version to 1 if not provided.
  *
+ * **Input ownership.** The event is deeply frozen, and `payload` and
+ * `metadata` are deep-cloned first, so the caller's own objects are never
+ * frozen in place and later mutation of them does not bleed into the
+ * event (same contract as `vo()`). The clone follows the plain-data event
+ * contract via `structuredClone`: functions, Promise, and WeakMap/WeakSet
+ * values throw a `TypeError`; symbol-keyed properties are not carried
+ * over.
+ *
  * **For aggregate-internal events, prefer `this.recordEvent(...)` on
  * `AggregateRoot` / `EventSourcedAggregate`.** That helper auto-injects
  * `aggregateId` (from `this.id`) and `aggregateType` (from the
@@ -583,20 +642,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.
@@ -640,15 +685,25 @@ interface AggregateSnapshot<TState> {
     /**
      * The state of the aggregate at the time of the snapshot.
      */
-    state: TState;
+    readonly state: TState;
     /**
      * The version of the aggregate when the snapshot was taken.
      */
-    version: Version;
+    readonly version: Version;
     /**
      * Timestamp when the snapshot was created.
      */
-    snapshotAt: Date;
+    readonly snapshotAt: Date;
+    /**
+     * Schema version of the SHAPE of `state` (the aggregate's declared
+     * `snapshotSchemaVersion`), stamped by `createSnapshot`. Distinct from
+     * {@link version}, which counts mutations: this field says "which
+     * shape does the stored state have", so a restore can detect a
+     * snapshot written against an older `TSnapshotState` and migrate or
+     * discard it instead of crashing later. Optional: absent on snapshots
+     * written by older kit versions, which restore treats as schema `1`.
+     */
+    readonly schemaVersion?: number;
 }
 /**
  * Public contract every Aggregate Root satisfies. Implemented by
@@ -713,4 +768,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, SnapshotSchemaMismatchError as S, UnenrolledChangesError as U, type Version as V, type Id as a, type AggregateSnapshot as b, type IEventSourcedAggregate as c, InfrastructureError as d, copyMetadata as e, createDomainEvent as f, type DomainEvent as g, type EventMetadata as h, setEventIdFactory as i, AggregateDeletedError as j, AggregateNotFoundError as k, type AggregateNotFoundErrorOptions as l, mergeMetadata as m, ConcurrencyConflictError as n, type ConcurrencyConflictErrorOptions as o, DuplicateAggregateError as p, type DuplicateAggregateErrorOptions as q, resetEventIdFactory as r, sameVersion as s, EventHarvestError as t, type SnapshotSchemaMismatchErrorOptions as u, UnregisteredHandlerError as v, withEventIdFactory as w, type UnregisteredHandlerErrorOptions as x, UnreplayableAggregateError 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"]}