@shirudo/ddd-kit 1.2.0 → 2.0.0

package/README.md

@@ -17,9 +17,9 @@ Composable TypeScript toolkit for tactical Domain-Driven Design. Ships the canon
 - **Domain Events:** typed, deeply frozen, carry metadata for traceability and schema evolution.
 - **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).
+- **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.
+- **Repository contract tests:** `@shirudo/ddd-kit/testing` ships the suite 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

package/dist/{aggregate-DclYgG_D.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> {
 }
@@ -104,6 +106,60 @@ declare class MissingHandlerError extends BaseError<"MissingHandlerError"> {
     readonly eventType: string;
     constructor(eventType: string, cause?: unknown);
 }
+/**
+ * Thrown by `withCommit` when an event harvested from an aggregate cannot
+ * be safely committed: it is missing `aggregateId` / `aggregateType`
+ * (downstream routing would break), or it carries a pre-set
+ * `aggregateVersion` AHEAD of the aggregate's commit version (a leaked or
+ * copied fixture that would advance consumer idempotency watermarks past
+ * real history). Both are programming bugs in how the aggregate recorded
+ * the event, deterministic, and fail identically on every retry.
+ *
+ * Deliberately **not** an {@link InfrastructureError} (same reasoning as
+ * {@link MissingHandlerError}): the failure happens after the work
+ * callback completed, but it is NOT transient. A `catch (e instanceof
+ * InfrastructureError)` retry handler, or a retrying `TransactionScope`,
+ * must NOT mask it or loop on it forever; it should crash loud so the
+ * recordEvent / createDomainEvent misuse surfaces in development. This is
+ * why `withCommit` throws it directly and `UnitOfWork.run` passes it
+ * through unchanged instead of wrapping it in `CommitError`.
+ */
+declare class EventHarvestError extends BaseError<"EventHarvestError"> {
+    /** The `type` of the offending event, for programmatic routing. */
+    readonly eventType?: string | undefined;
+    constructor(message: string, 
+    /** The `type` of the offending event, for programmatic routing. */
+    eventType?: string | undefined);
+}
+/**
+ * Thrown at the end of a `UnitOfWork.run` when an aggregate that was
+ * loaded into the identity map during the operation carries unflushed
+ * `pendingEvents` but was never enrolled (no `session.enrollSaved`, and
+ * not deleted). The almost-certain cause is a repository `save()` that
+ * forgot to call `enrollSaved`, or a use case that recorded events on a
+ * loaded aggregate and never saved it. Without this guard those events
+ * would be silently dropped: never harvested into the outbox, never
+ * published.
+ *
+ * Deliberately **not** an `InfrastructureError` (same posture as
+ * {@link MissingHandlerError}): a programming bug that must crash loud,
+ * not be absorbed by a generic infrastructure-error handler. The throw
+ * happens inside the transaction, so the unit of work rolls back and
+ * leaves no partial state.
+ *
+ * **Scope of the guard.** A best-effort runtime safety net, not a proof.
+ * It only sees aggregates the identity map knows about (those loaded via
+ * `getById`), and detects new events by comparing the pending-event COUNT
+ * at load against commit, which assumes the kit's append-only event model
+ * (so it cannot see events that were recorded and then cleared within the
+ * same run). A freshly *created* aggregate that was never enrolled is
+ * invisible to the kit. The repository contract test suite remains the
+ * full mitigation. See the Unit of Work guide.
+ */
+declare class UnenrolledChangesError extends BaseError<"UnenrolledChangesError"> {
+    readonly aggregateId: string;
+    constructor(aggregateId: string);
+}
 /**
  * Thrown when an aggregate that was deleted within the current unit of
  * work is saved or re-registered again in the same operation: by
@@ -134,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
@@ -158,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
@@ -172,7 +240,7 @@ declare class DuplicateAggregateError extends InfrastructureError<"DuplicateAggr
  *
  * **Retry means a FRESH unit of work** (a new `UnitOfWork.run()` /
  * `withCommit` invocation): reload, re-apply, save. Do NOT catch this
- * inside the same `run()` callback and continue — the failed aggregate
+ * inside the same `run()` callback and continue: the failed aggregate
  * is already enrolled (its events would be committed for a write that
  * never happened) and the identity map still serves the same stale
  * instance to any in-place "reload".
@@ -181,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);
 }
 
 /**
@@ -209,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";
@@ -287,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";
@@ -379,7 +453,7 @@ interface EventMetadata {
  * transport concerns the outbox needs (`aggregateId`, `aggregateType`,
  * `aggregateVersion`, `metadata`). That is the line: further transport
  * fields (partition keys, tenancy, schema URNs, …) belong in an outbox
- * envelope / `metadata`, not on the domain event — the next first-class
+ * envelope / `metadata`, not on the domain event: the next first-class
  * transport field forces an `OutboxMessage` envelope port instead.
  *
  * @template T - The event type name (e.g., "OrderCreated")
@@ -422,7 +496,7 @@ interface DomainEvent<T extends string, P = void> {
      * Required for safe schema migration in event-sourced systems.
      * Use 1 for the initial schema version.
      *
-     * **NOT the aggregate's version** — that is
+     * **NOT the aggregate's version**: that is
      * {@link aggregateVersion}. The two are deliberately distinct
      * fields: this one says "which shape does the payload have"
      * (upcasting), the other says "which state revision of the
@@ -435,7 +509,7 @@ interface DomainEvent<T extends string, P = void> {
      * `withCommit` at the harvest boundary (all events of one aggregate
      * in one commit share it; their relative order within the commit is
      * the harvest order), or set manually via
-     * `CreateDomainEventOptions.aggregateVersion` — a pre-set value is
+     * `CreateDomainEventOptions.aggregateVersion`; a pre-set value is
      * never overwritten.
      *
      * Consumers use it for ordering ("apply projections up to aggregate
@@ -486,8 +560,8 @@ interface CreateDomainEventOptions {
     version?: number;
     /**
      * Pre-set the producing aggregate's version (see
-     * `DomainEvent.aggregateVersion`). Normally left unset — `withCommit`
-     * stamps it at the harvest boundary with the commit version — but
+     * `DomainEvent.aggregateVersion`). Normally left unset (`withCommit`
+     * stamps it at the harvest boundary with the commit version), but
      * useful for replay fixtures and events constructed outside an
      * aggregate. A pre-set value is never overwritten by the harvest.
      */
@@ -529,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.
@@ -659,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, 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, AggregateDeletedError as p, AggregateNotFoundError as q, resetEventIdFactory as r, sameVersion as s, DuplicateAggregateError as t, ConcurrencyConflictError as u, type IdGenerator as v, withEventIdFactory as w };
+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"]}