@shirudo/ddd-kit 2.0.0 → 3.0.0-rc.10

package/dist/http.d.ts

@@ -1,69 +1,81 @@
-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";
+import { PublicIssue, ValidationError } from "@shirudo/base-error";
+import { ProblemDetailsResult, ToProblemContext } from "@shirudo/base-error/public-error";
+//#region src/presentation/http/problem-details.d.ts
+/** Details member carried by a {@link toProblemDetails} body. */
+interface ValidationProblemDetails {
+  /** The whitelisted field issues, straight from `publicIssues()`. */
+  readonly issues: readonly PublicIssue[];
+}
 /**
- * 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.
+ * Options for {@link toProblemDetails}: the transport members the boundary
+ * may set, plus {@link extensions} for extra public body members.
  */
-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. 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;
+interface ValidationProblemOptions<TExtensions extends object = Record<never, never>> {
+  /** 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;
+  /**
+   * Extra public extension members merged alongside the documented body
+   * members. Constrained by base-error's `toProblem` contract: JSON-safe,
+   * string-keyed, and free of the reserved member names, checked at
+   * compile time and re-validated at runtime (a colliding or
+   * non-JSON-safe set is dropped and recorded in `outcome.omitted`).
+   */
+  extensions?: ToProblemContext<TExtensions>["extensions"];
 }
 /**
- * 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**: 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. The full-fidelity
- * issues remain available for observability via `error.toLogObject()`.
+ * The kit-named result of {@link toProblemDetails}: base-error's
+ * `ProblemDetailsResult` specialized to the validation shortcut. Exists so
+ * consumers can annotate boundaries from the kit entry alone; importing
+ * base-error stays an opt-in, never a prerequisite.
+ */
+type ValidationProblemResult<TExtensions extends object = Record<never, never>> = ProblemDetailsResult<ValidationProblemDetails, string, TExtensions>;
+/**
+ * Projects a base-error {@link ValidationError} to an RFC 9457 Problem
+ * Details result by delegating to base-error's `toProblem` transport stage:
+ * one pipeline, one wire profile, one hardening implementation. The body
+ * carries the error's public `code`, and the whitelisted issues ride under
+ * `details.issues` (`{ message, path, code?, pointer? }`, never raw
+ * validator extras), the same shape `toPublicErrorView` uses.
  *
- * 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.
+ * All of `toProblem`'s wire-safety guarantees apply: the body is deeply
+ * frozen with a null prototype (cannot carry or receive prototype
+ * pollution), every member is JSON-safe (a non-serializable value drops
+ * that member and records it in `result.outcome.omitted` instead of
+ * corrupting the wire), and extensions cannot collide with the reserved
+ * members. The result also carries the HTTP `status` and ready-made
+ * `headers`, so the boundary does not restate them.
  *
  * This is a presentation/transport concern and ships from the opt-in
  * `@shirudo/ddd-kit/http` entry point: the core kit stays transport-free.
+ * For catalog-driven mapping across ALL your public errors use
+ * base-error's `definePublicErrors` + `project` + `toProblem` directly;
+ * this helper is the narrow validation shortcut.
  *
  * @example
  * ```ts
  * import { toProblemDetails } from "@shirudo/ddd-kit/http";
  *
  * if (result.isErr()) {
- *   return Response.json(toProblemDetails(result.error), { status: 422 });
+ *   const problem = toProblemDetails(result.error);
+ *   return Response.json(problem.body, {
+ *     status: problem.status,
+ *     headers: problem.headers,
+ *   });
  * }
- * // → { type: "about:blank", title: "Validation Failed", status: 422,
- * //     errors: [{ message: "must be a valid email", path: ["email"], pointer: "email" }] }
+ * // body → { type: "about:blank", title: "Validation Failed", status: 422,
+ * //          code: "VALIDATION_FAILED",
+ * //          details: { issues: [{ message: "must be a valid email", ... }] } }
  * ```
  */
