@shirudo/ddd-kit 1.2.0 → 2.0.0

package/dist/presentation.d.ts

@@ -0,0 +1,54 @@
+import { PublicIssue } from '@shirudo/base-error';
+import { PublicErrorView } from '@shirudo/base-error/presentation';
+
+/** Details shape carried by the view for a {@link toPublicErrorView} result. */
+interface PublicErrorViewDetails {
+    /** Whitelisted field issues, present only for a `ValidationError`. */
+    readonly issues: readonly PublicIssue[];
+}
+/** Options for {@link toPublicErrorView}. */
+interface PublicErrorViewOptions {
+    /**
+     * BCP 47 locale tag stamped on the view. The built-in messages are English;
+     * pass a locale only when you supply your own message resolution upstream.
+     * Default `"en"`.
+     */
+    locale?: string;
+}
+/**
+ * Maps a kit error (or any caught value) to a base-error
+ * {@link PublicErrorView}: a **transport-neutral**, client-safe representation
+ * (`code`, `message`, `locale`, optional `details`). It is deliberately *not* a
+ * transport adapter: it carries no HTTP status, header, or exit code, because
+ * those are the consumer's concern. Feed the view into base-error's
+ * `defineProblemDetailsAdapter` (HTTP / RFC 9457), a gRPC status mapper, or a
+ * CLI exit-code table, whichever boundary you are at.
+ *
+ * Total over `unknown`: an unmapped or non-kit value degrades to a generic
+ * `INTERNAL_ERROR` view rather than leaking the technical message or throwing.
+ * The kit's class-based errors match by their pinned `error.name`, so it
+ * survives minification and duplicate installs (no `instanceof`). A
+ * `ValidationError` is detected by its `publicIssues()` whitelist (base-error
+ * names it after its code), and those issues ride along in `details.issues`.
+ *
+ * For richer, multi-locale messages, register the kit's errors in a base-error
+ * `PublicErrorRegistry` and use `PublicErrorPresenter` instead; this helper is
+ * the lean, single-locale default.
+ *
+ * @example
+ * ```ts
+ * import { toPublicErrorView } from "@shirudo/ddd-kit/presentation";
+ * import { defineProblemDetailsAdapter } from "@shirudo/base-error/problem-details";
+ *
+ * const adapter = defineProblemDetailsAdapter({
+ *   definitions: { AggregateNotFoundError: { type: "about:blank", status: 404 } },
+ *   fallback: { type: "about:blank", status: 500 },
+ * });
+ *
+ * const { body, status } = adapter.map(toPublicErrorView(error));
+ * return Response.json(body, { status });
+ * ```
+ */
+declare function toPublicErrorView(error: unknown, options?: PublicErrorViewOptions): PublicErrorView<PublicErrorViewDetails>;
+
+export { type PublicErrorViewDetails, type PublicErrorViewOptions, toPublicErrorView };

package/dist/presentation.js

@@ -0,0 +1,45 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/presentation/public-error-view.ts
+var KIT_PUBLIC_MESSAGES = {
+  AggregateNotFoundError: "The requested resource could not be found.",
+  ConcurrencyConflictError: "The resource was modified by another request. Please reload and try again.",
+  DuplicateAggregateError: "The resource already exists."
+};
+var VALIDATION_MESSAGE = "The submitted data is invalid.";
+var FALLBACK_CODE = "INTERNAL_ERROR";
+var FALLBACK_MESSAGE = "An unexpected error occurred.";
+var DEFAULT_LOCALE = "en";
+function toPublicErrorView(error, options = {}) {
+  const locale = options.locale ?? DEFAULT_LOCALE;
+  const name = errorName(error);
+  if (hasPublicIssues(error)) {
+    return {
+      code: name ?? "VALIDATION_FAILED",
+      message: VALIDATION_MESSAGE,
+      locale,
+      details: { issues: error.publicIssues() }
+    };
+  }
+  const message = name ? KIT_PUBLIC_MESSAGES[name] : void 0;
+  if (message === void 0) {
+    return { code: FALLBACK_CODE, message: FALLBACK_MESSAGE, locale };
+  }
+  return { code: name, message, locale };
+}
+__name(toPublicErrorView, "toPublicErrorView");
+function errorName(error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const { name } = error;
+  return typeof name === "string" ? name : void 0;
+}
+__name(errorName, "errorName");
+function hasPublicIssues(error) {
+  return typeof error.publicIssues === "function";
+}
+__name(hasPublicIssues, "hasPublicIssues");
+
+export { toPublicErrorView };
+//# sourceMappingURL=presentation.js.map
+//# sourceMappingURL=presentation.js.map

