@zeroxsolutions/jsonapi 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 0.13.0 (2026-09-29)
+
+### 🩹 Fixes
+
+- ⚠️  **jsonapi:** negotiate by the four json:api server rules alone ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** negotiate by the four json:api server rules alone  ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
+  negotiateJsonApi returns null for a Content-Type that
+  is not the JSON:API media type (or absent), and for an Accept that holds
+  no JSON:API instance. A route refuses a body it cannot read through its
+  own body validation.
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 0.12.1 (2026-09-28)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
 ## 0.12.0 (2026-09-28)
 
 ### 🩹 Fixes

package/README.md

@@ -3,7 +3,7 @@
 The [JSON:API v1.1](https://jsonapi.org/) halves that are **not** a response body: content negotiation
 on the request, and document deserialization on the client.
 
-Everything a server puts *in* a response - the document schemas, the serializers, the `errors[]`
+Everything a server puts _in_ a response - the document schemas, the serializers, the `errors[]`
 document - is `@zeroxsolutions/response`, and the central `onError` that renders it is
 `@zeroxsolutions/server`. The **query families** are `@zeroxsolutions/query`, which speaks this
 standard's spelling (`page[limit]`, a comma-separated `sort`, the labelled `filter` grammar,
@@ -24,10 +24,10 @@ what keeps `hono` out of the package an SPA also loads.
 
 ## Entry points
 
-| 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 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 |
+| 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 |
+| `@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
 over it, and it lives with the other framework wiring. `negotiateJsonApi` itself takes the surface's
@@ -59,19 +59,18 @@ 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.
 
-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. 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.
+The decision is the four server rules of JSON:API v1.1 and nothing more:
+
+- **Only the JSON:API media type is judged.** A `Content-Type` naming another type, or none, and an `Accept`
+  naming no JSON:API instance, are cases the standard sets no rule for, so they pass. A body the route
+  cannot read is refused by the route's own body validation.
+- **The body is never consulted.** A `Content-Type` with a disallowed parameter is a 415 on a request with no
+  body too, because the standard's rule names the header, not the content. A runtime decides for itself
+  whether a bodyless request has a `body` (workerd hands every POST a stream), so a decision keyed on it
+  answers differently per runtime.
+- **In `Accept`, `q` is a weight, not a parameter.** An instance weighted 0 is still unmodified, so it does
+  not make the header a 406.
+- **An `ext` URI outside `supportedExtensions` makes that JSON:API instance unusable** - a 415 where it
+  names `Content-Type`, or one fewer usable member in `Accept`, which is a 406 where none is left.
+  `supportedExtensions` is `negotiateJsonApi`'s fourth parameter: the extension URIs this surface answers
+  `ext` requests for, empty by default, which refuses every `ext`.

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

@@ -1,21 +1,19 @@
 import { JsonApiError } from '@zeroxsolutions/response';
 /**
- * Framework-neutral JSON:API v1.1 content-negotiation decision computed from request headers:
- * - **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.
+ * JSON:API v1.1 content negotiation, decided from the request headers and nothing else. The standard's four
+ * server rules are the whole of it:
+ * - **415** where `Content-Type` is the JSON:API media type and carries a parameter other than `ext`/`profile`,
+ *   or an `ext` URI outside `supportedExtensions`.
+ * - **406** where `Accept` holds JSON:API instances and every one carries a parameter other than
+ *   `ext`/`profile`, or an `ext` URI outside `supportedExtensions`.
  *
- * 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.
+ * Nothing else is refused. A `Content-Type` naming another media type, or none, and an `Accept` naming no
+ * JSON:API instance, are cases the standard sets no rule for, so a body in another type reaches the route,
+ * whose body validation refuses what it cannot read. The rules hold whether or not the request carries a
+ * body, so no runtime's idea of an empty body can change the 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. `''` means a body
- * sent with no `Content-Type` header.
+ * @param contentType - the `Content-Type` header, `undefined` where the request sent none
+ * @param accept - the `Accept` header, `undefined` where the request sent none
  * @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

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;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"}
+{"version":3,"file":"negotiate.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/negotiate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,YAAY,EAAuB,MAAM,0BAA0B,CAAC;AAQ/F;;;;;;;;;;;;;;;;;;GAkBG;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,CA4BrB"}

package/dist/lib/negotiation/negotiate.js

@@ -1,64 +1,50 @@
 import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
 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/*', '*/*']);
-/** 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)));
+/** A JSON:API instance this surface can use: no parameter but ext/profile, and every ext supported. */
+function isUsable(parsed, supported) {
+    return !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 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.
+ * JSON:API v1.1 content negotiation, decided from the request headers and nothing else. The standard's four
+ * server rules are the whole of it:
+ * - **415** where `Content-Type` is the JSON:API media type and carries a parameter other than `ext`/`profile`,
+ *   or an `ext` URI outside `supportedExtensions`.
+ * - **406** where `Accept` holds JSON:API instances and every one carries a parameter other than
+ *   `ext`/`profile`, or an `ext` URI outside `supportedExtensions`.
  *
- * 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.
+ * Nothing else is refused. A `Content-Type` naming another media type, or none, and an `Accept` naming no
+ * JSON:API instance, are cases the standard sets no rule for, so a body in another type reaches the route,
+ * whose body validation refuses what it cannot read. The rules hold whether or not the request carries a
+ * body, so no runtime's idea of an empty body can change the 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. `''` means a body
- * sent with no `Content-Type` header.
+ * @param contentType - the `Content-Type` header, `undefined` where the request sent none
+ * @param accept - the `Accept` header, `undefined` where the request sent none
  * @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, supportedExtensions = new Set()) {
-    if (contentType !== undefined && !isServable(parseMediaType(contentType, { readWeight: false }), supportedExtensions)) {
+    const content = contentType === undefined ? undefined : parseMediaType(contentType, { readWeight: false });
+    if (content?.type === JSON_API_MEDIA_TYPE && !isUsable(content, 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,
             code: `${namespace}.unsupported_media_type`,
             // Names what the surface reads rather than what arrived: a failure body is a client-facing projection
             // too, and echoing the caller's own value teaches it nothing it did not send.
-            detail: `This surface reads ${JSON_API_MEDIA_TYPE}.`,
+            detail: `This surface reads ${JSON_API_MEDIA_TYPE} with no parameter but a supported ext or a profile.`,
             source: { header: 'Content-Type' },
         });
     }
-    if (accept !== undefined && !isAcceptable(accept, supportedExtensions)) {
+    const instances = (accept ?? '')
+        .split(',')
+        .map((member) => parseMediaType(member))
+        .filter((member) => member.type === JSON_API_MEDIA_TYPE);
+    if (instances.length > 0 && !instances.some((instance) => isUsable(instance, supportedExtensions))) {
         return new JsonApiError({
             ...BASE_ERROR_CODES.NOT_ACCEPTABLE,
             code: `${namespace}.not_acceptable`,
-            detail: `This surface answers ${JSON_API_MEDIA_TYPE}.`,
+            detail: `This surface answers ${JSON_API_MEDIA_TYPE} with no parameter but a supported ext or a profile.`,
             source: { header: 'Accept' },
         });
     }

package/package.json

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