@ddd-ts-kit/http 0.2.0 → 0.3.0

package/README.md

@@ -60,6 +60,27 @@ A handler throws a `DomainError`; its `code` is mapped to a status in one place
   "detail": "Order 7 does not exist.", "requestId": "..." }
 ```
 
+A refusal built by a factory of a `ConceptError` carries facts, and they are private: the
+document holds, under `facts`, only the ones its factory exposed by name, and no `facts` member
+when it exposed none.
+
+```ts
+static slotTaken(calendarId: string, startsAt: Date) {
+  return AppointmentError.refusal('SLOT_TAKEN', 'The slot is already held.', { calendarId, startsAt }).exposing('startsAt');
+}
+```
+
+```json
+{ "type": "urn:problem:slot-taken", "title": "Conflict", "status": 409, "code": "SLOT_TAKEN",
+  "detail": "The slot is already held.", "facts": { "startsAt": "2026-03-02T09:00:00.000Z" }, "requestId": "..." }
+```
+
+`facts` is an optional object of the `Problem` schema of the OpenAPI document. A client
+branches on `code` and reads data from `facts`, never from `detail`, which is a sentence for a
+human and may change. The message is answered as it was written: it says nothing the caller
+did not send, and nothing about another person. A refusal mapped to a 5xx answers neither its
+message nor its facts.
+
 Defaults: `VALIDATION_FAILED` 422 (with `issues`, paths prefixed by the part:
 `body.items.0.sku`), `NOT_FOUND` 404, `CONFLICT` 409, `INVARIANT_VIOLATION` 422, `UNAUTHORIZED`
 401, `FORBIDDEN` 403. A domain code that is not mapped answers 422.

package/dist/error/problem.d.ts

@@ -1,3 +1,4 @@
+import type { RefusalFacts } from '@ddd-ts-kit/kernel';
 import type { ValidationIssue } from '@ddd-ts-kit/validation';
 export interface Problem {
     readonly type: string;
@@ -6,6 +7,8 @@ export interface Problem {
     readonly code: string;
     readonly detail?: string;
     readonly issues?: readonly ValidationIssue[];
+    /** The facts the refusal exposes, by name. Absent when its factory exposed none: facts are private by default. */
+    readonly facts?: RefusalFacts;
     readonly requestId: string;
 }
 //# sourceMappingURL=problem.d.ts.map

package/dist/error/problem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"problem.d.ts","sourceRoot":"","sources":["../../src/error/problem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"problem.d.ts","sourceRoot":"","sources":["../../src/error/problem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,kHAAkH;IAClH,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/error/to-problem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"to-problem.d.ts","sourceRoot":"","sources":["../../src/error/to-problem.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAqBzF"}
+{"version":3,"file":"to-problem.d.ts","sourceRoot":"","sources":["../../src/error/to-problem.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAG5C,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAsBzF"}

package/dist/error/to-problem.js

@@ -1,4 +1,4 @@
-import { DomainError } from '@ddd-ts-kit/kernel';
+import { ConceptError, DomainError } from '@ddd-ts-kit/kernel';
 import { ValidationError } from '@ddd-ts-kit/validation';
 import { INTERNAL_ERROR_CODE } from './internal-error-code.js';
 import { statusTitle } from './status-title.js';
@@ -18,9 +18,18 @@ export function toProblem(error, mapper, requestId) {
         code: error.code,
         detail: error.message,
         ...(error instanceof ValidationError ? { issues: error.issues } : {}),
+        ...exposedFacts(error),
         requestId,
     };
 }
+/** Only what the factory of the refusal exposed by name: a fact never leaves the process by default. */
+function exposedFacts(error) {
+    if (!(error instanceof ConceptError)) {
+        return {};
+    }
+    const facts = error.exposedFacts;
+    return Object.keys(facts).length === 0 ? {} : { facts };
+}
 // The message of an unexpected error quotes data and internals: it never leaves the process.
 function internalProblem(requestId) {
     return {

package/dist/error/to-problem.js.map

@@ -1 +1 @@
-{"version":3,"file":"to-problem.js","sourceRoot":"","sources":["../../src/error/to-problem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,MAAmB,EAAE,SAAiB;IAC9E,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC,EAAE,CAAC;QACpC,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE3C,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAClB,8EAA8E;QAC9E,OAAO,EAAE,GAAG,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IACjG,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAC/B,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC;QAC1B,MAAM;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,OAAO;QACrB,GAAG,CAAC,KAAK,YAAY,eAAe,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,SAAS;KACV,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,SAAS,eAAe,CAAC,SAAiB;IACxC,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,uBAAuB;QAC9B,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,mBAAmB;QACzB,SAAS;KACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"to-problem.js","sourceRoot":"","sources":["../../src/error/to-problem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAqB,MAAM,oBAAoB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,UAAU,SAAS,CAAC,KAAc,EAAE,MAAmB,EAAE,SAAiB;IAC9E,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC,EAAE,CAAC;QACpC,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE3C,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAClB,8EAA8E;QAC9E,OAAO,EAAE,GAAG,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IACjG,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAC/B,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC;QAC1B,MAAM;QACN,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,OAAO;QACrB,GAAG,CAAC,KAAK,YAAY,eAAe,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,GAAG,YAAY,CAAC,KAAK,CAAC;QACtB,SAAS;KACV,CAAC;AACJ,CAAC;AAED,wGAAwG;AACxG,SAAS,YAAY,CAAC,KAAkB;IACtC,IAAI,CAAC,CAAC,KAAK,YAAY,YAAY,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC;IAEjC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;AAC1D,CAAC;AAED,6FAA6F;AAC7F,SAAS,eAAe,CAAC,SAAiB;IACxC,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,uBAAuB;QAC9B,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,mBAAmB;QACzB,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/openapi/problem-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"problem-schema.d.ts","sourceRoot":"","sources":["../../src/openapi/problem-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,eAAO,MAAM,cAAc,EAAE,UAyB5B,CAAC"}
+{"version":3,"file":"problem-schema.d.ts","sourceRoot":"","sources":["../../src/openapi/problem-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,eAAO,MAAM,cAAc,EAAE,UA8B5B,CAAC"}

package/dist/openapi/problem-schema.js

@@ -21,6 +21,11 @@ export const PROBLEM_SCHEMA = {
                 },
             },
         },
+        facts: {
+            type: 'object',
+            description: 'The facts of the refusal its code exposes, by name. Absent when it exposes none.',
+            additionalProperties: true,
+        },
         requestId: { type: 'string' },
     },
 };

package/dist/openapi/problem-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"problem-schema.js","sourceRoot":"","sources":["../../src/openapi/problem-schema.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,iEAAiE;IAC9E,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC;IAC1D,UAAU,EAAE;QACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;QAC7E,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sDAAsD,EAAE;QAC7F,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC1B,MAAM,EAAE;YACN,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,6CAA6C;YAC1D,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC;gBACrC,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4CAA4C,EAAE;oBACnF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACxB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iBAC5B;aACF;SACF;QACD,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC9B;CACF,CAAC"}
+{"version":3,"file":"problem-schema.js","sourceRoot":"","sources":["../../src/openapi/problem-schema.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,iEAAiE;IAC9E,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC;IAC1D,UAAU,EAAE;QACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sCAAsC,EAAE;QAC7E,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAC3B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sDAAsD,EAAE;QAC7F,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC1B,MAAM,EAAE;YACN,IAAI,EAAE,OAAO;YACb,WAAW,EAAE,6CAA6C;YAC1D,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC;gBACrC,UAAU,EAAE;oBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,4CAA4C,EAAE;oBACnF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACxB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;iBAC5B;aACF;SACF;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,kFAAkF;YAC/F,oBAAoB,EAAE,IAAI;SAC3B;QACD,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC9B;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddd-ts-kit/http",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic route definitions with Express, Fastify and NestJS adapters and OpenAPI 3.1 generation.",
   "license": "MIT",
   "repository": {
@@ -46,8 +46,8 @@
     "dist"
   ],
   "dependencies": {
-    "@ddd-ts-kit/kernel": "0.2.0",
-    "@ddd-ts-kit/validation": "0.2.0"
+    "@ddd-ts-kit/kernel": "0.3.0",
+    "@ddd-ts-kit/validation": "0.3.0"
   },
   "peerDependencies": {
     "@nestjs/common": ">=11.0.0",