package/dist/presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/presentation/public-error-view.ts"],"names":[],"mappings":";;;;AAaA,IAAM,mBAAA,GAAwD;AAAA,EAC7D,sBAAA,EAAwB,4CAAA;AAAA,EACxB,wBAAA,EACC,4EAAA;AAAA,EACD,uBAAA,EAAyB;AAC1B,CAAA;AAGA,IAAM,kBAAA,GAAqB,gCAAA;AAE3B,IAAM,aAAA,GAAgB,gBAAA;AACtB,IAAM,gBAAA,GAAmB,+BAAA;AAEzB,IAAM,cAAA,GAAiB,IAAA;AAoDhB,SAAS,iBAAA,CACf,KAAA,EACA,OAAA,GAAkC,EAAC,EACO;AAC1C,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,IAAU,cAAA;AACjC,EAAA,MAAM,IAAA,GAAO,UAAU,KAAK,CAAA;AAK5B,EAAA,IAAI,eAAA,CAAgB,KAAK,CAAA,EAAG;AAC3B,IAAA,OAAO;AAAA,MACN,MAAM,IAAA,IAAQ,mBAAA;AAAA,MACd,OAAA,EAAS,kBAAA;AAAA,MACT,MAAA;AAAA,MACA,OAAA,EAAS,EAAE,MAAA,EAAQ,KAAA,CAAM,cAAa;AAAE,KACzC;AAAA,EACD;AAEA,EAAA,MAAM,OAAA,GAAU,IAAA,GAAO,mBAAA,CAAoB,IAAI,CAAA,GAAI,MAAA;AACnD,EAAA,IAAI,YAAY,MAAA,EAAW;AAC1B,IAAA,OAAO,EAAE,IAAA,EAAM,aAAA,EAAe,OAAA,EAAS,kBAAkB,MAAA,EAAO;AAAA,EACjE;AAEA,EAAA,OAAO,EAAE,IAAA,EAAM,IAAA,EAAgB,OAAA,EAAS,MAAA,EAAO;AAChD;AAzBgB,MAAA,CAAA,iBAAA,EAAA,mBAAA,CAAA;AA4BhB,SAAS,UAAU,KAAA,EAAoC;AACtD,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,MAAM,OAAO,MAAA;AACxD,EAAA,MAAM,EAAE,MAAK,GAAI,KAAA;AACjB,EAAA,OAAO,OAAO,IAAA,KAAS,QAAA,GAAW,IAAA,GAAO,MAAA;AAC1C;AAJS,MAAA,CAAA,SAAA,EAAA,WAAA,CAAA;AAOT,SAAS,gBACR,KAAA,EAC6C;AAC7C,EAAA,OACC,OAAQ,MAAqC,YAAA,KAAiB,UAAA;AAEhE;AANS,MAAA,CAAA,eAAA,EAAA,iBAAA,CAAA","file":"presentation.js","sourcesContent":["import type { PublicIssue } from \"@shirudo/base-error\";\nimport type { PublicErrorView } from \"@shirudo/base-error/presentation\";\n\n/**\n * Safe, client-facing English messages for the kit's known errors. They carry\n * no occurrence data (no id, version, or technical detail), so they never leak\n * across the boundary. This is the transport-neutral *presentation* layer: the\n * technical error classes stay free of these strings (removed from the core in\n * 2.0); here is their opt-in home.\n *\n * Keyed by the kit's pinned `error.name` (stable across minification and\n * duplicate installs), so matching does not depend on `instanceof`.\n */\nconst KIT_PUBLIC_MESSAGES: Readonly<Record<string, string>> = {\n\tAggregateNotFoundError: \"The requested resource could not be found.\",\n\tConcurrencyConflictError:\n\t\t\"The resource was modified by another request. Please reload and try again.\",\n\tDuplicateAggregateError: \"The resource already exists.\",\n};\n\n/** Message for a `ValidationError`, which is detected by capability, not name. */\nconst VALIDATION_MESSAGE = \"The submitted data is invalid.\";\n/** Public code and message used for any unmapped or non-kit error. */\nconst FALLBACK_CODE = \"INTERNAL_ERROR\";\nconst FALLBACK_MESSAGE = \"An unexpected error occurred.\";\n/** BCP 47 locale the built-in messages are written in. */\nconst DEFAULT_LOCALE = \"en\";\n\n/** Details shape carried by the view for a {@link toPublicErrorView} result. */\nexport interface PublicErrorViewDetails {\n\t/** Whitelisted field issues, present only for a `ValidationError`. */\n\treadonly issues: readonly PublicIssue[];\n}\n\n/** Options for {@link toPublicErrorView}. */\nexport interface PublicErrorViewOptions {\n\t/**\n\t * BCP 47 locale tag stamped on the view. The built-in messages are English;\n\t * pass a locale only when you supply your own message resolution upstream.\n\t * Default `\"en\"`.\n\t */\n\tlocale?: string;\n}\n\n/**\n * Maps a kit error (or any caught value) to a base-error\n * {@link PublicErrorView}: a **transport-neutral**, client-safe representation\n * (`code`, `message`, `locale`, optional `details`). It is deliberately *not* a\n * transport adapter: it carries no HTTP status, header, or exit code, because\n * those are the consumer's concern. Feed the view into base-error's\n * `defineProblemDetailsAdapter` (HTTP / RFC 9457), a gRPC status mapper, or a\n * CLI exit-code table, whichever boundary you are at.\n *\n * Total over `unknown`: an unmapped or non-kit value degrades to a generic\n * `INTERNAL_ERROR` view rather than leaking the technical message or throwing.\n * The kit's class-based errors match by their pinned `error.name`, so it\n * survives minification and duplicate installs (no `instanceof`). A\n * `ValidationError` is detected by its `publicIssues()` whitelist (base-error\n * names it after its code), and those issues ride along in `details.issues`.\n *\n * For richer, multi-locale messages, register the kit's errors in a base-error\n * `PublicErrorRegistry` and use `PublicErrorPresenter` instead; this helper is\n * the lean, single-locale default.\n *\n * @example\n * ```ts\n * import { toPublicErrorView } from \"@shirudo/ddd-kit/presentation\";\n * import { defineProblemDetailsAdapter } from \"@shirudo/base-error/problem-details\";\n *\n * const adapter = defineProblemDetailsAdapter({\n *   definitions: { AggregateNotFoundError: { type: \"about:blank\", status: 404 } },\n *   fallback: { type: \"about:blank\", status: 500 },\n * });\n *\n * const { body, status } = adapter.map(toPublicErrorView(error));\n * return Response.json(body, { status });\n * ```\n */\nexport function toPublicErrorView(\n\terror: unknown,\n\toptions: PublicErrorViewOptions = {},\n): PublicErrorView<PublicErrorViewDetails> {\n\tconst locale = options.locale ?? DEFAULT_LOCALE;\n\tconst name = errorName(error);\n\n\t// ValidationError (and subclasses) are detected by the publicIssues()\n\t// whitelist, not by name: base-error names a ValidationError after its code\n\t// (\"VALIDATION_FAILED\"), so a name match would miss it.\n\tif (hasPublicIssues(error)) {\n\t\treturn {\n\t\t\tcode: name ?? \"VALIDATION_FAILED\",\n\t\t\tmessage: VALIDATION_MESSAGE,\n\t\t\tlocale,\n\t\t\tdetails: { issues: error.publicIssues() },\n\t\t};\n\t}\n\n\tconst message = name ? KIT_PUBLIC_MESSAGES[name] : undefined;\n\tif (message === undefined) {\n\t\treturn { code: FALLBACK_CODE, message: FALLBACK_MESSAGE, locale };\n\t}\n\n\treturn { code: name as string, message, locale };\n}\n\n/** Reads a string `name` off a caught value without assuming it is an Error. */\nfunction errorName(error: unknown): string | undefined {\n\tif (typeof error !== \"object\" || error === null) return undefined;\n\tconst { name } = error as { name?: unknown };\n\treturn typeof name === \"string\" ? name : undefined;\n}\n\n/** Duck-types base-error's `ValidationError.publicIssues()` accessor. */\nfunction hasPublicIssues(\n\terror: unknown,\n): error is { publicIssues(): PublicIssue[] } {\n\treturn (\n\t\ttypeof (error as { publicIssues?: unknown }).publicIssues === \"function\"\n\t);\n}\n"]}

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { I as IAggregateRoot, a as Id, A as AnyDomainEvent } from './aggregate-DclYgG_D.js';
+import { I as IAggregateRoot, a as Id, A as AnyDomainEvent } from './aggregate-CePTINEt.js';
 import '@shirudo/result';
 import '@shirudo/base-error';
 
