@zeroxsolutions/response 0.14.6 → 0.14.7

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.14.7 (2026-10-21)
+
+### 🚀 Features
+
+- **response:** let an upstream answer state its own source ([fdc8078](https://github.com/zeroxsolutions/zeroxsolutions/commit/fdc8078))
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
 ## 0.14.6 (2026-10-21)
 
 ### 🚀 Features

package/README.md

@@ -246,6 +246,11 @@ exactly one error per failure. Of that error it keeps only what an answer's `met
 pointers name the SERVICE's request shape, not the one this caller sent, so echoing them would point a
 client at members it has no way to correct.
 
+An answer can state a `source` of its own instead, in this transport's request terms. It is fixed per
+upstream code, so it suits a refusal whose slot is the same on every occurrence; a slot that varies per
+occurrence (one member of a list, say) has no way through, since the upstream error's `source` is the only
+place that varies and it describes the wrong request. The fallback states none.
+
 A `meta` callback returns its parse, never `upstream` as received - the schema is what keeps a member the
 service adds later from crossing. Returning `undefined` answers the fallback: a mapped code missing the
 data its contract promises is an answer the gateway does not recognise.
@@ -298,6 +303,30 @@ export const translateCatalogueError = translator(
 throw error({ ...BASE_ERROR_CODES.FORBIDDEN, code: 'api.forbidden' });
 ```
 
+A mapped answer states where in the client's request the refusal belongs with `source`, one of the
+standard's `pointer`, `parameter` or `header`. JSON:API holds a `pointer` to "a value in the request
+document that exists", so it names the member this transport's client sent, never the one the service
+was sent:
+
+```ts
+// entrypoints/http/error-map.ts - the client names the place by its slug; the service was sent its id
+export const translateCatalogueWriteError = translator(
+  CATALOGUE_ERROR_CODES,
+  {
+    'catalogue.place.not_found': {
+      status: 422,
+      title: 'Unprocessable Entity',
+      code: 'api.place.not_found',
+      source: { pointer: '/data/attributes/placeSlug' },
+    },
+  },
+  { status: 502, title: 'Bad Gateway', code: 'api.upstream_failed' },
+);
+```
+
+The translated error renders `source: { pointer: '/data/attributes/placeSlug' }` whatever `source` the
+service's error carried, and a member the standard does not define, `pointr`, does not compile.
+
 The lists are values rather than type arguments: with nothing passed there is no list to fall back on,
 where a type argument left out would widen to `string`. Neither is read at runtime. `error` also refuses
 a key its answer does not declare, so a misspelled `detial` does not compile, and a thrown answer's `meta`

package/dist/upstream-error.d.ts

@@ -1,5 +1,5 @@
 import type { UpstreamErrorMap } from './error-map.js';
-import type { ErrorDocument, ErrorLinks } from './errors/error-document.js';
+import type { ErrorDocument, ErrorLinks, ErrorSource } from './errors/error-document.js';
 import type { ErrorStatus } from './errors/error-registry.js';
 import { JsonApiError } from './errors/jsonapi-error.js';
 import type { Meta } from './primitives.js';
@@ -11,6 +11,11 @@ export interface UpstreamErrorAnswer extends ErrorStatus {
     code: string;
     /** Human-readable and request-specific; the error's `message` falls back to the title without one. */
     detail?: string;
+    /**
+     * Where in this transport's own request the error originates, the same on every occurrence of the code - omit to render
+     * no `source`. The upstream error's own `source` is never read: it names a slot of the request the service received.
+     */
+    source?: ErrorSource;
     /** A page about this occurrence, and a page about its type of problem. */
     links?: ErrorLinks;
     /**
@@ -28,7 +33,8 @@ export interface UpstreamErrorAnswer extends ErrorStatus {
  *
  * The document's FIRST error decides, because `createErrorHandler` renders exactly one per failure. Nothing else of the
  * service's error survives unless an answer's `meta` reads it: its `code` names a namespace this surface's contract
- * never declared, and its `detail` and `source` describe a request this client never sent.
+ * never declared, and its `detail` and `source` describe a request this client never sent. An answer states its own
+ * `source` instead; the fallback states none, since the code it answers was not recognised.
  */
-export declare function createUpstreamErrorTranslator(answers: UpstreamErrorMap, fallback: Omit<UpstreamErrorAnswer, 'meta'>): (document: ErrorDocument) => JsonApiError;
+export declare function createUpstreamErrorTranslator(answers: UpstreamErrorMap, fallback: Omit<UpstreamErrorAnswer, 'meta' | 'source'>): (document: ErrorDocument) => JsonApiError;
 //# sourceMappingURL=upstream-error.d.ts.map

package/dist/upstream-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-error.d.ts","sourceRoot":"","sources":["../src/upstream-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,GAAG,SAAS,KAAK,IAAI,GAAG,SAAS,CAAC;CACzD;AAaD;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,GAC1C,CAAC,QAAQ,EAAE,aAAa,KAAK,YAAY,CAa3C"}
+{"version":3,"file":"upstream-error.d.ts","sourceRoot":"","sources":["../src/upstream-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,sGAAsG;IACtG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,IAAI,GAAG,SAAS,KAAK,IAAI,GAAG,SAAS,CAAC;CACzD;AAcD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,GAAG,QAAQ,CAAC,GACrD,CAAC,QAAQ,EAAE,aAAa,KAAK,YAAY,CAa3C"}

package/dist/upstream-error.js

@@ -5,6 +5,7 @@ function toJsonApiError(answer, meta) {
         title: answer.title,
         code: answer.code,
         detail: answer.detail,
+        source: answer.source,
         links: answer.links,
         meta,
     });
@@ -15,7 +16,8 @@ function toJsonApiError(answer, meta) {
  *
  * The document's FIRST error decides, because `createErrorHandler` renders exactly one per failure. Nothing else of the
  * service's error survives unless an answer's `meta` reads it: its `code` names a namespace this surface's contract
- * never declared, and its `detail` and `source` describe a request this client never sent.
+ * never declared, and its `detail` and `source` describe a request this client never sent. An answer states its own
+ * `source` instead; the fallback states none, since the code it answers was not recognised.
  */
 export function createUpstreamErrorTranslator(answers, fallback) {
     return (document) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/response",
-  "version": "0.14.6",
+  "version": "0.14.7",
   "private": false,
   "type": "module",
   "sideEffects": false,