@zeroxsolutions/jsonapi 0.13.7 → 0.13.8

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 0.13.8 (2026-10-22)
+
+### 🚀 Features
+
+- **jsonapi:** read a refused response into an api error ([723fa9a](https://github.com/zeroxsolutions/zeroxsolutions/commit/723fa9a))
+
+### 💅 Refactors
+
+- **jsonapi:** name the refused-response read errorOf ([7bd0c02](https://github.com/zeroxsolutions/zeroxsolutions/commit/7bd0c02))
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
 ## 0.13.7 (2026-10-21)
 
 This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.

package/README.md

@@ -27,7 +27,7 @@ what keeps `hono` out of the package an SPA also loads.
 | Import                           | Use in                  | What it holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@zeroxsolutions/jsonapi`        | services, gateway       | `negotiateJsonApi` - the whole decision, from `Content-Type`, `Accept` and the `ext` URIs this surface supports (`supportedExtensions`), to the `JsonApiError` to reject with or `null`: 415 where `Content-Type` is the JSON:API media type carrying a parameter beyond `ext`/`profile` or an `ext` outside `supportedExtensions`; 406 where `Accept` holds JSON:API instances and every one carries such a parameter or `ext`; nothing else. `findOptionsOf` - a guarded query to the options `@zeroxsolutions/db`'s finders take |
-| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; `toRequestDocument`, the JSON:API request document a write sends, each relationship wrapped in its relationship object; and `ApiError`, the non-2xx a caller throws once a response has come back                                                                                                               |
+| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; `toRequestDocument`, the JSON:API request document a write sends, each relationship wrapped in its relationship object; `ApiError`, the non-2xx a caller throws once a response has come back, and `errorOf`, which reads one off that response                                                                 |
 
 A transport mounts the decision rather than calling it: `jsonApiContentNegotiation` is the Hono adapter
 over it, and it lives with the other framework wiring. `negotiateJsonApi` itself takes the surface's
@@ -47,10 +47,42 @@ response type, which is what keeps the model off a hand-written interface:
 ```ts
 // the query layer - the only place the document is spelled
 type SubjectList = CollectionOf<InferResponseType<(typeof api.v1.orgs)[':orgId']['subjects']['$get'], 200>>;
-if (!res.ok) throw new ApiError(res.status, await res.json().catch(() => null));
+if (!res.ok) throw await errorOf(res);
 const { data, meta } = readCollection(await res.json());
 ```
 
+A refused response is read into an `ApiError` by `errorOf`, never by reading the body by hand. It reads the body
+once and parses it as an error document, so `body` holds every error object the server sent, in its order, and is
+`null` where the failing tier sent no error document: a proxy's HTML page, an empty body, or JSON of another shape.
+Parsed rather than trusted, a body with no `errors` cannot make the throw itself throw:
+
+```ts
+import { ApiError, errorOf } from '@zeroxsolutions/jsonapi/client';
+
+async function read(res: Response): Promise<unknown> {
+  if (!res.ok) throw await errorOf(res);
+  return res.json();
+}
+
+const refusal = {
+  errors: [{ code: 'api.bad_request', source: { pointer: '/data/attributes/name' } }, { code: 'api.conflict' }],
+};
+
+try {
+  await read(new Response(JSON.stringify(refusal), { status: 422 }));
+} catch (error) {
+  if (error instanceof ApiError) {
+    error.status; // 422
+    error.body?.errors.map((object) => object.code); // ['api.bad_request', 'api.conflict']
+  }
+}
+
+(await errorOf(new Response('<html>502 Bad Gateway</html>', { status: 502 }))).body; // null
+```
+
+The body is read once, so a caller that reads it too hands `errorOf` a `clone()`. What a screen draws for each
+code, and which field a pointer names, is the screen's, so neither is here.
+
 Only `data` is flattened. `links` and `meta` keep the names the standard gives them, and `meta` stays
 free-form - the standard puts no member in it, so a row count there is one surface's own convention.
 

package/dist/client/api-error.d.ts

@@ -1,4 +1,4 @@
-import type { ErrorDocument } from '@zeroxsolutions/response';
+import { type ErrorDocument } from '@zeroxsolutions/response';
 /**
  * A non-2xx response, as the client that made the request holds it.
  *
@@ -11,4 +11,19 @@ export declare class ApiError extends Error {
     readonly body: ErrorDocument | null;
     constructor(status: number, body: ErrorDocument | null);
 }
+/**
+ * The {@link ApiError} a refused response yields: its status, and the error document its body holds, every error
+ * object kept in the order the server sent them.
+ *
+ * Reads the body once, so the response must not have been read before; a caller that needs the body for anything
+ * else hands this a clone. `body` is null where the body is no JSON, such as a proxy's HTML page or an empty body,
+ * and where it is JSON but no error document. It never rejects.
+ *
+ * @example
+ * if (!response.ok) throw await errorOf(response);
+ */
+export declare function errorOf(response: {
+    readonly status: number;
+    json(): Promise<unknown>;
+}): Promise<ApiError>;
 //# sourceMappingURL=api-error.d.ts.map

package/dist/client/api-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../src/client/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;gBAD1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAAG,IAAI;CAKtC"}
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../src/client/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEnF;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;gBAD1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAAG,IAAI;CAKtC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,OAAO,CAAC,QAAQ,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAIhH"}

package/dist/client/api-error.js

@@ -1,3 +1,4 @@
+import { errorDocumentSchema } from '@zeroxsolutions/response';
 /**
  * A non-2xx response, as the client that made the request holds it.
  *
@@ -15,3 +16,18 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+/**
+ * The {@link ApiError} a refused response yields: its status, and the error document its body holds, every error
+ * object kept in the order the server sent them.
+ *
+ * Reads the body once, so the response must not have been read before; a caller that needs the body for anything
+ * else hands this a clone. `body` is null where the body is no JSON, such as a proxy's HTML page or an empty body,
+ * and where it is JSON but no error document. It never rejects.
+ *
+ * @example
+ * if (!response.ok) throw await errorOf(response);
+ */
+export async function errorOf(response) {
+    const document = errorDocumentSchema.safeParse(await response.json().catch(() => null));
+    return new ApiError(response.status, document.success ? document.data : null);
+}

package/dist/client/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * The client half of the standard: the document a response carries, flattened once, the document a write sends, and
- * the failure a caller throws.
+ * the failure a caller throws, read off the response that refused it.
  */
-export { ApiError } from './api-error.js';
+export { ApiError, errorOf } from './api-error.js';
 export { deserializeDocument } from './deserialize.js';
 export { readCollection, readRelated, readResource, type Collection, type CollectionOf, type Resource, type ResourceOf, } from './read-document.js';
 export { toRequestDocument, type RelationshipInput, type ToRequestDocument } from './request-document.js';

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EACL,cAAc,EACd,WAAW,EACX,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/client/index.js

@@ -1,8 +1,8 @@
 /**
  * The client half of the standard: the document a response carries, flattened once, the document a write sends, and
- * the failure a caller throws.
+ * the failure a caller throws, read off the response that refused it.
  */
-export { ApiError } from './api-error.js';
+export { ApiError, errorOf } from './api-error.js';
 export { deserializeDocument } from './deserialize.js';
 export { readCollection, readRelated, readResource, } from './read-document.js';
 export { toRequestDocument } from './request-document.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/jsonapi",
-  "version": "0.13.7",
+  "version": "0.13.8",
   "private": false,
   "type": "module",
   "sideEffects": false,