@@ -6,9 +6,9 @@ import '@shirudo/base-error';
  * The repository surface the contract suite exercises: the minimal
  * structural subset of the canonical `IUnitOfWorkRepository` (exported
  * from the main entry) that the tests need. `getById` is typed over
- * the aggregate's own branded id (`TAgg["id"]`), so concrete adapters
- * — including arrow-function-property style repositories, which are
- * checked contravariantly — match without casts.
+ * the aggregate's own branded id (`TAgg["id"]`), so concrete adapters,
+ * including arrow-function-property style repositories, which are
+ * checked contravariantly, match without casts.
  */
 interface ContractRepository<TAgg extends IAggregateRoot<Id<string>, AnyDomainEvent>> {
     getById(id: TAgg["id"]): Promise<TAgg | null>;
@@ -27,7 +27,7 @@ interface RepositoryContractEnvironment<TAgg extends IAggregateRoot<Id<string>,
      * transaction, hand the suite a tx-bound repository, commit on
      * resolve, roll back on throw, and run the post-commit lifecycle
      * (event harvest into the outbox, `markPersisted`). Wire this
-     * through your real `UnitOfWork` / `withCommit` setup — the commit
+     * through your real `UnitOfWork` / `withCommit` setup: the commit
      * boundary IS part of what the suite proves.
      */
     run<R>(work: (ctx: {
@@ -35,7 +35,7 @@ interface RepositoryContractEnvironment<TAgg extends IAggregateRoot<Id<string>,
     }) => Promise<R>): Promise<R>;
     /**
      * All events currently persisted in the outbox (committed writes
-     * only — a rolled-back transaction's events must not appear here).
+     * only; a rolled-back transaction's events must not appear here).
      */
     committedOutboxEvents(): Promise<ReadonlyArray<Evt>>;
     /** Release connections, drop schemas, etc. Called in a finally. */
@@ -45,7 +45,7 @@ interface RepositoryContractEnvironment<TAgg extends IAggregateRoot<Id<string>,
  * What an adapter supplies to run the contract suite.
  *
  * The harness MUST provide isolation per environment (fresh
- * tables/keyspace or a truncate) — tests assume they see only their
+ * tables/keyspace or a truncate); tests assume they see only their
  * own writes. **For SQL/ORM adapters this must run against a real
  * database** (testcontainers or equivalent), not an in-memory fake:
  * the mandatory two-writer test proves YOUR `WHERE version = ?`