-declare function toProblemDetails(error: ValidationError, options?: ValidationProblemOptions): ProblemDetails<never, ProblemDetailsExtensions>;
-
-export { type ValidationProblemMember, type ValidationProblemOptions, toProblemDetails };
+declare function toProblemDetails<TExtensions extends object = Record<never, never>>(error: ValidationError, options?: ValidationProblemOptions<TExtensions>): ValidationProblemResult<TExtensions>;
+//#endregion
+export { ValidationProblemDetails, ValidationProblemOptions, ValidationProblemResult, toProblemDetails };
+//# sourceMappingURL=http.d.ts.map

package/dist/http.js

@@ -1,26 +1,60 @@
-var __defProp = Object.defineProperty;
-var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+import { toProblem } from "@shirudo/base-error/public-error";
 
-// src/http/problem-details.ts
+//#region src/presentation/http/problem-details.ts
+/**
+* Projects a base-error {@link ValidationError} to an RFC 9457 Problem
+* Details result by delegating to base-error's `toProblem` transport stage:
+* one pipeline, one wire profile, one hardening implementation. The body
+* carries the error's public `code`, and the whitelisted issues ride under
+* `details.issues` (`{ message, path, code?, pointer? }`, never raw
+* validator extras), the same shape `toPublicErrorView` uses.
+*
+* All of `toProblem`'s wire-safety guarantees apply: the body is deeply
+* frozen with a null prototype (cannot carry or receive prototype
+* pollution), every member is JSON-safe (a non-serializable value drops
+* that member and records it in `result.outcome.omitted` instead of
+* corrupting the wire), and extensions cannot collide with the reserved
+* members. The result also carries the HTTP `status` and ready-made
+* `headers`, so the boundary does not restate them.
+*
+* This is a presentation/transport concern and ships from the opt-in
+* `@shirudo/ddd-kit/http` entry point: the core kit stays transport-free.
+* For catalog-driven mapping across ALL your public errors use
+* base-error's `definePublicErrors` + `project` + `toProblem` directly;
+* this helper is the narrow validation shortcut.
+*
+* @example
+* ```ts
+* import { toProblemDetails } from "@shirudo/ddd-kit/http";
+*
+* if (result.isErr()) {
+*   const problem = toProblemDetails(result.error);
+*   return Response.json(problem.body, {
+*     status: problem.status,
+*     headers: problem.headers,
+*   });
+* }
+* // body → { type: "about:blank", title: "Validation Failed", status: 422,
+* //          code: "VALIDATION_FAILED",
+* //          details: { issues: [{ message: "must be a valid email", ... }] } }
+* ```
+*/
 function toProblemDetails(error, options = {}) {
-  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;
+	const { type = "about:blank", title = "Validation Failed", status = 422, detail, instance, extensions } = options;
+	return toProblem({
+		status,
+		type,
+		title
+	}, {
+		code: error.code,
+		details: { issues: error.publicIssues() }
+	}, {
+		detail,
+		instance,
+		extensions
+	});
 }
-__name(toProblemDetails, "toProblemDetails");
 
+//#endregion
 export { toProblemDetails };
-//# sourceMappingURL=http.js.map
 //# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -1 +1 @@
