@zeroxsolutions/response 0.12.0

package/dist/upstream-error.d.ts

@@ -0,0 +1,34 @@
+import type { UpstreamErrorMap } from './error-map.js';
+import type { ErrorDocument, ErrorLinks } 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';
+/**
+ * This transport's answer to one `code` a fronted service renders - its own title and detail, since the service's were
+ * written for its single internal caller.
+ */
+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;
+    /** A page about this occurrence, and a page about its type of problem. */
+    links?: ErrorLinks;
+    /**
+     * Reads what the upstream error's `meta` promises into this error's `meta` - omit to render none.
+     *
+     * It returns what its parse produced, never `upstream` as received: the schema is what keeps a member the service
+     * adds later from crossing. `undefined` answers the fallback, because a mapped code missing the data its contract
+     * promises is an answer this transport does not recognise.
+     */
+    meta?: (upstream: Meta | undefined) => Meta | undefined;
+}
+/**
+ * Binds one fronted service's answers and fallback into the function translating its rendered document into this
+ * transport's own error, to be thrown so `onError` renders it.
+ *
+ * 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.
+ */
+export declare function createUpstreamErrorTranslator(answers: UpstreamErrorMap, fallback: Omit<UpstreamErrorAnswer, 'meta'>): (document: ErrorDocument) => JsonApiError;
+//# sourceMappingURL=upstream-error.d.ts.map

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

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

package/dist/upstream-error.js

@@ -0,0 +1,33 @@
+import { JsonApiError } from './errors/jsonapi-error.js';
+function toJsonApiError(answer, meta) {
+    return new JsonApiError({
+        status: answer.status,
+        title: answer.title,
+        code: answer.code,
+        detail: answer.detail,
+        links: answer.links,
+        meta,
+    });
+}
+/**
+ * Binds one fronted service's answers and fallback into the function translating its rendered document into this
+ * transport's own error, to be thrown so `onError` renders it.
+ *
+ * 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.
+ */
+export function createUpstreamErrorTranslator(answers, fallback) {
+    return (document) => {
+        const [upstream] = document.errors;
+        const answer = upstream?.code === undefined ? undefined : answers[upstream.code];
+        if (answer === undefined) {
+            return toJsonApiError(fallback);
+        }
+        if (answer.meta === undefined) {
+            return toJsonApiError(answer);
+        }
+        const meta = answer.meta(upstream?.meta);
+        return meta === undefined ? toJsonApiError(fallback) : toJsonApiError(answer, meta);
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@zeroxsolutions/response",
+  "version": "0.12.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "The response half of the HTTP contract shared across ZeroXSolutions services and the edge gateway - JSON:API resource declarations and their serializers, the three OpenAPI response descriptors (okResponse / listResponse / errorResponse) every route spells its `responses` from, and the error document and error map.",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "ts-japi": "^1.12.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "zod": "^4.3.6"
+  },
+  "nx": {
+    "name": "@zeroxsolutions/response"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}