@zeroxsolutions/jsonapi 0.11.3 → 0.12.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.12.0 (2026-09-28)
+
+### 🩹 Fixes
+
+- **jsonapi:** read every content-type parameter, q included ([07f81b9](https://github.com/zeroxsolutions/zeroxsolutions/commit/07f81b9))
+- ⚠️  **jsonapi:** negotiate ext, q, wildcards and content-type per spec ([2e2ffad](https://github.com/zeroxsolutions/zeroxsolutions/commit/2e2ffad))
+- **jsonapi:** read q as a weight when parsing a media type ([5403c39](https://github.com/zeroxsolutions/zeroxsolutions/commit/5403c39))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** negotiate ext, q, wildcards and content-type per spec  ([2e2ffad](https://github.com/zeroxsolutions/zeroxsolutions/commit/2e2ffad))
+  a Content-Type wildcard or a missing Content-Type is 415; an unsupported ext is 415 or 406; a wildcard no longer hides modified JSON:API Accept members; q=0 refuses a member.
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 0.11.3 (2026-09-27)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
 ## 0.11.2 (2026-09-27)
 
 This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.

package/README.md

@@ -26,7 +26,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 two header strings to the `JsonApiError` to reject with or `null`: 415 unless a write's media type is JSON:API carrying at most `ext`/`profile`, 406 unless some `Accept` member names that same type or a wildcard range |
+| `@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 on a write unless `Content-Type` is exactly the JSON:API media type, carrying no parameter beyond `ext`/`profile` and no `ext` outside `supportedExtensions` - a body sent with no `Content-Type` header is refused the same way; 406 unless some `Accept` member names that same servable JSON:API media type - once one does, only JSON:API members decide - or, failing that, a wildcard range weighted above zero |
 | `@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; and `ApiError`, the non-2xx a caller throws once a response has come back |
 
 A transport mounts the decision rather than calling it: `jsonApiContentNegotiation` is the Hono adapter
@@ -59,12 +59,19 @@ through the same central `onError` as every other failure rather than a shape of
 offending header in `source` and, in `detail`, what the surface reads or answers in - never the value the
 caller sent, which teaches the caller nothing it did not already have.
 
-Two decisions the headers alone do not settle:
+What the headers alone do not settle:
 
 - **`Content-Type` is read only where the request carries a body.** RFC 9110 gives a GET payload no defined
   semantics, so a read route has no representation to describe; reading the header there would turn a
-  client-wide default of `application/json` into a 415 on every collection.
+  client-wide default of `application/json` into a 415 on every collection. Where the route does read one, a
+  body sent with no `Content-Type` header is refused the same way an unservable type is.
+- **Once `Accept` names the JSON:API media type at all, only those members decide.** The standard answers 406
+  when every one of them is unacceptable, and a wildcard sitting beside them does not change that. Failing
+  that, a wildcard range weighted above zero is enough.
+- **A `q` of 0 refuses that member**, the same way a parameter the media type does not allow does.
+- **An `ext` URI outside `supportedExtensions` makes that JSON:API instance unservable** - a 415 where it
+  names `Content-Type`, or dropped from the members `Accept` considers, which is a 406 where nothing else in
+  it serves. `supportedExtensions` is `negotiateJsonApi`'s fourth parameter: the extension URIs this surface
+  answers `ext` requests for, empty by default, which refuses every `ext`.
 - **An empty `Accept` is refused.** RFC 9110 12.5.1 gives an *absent* header any media type, but an empty
-  field-value is a zero-member list, and no member of it names a range this surface can answer. A weight
-  goes unread, so a wildcard weighted to zero - a client stating that nothing at all is acceptable - is let
-  through; every other unsatisfiable header is caught by the range alone.
+  field-value is a zero-member list, and no member of it names a range this surface can answer.

package/dist/lib/negotiation/media-type.d.ts

@@ -1,10 +1,29 @@
-/** A parsed media type: its base `type` (lower-cased) and the parameter names present. */
+/** A parsed media type: its base type (lower-cased), its parameters up to the weight, and the weight. */
 export interface ParsedMediaType {
     type: string;
-    params: string[];
+    params: Map<string, string>;
+    /** The `q` weight, 1 where none is given. It is not a parameter of the media type (RFC 9110 12.4.2). */
+    weight: number;
 }
-/** Parses one media-type string (e.g. `application/vnd.api+json; ext="..."`) into its type and param names. */
-export declare function parseMediaType(value: string): ParsedMediaType;
+/** Tunes {@link parseMediaType} for which header it reads a media type off. */
+export interface ParseMediaTypeOptions {
+    /**
+     * Whether `q` ends the media type's own parameters and starts the accept-params RFC 9110 12.4.2 defines -
+     * true for an `Accept` member. A `Content-Type` carries no such split: `q` there is a parameter like any
+     * other, so it is read as one rather than as a weight.
+     */
+    readWeight?: boolean;
+}
+/**
+ * Parses one media type or Accept member into its type, its parameters, and its weight.
+ *
+ * `q` is a weight only where {@link ParseMediaTypeOptions.readWeight} says so (the default, for `Accept`);
+ * everywhere else it is one parameter among the rest, so `Content-Type` keeps every one it is sent, `q`
+ * included, and a wrong one there is still caught as a disallowed parameter rather than dropped unread.
+ */
+export declare function parseMediaType(value: string, options?: ParseMediaTypeOptions): ParsedMediaType;
+/** The extension URIs an `ext` parameter names, which is a space-separated list. */
+export declare function extensionsOf(parsed: ParsedMediaType): string[];
 /** True if the media type is JSON:API but carries a parameter other than `ext`/`profile`. */
 export declare function isJsonApiWithDisallowedParams(parsed: ParsedMediaType): boolean;
 //# sourceMappingURL=media-type.d.ts.map

package/dist/lib/negotiation/media-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-type.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/media-type.ts"],"names":[],"mappings":"AAKA,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,+GAA+G;AAC/G,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAO7D;AAED,6FAA6F;AAC7F,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAE9E"}
+{"version":3,"file":"media-type.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/media-type.ts"],"names":[],"mappings":"AAKA,yGAAyG;AACzG,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,wGAAwG;IACxG,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,eAAe,CAiBlG;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,EAAE,CAE9D;AAED,6FAA6F;AAC7F,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAE9E"}

package/dist/lib/negotiation/media-type.js

@@ -1,16 +1,38 @@
 import { JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
 /** Media-type parameters JSON:API v1.1 permits on its media type. */
 const ALLOWED_PARAMS = new Set(['ext', 'profile']);
-/** Parses one media-type string (e.g. `application/vnd.api+json; ext="..."`) into its type and param names. */
-export function parseMediaType(value) {
+const unquote = (value) => (value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value);
+/**
+ * Parses one media type or Accept member into its type, its parameters, and its weight.
+ *
+ * `q` is a weight only where {@link ParseMediaTypeOptions.readWeight} says so (the default, for `Accept`);
+ * everywhere else it is one parameter among the rest, so `Content-Type` keeps every one it is sent, `q`
+ * included, and a wrong one there is still caught as a disallowed parameter rather than dropped unread.
+ */
+export function parseMediaType(value, options = {}) {
+    const { readWeight = true } = options;
     const [rawType, ...rest] = value.split(';');
-    const type = (rawType ?? '').trim().toLowerCase();
-    const params = rest
-        .map((part) => part.split('=')[0]?.trim().toLowerCase())
-        .filter((name) => Boolean(name));
-    return { type, params };
+    const params = new Map();
+    let weight = 1;
+    for (const part of rest) {
+        const [rawName = '', ...rawValue] = part.split('=');
+        const name = rawName.trim().toLowerCase();
+        if (name === '')
+            continue;
+        const text = unquote(rawValue.join('=').trim());
+        if (readWeight && name === 'q') {
+            weight = Number(text);
+            break;
+        }
+        params.set(name, text);
+    }
+    return { type: (rawType ?? '').trim().toLowerCase(), params, weight: Number.isNaN(weight) ? 0 : weight };
+}
+/** The extension URIs an `ext` parameter names, which is a space-separated list. */
+export function extensionsOf(parsed) {
+    return (parsed.params.get('ext') ?? '').split(' ').filter(Boolean);
 }
 /** True if the media type is JSON:API but carries a parameter other than `ext`/`profile`. */
 export function isJsonApiWithDisallowedParams(parsed) {
-    return parsed.type === JSON_API_MEDIA_TYPE && parsed.params.some((param) => !ALLOWED_PARAMS.has(param));
+    return parsed.type === JSON_API_MEDIA_TYPE && [...parsed.params.keys()].some((param) => !ALLOWED_PARAMS.has(param));
 }

package/dist/lib/negotiation/negotiate.d.ts

@@ -1,18 +1,24 @@
 import { JsonApiError } from '@zeroxsolutions/response';
 /**
  * Framework-neutral JSON:API v1.1 content-negotiation decision computed from request headers:
- * - **415** unless `Content-Type` is the JSON:API media type carrying no parameter other than `ext`/`profile`;
- * - **406** unless some `Accept` member names a wildcard range or that same clean JSON:API media type.
+ * - **415** unless `Content-Type` is exactly the JSON:API media type, carrying no parameter other than
+ *   `ext`/`profile` and no `ext` URI outside `supportedExtensions`. An empty `Content-Type` means a body sent
+ *   without one, and is refused the same way: a wildcard never stands in for the one type this surface reads.
+ * - **406** unless some `Accept` member names that same servable JSON:API media type, or, where none does, a
+ *   wildcard range weighted above zero. An extension outside `supportedExtensions` makes a JSON:API instance
+ *   unservable, which is a 415 in `Content-Type` and drops that instance from `Accept`. A `q` of 0 refuses
+ *   that member the same way a disallowed parameter does.
  *
  * An EMPTY `Accept` is refused, deliberately: RFC 9110 12.5.1 gives an ABSENT header any media type, and an
  * empty field-value is a zero-member list rather than an absent header, so nothing in it names a range this
- * surface can answer. A weight goes unread, so a wildcard weighted to zero - a client stating that nothing at
- * all is acceptable - is let through; every other unsatisfiable header is caught by the range alone.
+ * surface can answer.
  *
  * @param contentType - `undefined` where the request carries no content: RFC 9110 gives a GET payload no
- * defined semantics, so reading it there would make every 415 on a read route a false one
+ * defined semantics, so reading it there would make every 415 on a read route a false one. `''` means a body
+ * sent with no `Content-Type` header.
  * @param namespace - the vocabulary this surface's own codes carry, so a refusal reads as one of them
+ * @param supportedExtensions - the extension URIs this surface answers `ext` requests for; empty by default
  * @returns the {@link JsonApiError} to reject with, or `null` when negotiation passes
  */
-export declare function negotiateJsonApi(contentType: string | undefined, accept: string | undefined, namespace: string): JsonApiError | null;
+export declare function negotiateJsonApi(contentType: string | undefined, accept: string | undefined, namespace: string, supportedExtensions?: ReadonlySet<string>): JsonApiError | null;
 //# sourceMappingURL=negotiate.d.ts.map

package/dist/lib/negotiation/negotiate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/negotiate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAY/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,SAAS,EAAE,MAAM,GAChB,YAAY,GAAG,IAAI,CAuBrB"}
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/negotiate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AA4B/F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,SAAS,EAAE,MAAM,EACjB,mBAAmB,GAAE,WAAW,CAAC,MAAM,CAAa,GACnD,YAAY,GAAG,IAAI,CAuBrB"}

package/dist/lib/negotiation/negotiate.js

@@ -1,30 +1,49 @@
 import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
-import { isJsonApiWithDisallowedParams, parseMediaType } from './media-type.js';
+import { extensionsOf, isJsonApiWithDisallowedParams, parseMediaType } from './media-type.js';
 /** The ranges an `Accept` member may name and still be satisfied by the one type a JSON:API surface answers in. */
 const WILDCARD_RANGES = new Set(['application/*', '*/*']);
-/** True if this `Accept` member names a range the surface can answer: a wildcard, or clean JSON:API. */
-function isAcceptable(parsed) {
-    if (WILDCARD_RANGES.has(parsed.type))
-        return true;
-    return parsed.type === JSON_API_MEDIA_TYPE && !isJsonApiWithDisallowedParams(parsed);
+/** A JSON:API instance this surface can answer: weighted above zero, no parameter but ext/profile, every ext supported. */
+function isServable(parsed, supported) {
+    return (parsed.type === JSON_API_MEDIA_TYPE &&
+        parsed.weight > 0 &&
+        !isJsonApiWithDisallowedParams(parsed) &&
+        extensionsOf(parsed).every((uri) => supported.has(uri)));
+}
+/**
+ * Whether an Accept header names something this surface answers in. Where it names the JSON:API media type at
+ * all, only those instances decide: the standard answers 406 when every one is modified, and a wildcard beside
+ * them does not change that. Otherwise a wildcard weighted above zero is enough.
+ */
+function isAcceptable(accept, supported) {
+    const members = accept.split(',').map((member) => parseMediaType(member));
+    const jsonApi = members.filter((member) => member.type === JSON_API_MEDIA_TYPE);
+    if (jsonApi.length > 0)
+        return jsonApi.some((member) => isServable(member, supported));
+    return members.some((member) => WILDCARD_RANGES.has(member.type) && member.weight > 0);
 }
 /**
  * Framework-neutral JSON:API v1.1 content-negotiation decision computed from request headers:
- * - **415** unless `Content-Type` is the JSON:API media type carrying no parameter other than `ext`/`profile`;
- * - **406** unless some `Accept` member names a wildcard range or that same clean JSON:API media type.
+ * - **415** unless `Content-Type` is exactly the JSON:API media type, carrying no parameter other than
+ *   `ext`/`profile` and no `ext` URI outside `supportedExtensions`. An empty `Content-Type` means a body sent
+ *   without one, and is refused the same way: a wildcard never stands in for the one type this surface reads.
+ * - **406** unless some `Accept` member names that same servable JSON:API media type, or, where none does, a
+ *   wildcard range weighted above zero. An extension outside `supportedExtensions` makes a JSON:API instance
+ *   unservable, which is a 415 in `Content-Type` and drops that instance from `Accept`. A `q` of 0 refuses
+ *   that member the same way a disallowed parameter does.
  *
  * An EMPTY `Accept` is refused, deliberately: RFC 9110 12.5.1 gives an ABSENT header any media type, and an
  * empty field-value is a zero-member list rather than an absent header, so nothing in it names a range this
- * surface can answer. A weight goes unread, so a wildcard weighted to zero - a client stating that nothing at
- * all is acceptable - is let through; every other unsatisfiable header is caught by the range alone.
+ * surface can answer.
  *
  * @param contentType - `undefined` where the request carries no content: RFC 9110 gives a GET payload no
- * defined semantics, so reading it there would make every 415 on a read route a false one
+ * defined semantics, so reading it there would make every 415 on a read route a false one. `''` means a body
+ * sent with no `Content-Type` header.
  * @param namespace - the vocabulary this surface's own codes carry, so a refusal reads as one of them
+ * @param supportedExtensions - the extension URIs this surface answers `ext` requests for; empty by default
  * @returns the {@link JsonApiError} to reject with, or `null` when negotiation passes
  */
-export function negotiateJsonApi(contentType, accept, namespace) {
-    if (contentType !== undefined && !isAcceptable(parseMediaType(contentType))) {
+export function negotiateJsonApi(contentType, accept, namespace, supportedExtensions = new Set()) {
+    if (contentType !== undefined && !isServable(parseMediaType(contentType, { readWeight: false }), supportedExtensions)) {
         return new JsonApiError({
             // The entry FIRST: it carries no `code` today, and the explicit one has to win the day it does.
             ...BASE_ERROR_CODES.UNSUPPORTED_MEDIA_TYPE,
@@ -35,7 +54,7 @@ export function negotiateJsonApi(contentType, accept, namespace) {
             source: { header: 'Content-Type' },
         });
     }
-    if (accept !== undefined && !accept.split(',').map(parseMediaType).some(isAcceptable)) {
+    if (accept !== undefined && !isAcceptable(accept, supportedExtensions)) {
         return new JsonApiError({
             ...BASE_ERROR_CODES.NOT_ACCEPTABLE,
             code: `${namespace}.not_acceptable`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/jsonapi",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -30,6 +30,6 @@
   "dependencies": {
     "jsona": "^1.12.0",
     "tslib": "^2.3.0",
-    "@zeroxsolutions/response": "0.13.0"
+    "@zeroxsolutions/response": "0.14.0"
   }
 }