@@ -53,11 +53,11 @@ interface RepositoryContractEnvironment<TAgg extends IAggregateRoot<Id<string>,
  *
  * Optional capabilities widen the suite: tests for an absent
  * capability come back **marked `skipped`** with a `run()` that
- * rejects loudly — bind them with `it.skip` so the gap stays visible
+ * rejects loudly: bind them with `it.skip` so the gap stays visible
  * in every report (see {@link RepositoryContractTest}); a naive
  * binding fails instead of green-no-op'ing. Capabilities are captured
  * once at suite creation. Provide every capability your adapter can
- * support — each one closes a real OCC hole.
+ * support; each one closes a real OCC hole.
  */
 interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>, Evt extends AnyDomainEvent = AnyDomainEvent> {
     createEnvironment(): Promise<RepositoryContractEnvironment<TAgg, Evt>>;
@@ -76,7 +76,7 @@ interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>
     /**
      * Optional: a version-bumping mutation whose state is deep-equal to
      * the previous state (`setState({...state}, true)`). Enables the
-     * version-only-change-still-persists test — the skip-save/OCC-desync
+     * version-only-change-still-persists test: the skip-save/OCC-desync
      * trap.
      */
     mutateVersionOnly?(aggregate: TAgg): void;
@@ -99,9 +99,9 @@ interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>
     /**
      * Semantic opt-OUT (default `true`): whether `save()`'s INSERT path
      * rejects an existing id with `DuplicateAggregateError` (mapping the
-     * driver's unique-violation — Postgres `23505`, MySQL `1062`, SQLite
+     * driver's unique-violation: Postgres `23505`, MySQL `1062`, SQLite
      * `SQLITE_CONSTRAINT_UNIQUE`). This is the near-mandatory contract:
-     * `save()` is insert-or-update, never upsert — create-idempotency
+     * `save()` is insert-or-update, never upsert. Create-idempotency
      * belongs in the USE CASE (load, then decide), not in the save path.
      * Set `false` ONLY for a deliberately upserting adapter
      * (idempotent-create design); the duplicate-insert test is then
@@ -114,12 +114,12 @@ interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>
      * Optional: a plain-data projection of the aggregate's persisted
      * state, compared with deep equality. Enables the mandatory test's
      * state assertion (without it, only the version and the outbox are
-     * compared — an adapter whose predicate guards the version write
+     * compared, and an adapter whose predicate guards the version write
      * but not the state write would slip through).
      *
      * **The projection must be roundtrip-stable**: it compares a
      * DB-reloaded aggregate against an in-memory one, so normalize
-     * anything your store changes in transit — dates to ISO strings at
+     * anything your store changes in transit: dates to ISO strings at
      * your store's precision (MySQL DATETIME truncates millis), no
      * `undefined`-valued keys (JSON columns drop them), decimals/bigints
      * to one consistent representation. A mismatch here fails the
@@ -130,7 +130,7 @@ interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>
      * Optional flag: declare it when your `delete(aggregate)` runs an
      * OCC predicate (`DELETE … WHERE id = ? AND version = ?`). Enables
      * the stale-delete conflict test. Unpredicated deletes are
-     * last-write-wins by construction — acceptable for GC-style
+     * last-write-wins by construction: acceptable for GC-style
      * cleanup, rarely for user-initiated deletion of contended
      * aggregates (see the repository guide).
      */
@@ -142,7 +142,7 @@ interface RepositoryContractHarness<TAgg extends IAggregateRoot<Id<string>, Evt>
  * entry is still returned with {@link skipped} set and a `run` that
  * REJECTS with an explanatory error: bind it with your runner's skip
  * (`(test.skipped ? it.skip : it)(test.name, test.run)`) so the gap is
- * visible in every test report — a missing capability must never look
+ * visible in every test report: a missing capability must never look
  * like green coverage, and a naive binding that ignores `skipped`
  * fails loud instead of passing silently.
  */
@@ -158,7 +158,7 @@ interface RepositoryContractTest {
  * The repository contract test suite: the proof that an adapter
  * actually delivers the guarantees the kit's Unit of Work documents.
  *
- * The kit is ORM-agnostic — the OCC version predicate lives in YOUR
+ * The kit is ORM-agnostic: the OCC version predicate lives in YOUR
  * repository's SQL. That makes optimistic concurrency a **repository
  * contract, not a kit guarantee**: the kit ships the boundary, the
  * `persistedVersion` baseline, `ConcurrencyConflictError`, and this
@@ -208,12 +208,12 @@ interface RepositoryContractTest {
  *
  * **`env.run` must provide unit-of-work semantics.** Three core tests
  * (identity-map sameness, getById-null-after-delete, deletion
- * finality) exercise the session machinery — `session.identityMap`,
+ * finality) exercise the session machinery: `session.identityMap`,
  * the `isDeleted` probe, the deleted-gate. Wiring `run` through the
  * kit's `UnitOfWork` gives you all of it; a hand-rolled `withCommit`
  * wiring must provide equivalents or those tests will fail. A
  * `withCommit`-only setup that deliberately makes no identity-map /
- * deletion-finality claims is outside this suite's scope — the suite
+ * deletion-finality claims is outside this suite's scope; the suite
  * is the compliance bar for unit-of-work repositories.
  *
  * **Error matching is by NAME along the `cause` chain, not by
@@ -227,20 +227,21 @@ interface RepositoryContractTest {
  * tests prove YOUR adapter's SQL and transaction wiring. The
  * identity-map, deletion-finality, and event-lifecycle tests prove
  * your READ-PATH and unit-of-work WIRING (they exercise kit-provided
- * machinery — `session.identityMap`, the deleted-gate, `withCommit`'s
- * harvest — and fail when your repository bypasses or mis-wires it).
+ * machinery, namely `session.identityMap`, the deleted-gate, and
+ * `withCommit`'s harvest, and fail when your repository bypasses or
+ * mis-wires it).
  * A deletion-finality failure usually means a missing
  * `identityMap.isDeleted` check or an `enrollSaved` placed after the
  * row write, not a broken DELETE statement.
  *
  * **Known limitation: no truly concurrent runs.** The mandatory
- * two-writer test is deliberately sequential-deterministic — writer B
+ * two-writer test is deliberately sequential-deterministic: writer B
  * loads, writer A loads/mutates/commits, then B commits its stale
  * instance. The stale `persistedVersion` baseline travels with B's
  * instance, so the version predicate is exercised exactly as in a true
  * race, without depending on lock timing, pool sizes, or
  * engine-specific blocking. The flip side: lock interaction is NOT
- * covered — a `SELECT … FOR UPDATE`-style repository that blocks
+ * covered. A `SELECT … FOR UPDATE`-style repository that blocks
  * instead of conflicting, or a SERIALIZABLE engine surfacing raw
  * serialization failures (Postgres 40001) your adapter must map to
  * `ConcurrencyConflictError`, needs adapter-specific tests on top of