@shirudo/ddd-kit 1.0.0-rc.8 → 1.0.0

package/README.md

@@ -2,9 +2,9 @@
 
 Composable TypeScript toolkit for tactical Domain-Driven Design.
 
-> **Release Candidate**
+> **Stable — 1.0**
 >
-> This library is in Release Candidate phase. The API is considered stable and ready for production evaluation. Please report any issues before the final 1.0.0 release.
+> 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](CHANGELOG.md).
 
 ## Badges
 
@@ -62,7 +62,7 @@ const email = createEmail("user@example.com");
 
 ### Value Objects
 
-Value Objects are immutable objects that are defined by their attributes rather than identity. They ensure data integrity by preventing modification after creation. Use the `vo()` helper function to create deeply frozen value objects that cannot be mutated, even nested objects and arrays. The library provides `voEquals()` for value-based equality comparison, `voEqualsExcept()` for comparing while ignoring specified keys (useful for metadata), and `voWithValidation()` for creating validated value objects at the App-Service boundary (returns Result). For Domain construction, prefer the `ValueObject` base class — its constructor throws on invariant violation via the `validate()` hook.
+Value Objects are immutable objects that are defined by their attributes rather than identity. They ensure data integrity by preventing modification after creation. Use the `vo()` helper function to create deeply frozen value objects that cannot be mutated, even nested objects and arrays. The library provides `voEquals()` for value-based equality comparison, `voEqualsExcept()` for comparing while ignoring specified keys (useful for metadata), `voWithValidation()` for creating validated value objects at the App-Service boundary (returns Result), and `voValidated()` when you need to collect *every* invalid field into one `ValidationError` instead of failing on the first. For Domain construction, prefer the `ValueObject` base class — its constructor throws on invariant violation via the `validate()` hook.
 
 ### Entities
 
@@ -136,7 +136,7 @@ The `Result<T, E>` type provides functional error handling without exceptions. I
 ### Creating a Value Object
 
 ```typescript
-import { vo, voEquals, voEqualsExcept, voWithValidation, type VO } from "@shirudo/ddd-kit";
+import { vo, voEquals, voEqualsExcept, voWithValidation, voValidated, type VO } from "@shirudo/ddd-kit";
 
 // Simple value object (Functional Style)
 type Money = VO<{
@@ -181,6 +181,20 @@ if (result.isOk()) {
 // throws via the `validate()` hook, so Domain code keeps a throw-based contract.
 // Reserve `voWithValidation` for parsing untrusted input at the App boundary.
 
+// To report every invalid field at once, use `voValidated` — it collects all
+// violations into one `ValidationError` (a Result-axis value, not a throw):
+const parsed = voValidated(
+  { amount: -1, currency: "US" },
+  (issues, m) => {
+    if (m.amount < 0)
+      issues.addIssue({ message: "must be non-negative", path: ["amount"] });
+    if (m.currency.length !== 3)
+      issues.addIssue({ message: "must be a 3-letter code", path: ["currency"] });
+  }
+);
+// On failure: parsed.error.publicIssues() lists every violation.
+// Render RFC 9457 with `toProblemDetails` from `@shirudo/ddd-kit/http`.
+
 // Value object with nested structures (deep freeze)
 const address = vo({
   street: "Main St",
@@ -1128,13 +1142,15 @@ For composition utilities (`map`, `flatMap`, `mapErr`, `match`, `unwrapOr`, `pip
 - **Infrastructure boundary returns `Result`** where corruption is an expected recoverable failure: `EventSourcedAggregate.loadFromHistory()`, `restoreFromSnapshotWithEvents()`.
 - **App-Service boundary returns `Result`**: `CommandBus.execute()`, `QueryBus.execute()`, `CommandHandler<C,R>`, `QueryHandler<Q,R>`, `withCommit()`. This is where you map errors to HTTP statuses, logs, etc.
 - **`voWithValidation`** is the explicit Result variant for parsing untrusted input at the App boundary. For Domain construction, use the `ValueObject` base class (constructor throws via `validate()`).
+- **`voValidated`** collects multiple field violations into one `ValidationError` (a Result-axis value you destructure, never catch). The opt-in `@shirudo/ddd-kit/http` entry point renders it as RFC 9457 via `toProblemDetails`.
 
 ## API Documentation
 
 This package is written in TypeScript and provides full type definitions. All types and functions are exported from the main entry point. You can explore the available APIs through your IDE's autocomplete or by examining the type definitions in `node_modules/@shirudo/ddd-kit/dist/index.d.ts`.
 
 Key exports include:
-- `vo()`, `voEquals()`, `voEqualsExcept()`, `voWithValidation()` - Value Object utilities (`voWithValidation` is for the App-Service boundary; Domain construction goes through the `ValueObject` base class which throws via `validate()`)
+- `vo()`, `voEquals()`, `voEqualsExcept()`, `voWithValidation()`, `voValidated()` - Value Object utilities (`voWithValidation` / `voValidated` are for the App-Service boundary — the latter collects every field violation into one `ValidationError`; Domain construction goes through the `ValueObject` base class which throws via `validate()`)
+- `toProblemDetails()` from `@shirudo/ddd-kit/http` - renders a `ValidationError` as an RFC 9457 Problem Details object (opt-in subpath; keeps transport out of the core)
 - `IAggregateRoot<TId>` - Marker interface for Aggregate Root Entities
 - `AggregateRoot<TState, TId, TEvent?>` - Base class for creating Aggregate Root Entities without Event Sourcing (extends `Entity`, implements `IAggregateRoot<TId, TEvent>`). Optional `TEvent` parameter enables type-safe domain events
 - `EventSourcedAggregate<TState, TEvent, TId>` - Base class for Event-Sourced Aggregate Roots (extends `Entity`, implements `IEventSourcedAggregate<TId, TEvent>`)

package/dist/http.d.ts

@@ -0,0 +1,46 @@
+import { ValidationError, ProblemDetailsOptions, ProblemDetails } from '@shirudo/base-error';
+
+/** 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.
+ */
+interface ValidationProblemOptions extends Omit<ProblemDetailsOptions, "extensions"> {
+    /**
+     * 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>;
+}
+/**
+ * Projects a base-error {@link ValidationError} to an RFC 9457 Problem Details
+ * object with the collected field issues attached under an extension member.
+ *
+ * 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
+ * applies sensible validation defaults (`422`, `"Validation Failed"`), so the
+ * common boundary case is a one-liner instead of a footgun.
+ *
+ * This is a presentation/transport concern and ships from the opt-in
+ * `@shirudo/ddd-kit/http` entry point — the core kit stays transport-free.
+ *
+ * @example
+ * ```ts
+ * import { toProblemDetails } from "@shirudo/ddd-kit/http";
+ *
+ * if (result.isErr()) {
+ *   return Response.json(toProblemDetails(result.error), { status: 422 });
+ * }
+ * // → { type, title: "Validation Failed", status: 422,
+ * //     errors: [{ message: "must be a valid email", path: ["email"], pointer: "email" }] }
+ * ```
+ */
+declare function toProblemDetails(error: ValidationError, options?: ValidationProblemOptions): ProblemDetails;
+
+export { type ValidationProblemMember, type ValidationProblemOptions, toProblemDetails };

package/dist/http.js

@@ -0,0 +1,18 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// 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() }
+  });
+}
+__name(toProblemDetails, "toProblemDetails");
+
+export { toProblemDetails };
+//# sourceMappingURL=http.js.map
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +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"]}