-{"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"]}
+{"version":3,"file":"http.js","names":[],"sources":["../src/presentation/http/problem-details.ts"],"sourcesContent":["// HTTP / transport presenters. Opt-in entry point (`@shirudo/ddd-kit/http`)\n// so the core kit stays free of transport concerns. Import only when you map\n// domain results to HTTP responses.\nimport type { PublicIssue, ValidationError } from \"@shirudo/base-error\";\nimport {\n\ttype ProblemDetailsResult,\n\ttype ToProblemContext,\n\ttoProblem,\n} from \"@shirudo/base-error/public-error\";\n\n/** Details member carried by a {@link toProblemDetails} body. */\nexport interface ValidationProblemDetails {\n\t/** The whitelisted field issues, straight from `publicIssues()`. */\n\treadonly issues: readonly PublicIssue[];\n}\n\n/**\n * Options for {@link toProblemDetails}: the transport members the boundary\n * may set, plus {@link extensions} for extra public body members.\n */\nexport interface ValidationProblemOptions<\n\tTExtensions extends object = Record<never, never>,\n> {\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 * Extra public extension members merged alongside the documented body\n\t * members. Constrained by base-error's `toProblem` contract: JSON-safe,\n\t * string-keyed, and free of the reserved member names, checked at\n\t * compile time and re-validated at runtime (a colliding or\n\t * non-JSON-safe set is dropped and recorded in `outcome.omitted`).\n\t */\n\textensions?: ToProblemContext<TExtensions>[\"extensions\"];\n}\n\n/**\n * The kit-named result of {@link toProblemDetails}: base-error's\n * `ProblemDetailsResult` specialized to the validation shortcut. Exists so\n * consumers can annotate boundaries from the kit entry alone; importing\n * base-error stays an opt-in, never a prerequisite.\n */\nexport type ValidationProblemResult<\n\tTExtensions extends object = Record<never, never>,\n> = ProblemDetailsResult<ValidationProblemDetails, string, TExtensions>;\n\n/**\n * Projects a base-error {@link ValidationError} to an RFC 9457 Problem\n * Details result by delegating to base-error's `toProblem` transport stage:\n * one pipeline, one wire profile, one hardening implementation. The body\n * carries the error's public `code`, and the whitelisted issues ride under\n * `details.issues` (`{ message, path, code?, pointer? }`, never raw\n * validator extras), the same shape `toPublicErrorView` uses.\n *\n * All of `toProblem`'s wire-safety guarantees apply: the body is deeply\n * frozen with a null prototype (cannot carry or receive prototype\n * pollution), every member is JSON-safe (a non-serializable value drops\n * that member and records it in `result.outcome.omitted` instead of\n * corrupting the wire), and extensions cannot collide with the reserved\n * members. The result also carries the HTTP `status` and ready-made\n * `headers`, so the boundary does not restate them.\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 * For catalog-driven mapping across ALL your public errors use\n * base-error's `definePublicErrors` + `project` + `toProblem` directly;\n * this helper is the narrow validation shortcut.\n *\n * @example\n * ```ts\n * import { toProblemDetails } from \"@shirudo/ddd-kit/http\";\n *\n * if (result.isErr()) {\n *   const problem = toProblemDetails(result.error);\n *   return Response.json(problem.body, {\n *     status: problem.status,\n *     headers: problem.headers,\n *   });\n * }\n * // body → { type: \"about:blank\", title: \"Validation Failed\", status: 422,\n * //          code: \"VALIDATION_FAILED\",\n * //          details: { issues: [{ message: \"must be a valid email\", ... }] } }\n * ```\n */\nexport function toProblemDetails<\n\tTExtensions extends object = Record<never, never>,\n>(\n\terror: ValidationError,\n\toptions: ValidationProblemOptions<TExtensions> = {},\n): ValidationProblemResult<TExtensions> {\n\tconst {\n\t\ttype = \"about:blank\",\n\t\ttitle = \"Validation Failed\",\n\t\tstatus = 422,\n\t\tdetail,\n\t\tinstance,\n\t\textensions,\n\t} = options;\n\n\treturn toProblem<ValidationProblemDetails, string, TExtensions>(\n\t\t{ status, type, title },\n\t\t{ code: error.code, details: { issues: error.publicIssues() } },\n\t\t{ detail, instance, extensions },\n\t);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2FA,SAAgB,iBAGf,OACA,UAAiD,CAAC,GACX;CACvC,MAAM,EACL,OAAO,eACP,QAAQ,qBACR,SAAS,KACT,QACA,UACA,eACG;CAEJ,OAAO,UACN;EAAE;EAAQ;EAAM;CAAM,GACtB;EAAE,MAAM,MAAM;EAAM,SAAS,EAAE,QAAQ,MAAM,aAAa,EAAE;CAAE,GAC9D;EAAE;EAAQ;EAAU;CAAW,CAChC;AACD"}