@zeroxsolutions/jsonapi 0.13.7 → 0.14.0

package/CHANGELOG.md

@@ -1,3 +1,36 @@
+## 0.14.0 (2026-10-23)
+
+### 🚀 Features
+
+- ⚠️ **jsonapi:** carry a refusal as ResponseError with its Retry-After ([b176c1f](https://github.com/zeroxsolutions/zeroxsolutions/commit/b176c1f))
+
+### ⚠️ Breaking Changes
+
+- **jsonapi:** carry a refusal as ResponseError with its Retry-After ([b176c1f](https://github.com/zeroxsolutions/zeroxsolutions/commit/b176c1f))
+  ApiError is renamed ResponseError, with no alias left
+  behind; its constructor takes retryAfterSeconds as a third argument;
+  errorOf takes a clock ({ now(): Date }) as its second argument, and the
+  response it reads must carry headers.
+  Refs: #76
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 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; `ResponseError`, 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,54 @@ 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, clock); // clock: { now(): Date }, what a Retry-After date counts from
 const { data, meta } = readCollection(await res.json());
 ```
 
+A refused response is read into a `ResponseError` 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.
+
+It reads `Retry-After` too, on every status, into `retryAfterSeconds`: delay-seconds as sent, an HTTP-date as the whole
+seconds from the clock's `now()` until it, rounded up and never below 0, and `null` where the header is missing or in
+neither form. The clock is the caller's, so a spec hands it a fixed one:
+
+```ts
+import { ResponseError, errorOf } from '@zeroxsolutions/jsonapi/client';
+
+const clock = { now: (): Date => new Date() };
+
+async function read(res: Response): Promise<unknown> {
+  if (!res.ok) throw await errorOf(res, clock);
+  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 ResponseError) {
+    error.status; // 422
+    error.body?.errors.map((object) => object.code); // ['api.bad_request', 'api.conflict']
+    error.retryAfterSeconds; // null
+  }
+}
+
+(await errorOf(new Response('<html>502 Bad Gateway</html>', { status: 502 }), clock)).body; // null
+(await errorOf(new Response(null, { status: 429, headers: { 'Retry-After': '10' } }), clock)).retryAfterSeconds; // 10
+
+const fixed = { now: (): Date => new Date('2026-10-21T07:28:00Z') };
+const unavailable = new Response(null, { status: 503, headers: { 'Retry-After': 'Wed, 21 Oct 2026 07:30:00 GMT' } });
+(await errorOf(unavailable, fixed)).retryAfterSeconds; // 120
+```
+
+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/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 { ResponseError, errorOf } from './response-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,aAAa,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC7D,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 { ResponseError, errorOf } from './response-error.js';
 export { deserializeDocument } from './deserialize.js';
 export { readCollection, readRelated, readResource, } from './read-document.js';
 export { toRequestDocument } from './request-document.js';

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

@@ -0,0 +1,39 @@
+import { type ErrorDocument } from '@zeroxsolutions/response';
+/**
+ * A non-2xx response, as the client that made the request holds it.
+ *
+ * The counterpart of `JsonApiError`, which a SERVER raises for its `onError` to render: this one
+ * is what a caller throws once a response has already come back. `body` is null wherever the failing
+ * tier emitted no document - a proxy, a gateway timeout, or an auth server with a shape of its own.
+ * `retryAfterSeconds` is how long the response's `Retry-After` asked the caller to wait before asking
+ * again, and null where it named no wait or one in neither of the header's forms.
+ */
+export declare class ResponseError extends Error {
+    readonly status: number;
+    readonly body: ErrorDocument | null;
+    readonly retryAfterSeconds: number | null;
+    constructor(status: number, body: ErrorDocument | null, retryAfterSeconds: number | null);
+}
+/**
+ * The {@link ResponseError} a refused response yields: its status, the error document its body holds, every error
+ * object kept in the order the server sent them, and the wait its `Retry-After` names.
+ *
+ * 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.
+ *
+ * @param clock - what a `Retry-After` HTTP-date is counted from; `retryAfterSeconds` is the whole seconds from
+ * `clock.now()` until that date, rounded up and never below 0. Delay-seconds are taken as sent.
+ * @example
+ * if (!response.ok) throw await errorOf(response, { now: () => new Date() });
+ */
+export declare function errorOf(response: {
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+}, clock: {
+    now(): Date;
+}): Promise<ResponseError>;
+//# sourceMappingURL=response-error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response-error.d.ts","sourceRoot":"","sources":["../../src/client/response-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGnF;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,KAAK;IAEpC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;gBAFhC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAAG,IAAI,EAC1B,iBAAiB,EAAE,MAAM,GAAG,IAAI;CAK5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE;IACR,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACvD,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B,EACD,KAAK,EAAE;IAAE,GAAG,IAAI,IAAI,CAAA;CAAE,GACrB,OAAO,CAAC,aAAa,CAAC,CAKxB"}

package/dist/client/response-error.js

@@ -0,0 +1,41 @@
+import { errorDocumentSchema } from '@zeroxsolutions/response';
+import { retryAfterSecondsOf } from './retry-after.js';
+/**
+ * A non-2xx response, as the client that made the request holds it.
+ *
+ * The counterpart of `JsonApiError`, which a SERVER raises for its `onError` to render: this one
+ * is what a caller throws once a response has already come back. `body` is null wherever the failing
+ * tier emitted no document - a proxy, a gateway timeout, or an auth server with a shape of its own.
+ * `retryAfterSeconds` is how long the response's `Retry-After` asked the caller to wait before asking
+ * again, and null where it named no wait or one in neither of the header's forms.
+ */
+export class ResponseError extends Error {
+    status;
+    body;
+    retryAfterSeconds;
+    constructor(status, body, retryAfterSeconds) {
+        super(`Request failed with status ${status}`);
+        this.status = status;
+        this.body = body;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'ResponseError';
+    }
+}
+/**
+ * The {@link ResponseError} a refused response yields: its status, the error document its body holds, every error
+ * object kept in the order the server sent them, and the wait its `Retry-After` names.
+ *
+ * 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.
+ *
+ * @param clock - what a `Retry-After` HTTP-date is counted from; `retryAfterSeconds` is the whole seconds from
+ * `clock.now()` until that date, rounded up and never below 0. Delay-seconds are taken as sent.
+ * @example
+ * if (!response.ok) throw await errorOf(response, { now: () => new Date() });
+ */
+export async function errorOf(response, clock) {
+    const document = errorDocumentSchema.safeParse(await response.json().catch(() => null));
+    const retryAfterSeconds = retryAfterSecondsOf(response.headers.get('Retry-After'), clock.now());
+    return new ResponseError(response.status, document.success ? document.data : null, retryAfterSeconds);
+}

package/dist/client/retry-after.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The seconds a `Retry-After` value (RFC 9110 section 10.2.3) asks the caller to wait from `now`: delay-seconds as
+ * they are, an HTTP-date as the whole seconds until it, rounded up and never below 0. Null where `value` is null or
+ * is neither form.
+ */
+export declare function retryAfterSecondsOf(value: string | null, now: Date): number | null;
+//# sourceMappingURL=retry-after.d.ts.map

package/dist/client/retry-after.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-after.d.ts","sourceRoot":"","sources":["../../src/client/retry-after.ts"],"names":[],"mappings":"AAmFA;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAOlF"}

package/dist/client/retry-after.js

@@ -0,0 +1,69 @@
+const DELAY_SECONDS = /^\d+$/;
+const DAY_NAMES = '(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)';
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const MONTH = `(${MONTHS.join('|')})`;
+const TIME_OF_DAY = '(\\d{2}):(\\d{2}):(\\d{2})';
+/** `Sun, 06 Nov 1994 08:49:37 GMT`: day, month, year, hour, minute, second. */
+const IMF_FIXDATE = new RegExp(`^${DAY_NAMES}, (\\d{2}) ${MONTH} (\\d{4}) ${TIME_OF_DAY} GMT$`);
+/** `Sunday, 06-Nov-94 08:49:37 GMT`: day, month, two-digit year, hour, minute, second. */
+const RFC850_DATE = new RegExp(`^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\\d{2})-${MONTH}-(\\d{2}) ${TIME_OF_DAY} GMT$`);
+/** `Sun Nov  6 08:49:37 1994`: month, day padded with a space, hour, minute, second, year. */
+const ASCTIME_DATE = new RegExp(`^${DAY_NAMES} ${MONTH} ([ \\d]\\d) ${TIME_OF_DAY} (\\d{4})$`);
+/**
+ * The instant an HTTP-date names, in any of the three forms RFC 9110 section 5.6.7 has a recipient accept, or null
+ * where `value` is none of them or names no such day or time; a second of 60 is the leap second the RFC allows.
+ * `now` places an RFC 850 date's two-digit year.
+ */
+function instantOf(value, now) {
+    const parts = partsOf(value, now);
+    if (parts === null)
+        return null;
+    const [day, hour, minute, second] = [parts.day, parts.hour, parts.minute, parts.second].map(Number);
+    const month = MONTHS.indexOf(parts.month);
+    if (hour > 23 || minute > 59 || second > 60)
+        return null;
+    const minuteStart = new Date(Date.UTC(parts.year, month, day, hour, minute));
+    if (minuteStart.getUTCDate() !== day || minuteStart.getUTCMonth() !== month)
+        return null;
+    return minuteStart.getTime() + second * 1000;
+}
+/** The fields of whichever of the three forms `value` is, or null where it is none of them. */
+function partsOf(value, now) {
+    const fixdate = IMF_FIXDATE.exec(value);
+    if (fixdate) {
+        const [, day, month, year, hour, minute, second] = fixdate;
+        return { year: Number(year), month, day, hour, minute, second };
+    }
+    const rfc850 = RFC850_DATE.exec(value);
+    if (rfc850) {
+        const [, day, month, year, hour, minute, second] = rfc850;
+        return { year: fullYearOf(Number(year), now), month, day, hour, minute, second };
+    }
+    const asctime = ASCTIME_DATE.exec(value);
+    if (asctime) {
+        const [, month, day, hour, minute, second, year] = asctime;
+        return { year: Number(year), month, day: day.trim(), hour, minute, second };
+    }
+    return null;
+}
+/**
+ * The year a two-digit year names: the one ending in those digits that is no more than fifty years after `now`,
+ * which is how RFC 9110 section 5.6.7 has a recipient read an RFC 850 date.
+ */
+function fullYearOf(twoDigits, now) {
+    const year = now.getUTCFullYear() - (now.getUTCFullYear() % 100) + twoDigits;
+    return year > now.getUTCFullYear() + 50 ? year - 100 : year;
+}
+/**
+ * The seconds a `Retry-After` value (RFC 9110 section 10.2.3) asks the caller to wait from `now`: delay-seconds as
+ * they are, an HTTP-date as the whole seconds until it, rounded up and never below 0. Null where `value` is null or
+ * is neither form.
+ */
+export function retryAfterSecondsOf(value, now) {
+    if (value === null)
+        return null;
+    if (DELAY_SECONDS.test(value))
+        return Number(value);
+    const instant = instantOf(value, now);
+    return instant === null ? null : Math.max(0, Math.ceil((instant - now.getTime()) / 1000));
+}

package/package.json

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

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

@@ -1,14 +0,0 @@
-import type { ErrorDocument } from '@zeroxsolutions/response';
-/**
- * A non-2xx response, as the client that made the request holds it.
- *
- * The counterpart of `JsonApiError`, which a SERVER raises for its `onError` to render: this one
- * is what a caller throws once a response has already come back. `body` is null wherever the failing
- * tier emitted no document - a proxy, a gateway timeout, or an auth server with a shape of its own.
- */
-export declare class ApiError extends Error {
-    readonly status: number;
-    readonly body: ErrorDocument | null;
-    constructor(status: number, body: ErrorDocument | null);
-}
-//# sourceMappingURL=api-error.d.ts.map

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

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

package/dist/client/api-error.js

@@ -1,17 +0,0 @@
-/**
- * A non-2xx response, as the client that made the request holds it.
- *
- * The counterpart of `JsonApiError`, which a SERVER raises for its `onError` to render: this one
- * is what a caller throws once a response has already come back. `body` is null wherever the failing
- * tier emitted no document - a proxy, a gateway timeout, or an auth server with a shape of its own.
- */
-export class ApiError extends Error {
-    status;
-    body;
-    constructor(status, body) {
-        super(`Request failed with status ${status}`);
-        this.status = status;
-        this.body = body;
-        this.name = 'ApiError';
-    }
-}