@zeroxsolutions/jsonapi 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,367 @@
+## 0.11.0 (2026-09-13)
+
+### 💅 Refactors
+
+- ⚠️  **jsonapi:** list the names each entry publishes ([3746762](https://github.com/zeroxsolutions/zeroxsolutions/commit/3746762))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** list the names each entry publishes  ([3746762](https://github.com/zeroxsolutions/zeroxsolutions/commit/3746762))
+  the root no longer exports `parseMediaType`,
+  `isJsonApiWithDisallowedParams` or `ParsedMediaType`; `negotiateJsonApi`
+  is the negotiation decision. `./client` publishes the same names as
+  before, from `dist/client/index.js`.
+
+### ❤️ Thank You
+
+- Claude Sonnet 5
+- Lương Văn Tú
+
+## 0.10.4 (2026-09-13)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
+## 0.10.3 (2026-09-13)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
+## 0.10.2 (2026-09-13)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.11.2
+
+## 0.10.1 (2026-09-07)
+
+Version bump only, to take the repackaged `@zeroxsolutions/response`.
+
+## 0.10.0 (2026-09-07)
+
+### 🚀 Features
+
+- ⚠️  **server,jsonapi:** one surface, one error-code vocabulary ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
+
+### ⚠️  Breaking Changes
+
+- **server,jsonapi:** one surface, one error-code vocabulary  ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
+  createErrorHandler, createValidationHook and
+  jsonApiContentNegotiation take a required `namespace`; negotiateJsonApi takes it
+  as a third argument. Codes these mint are now `<namespace>.<name>`.
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.9.2 (2026-09-07)
+
+### 💅 Refactors
+
+- ⚠️  **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+
+### ⚠️  Breaking Changes
+
+- **query,response,server:** one wire spelling, flat exports  ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+  `@zeroxsolutions/response/http`, `@zeroxsolutions/query/http`
+  and `@zeroxsolutions/server/hono/http` are gone, and the surviving `/jsonapi`
+  and `/hono` subpaths move to the package root. Every import drops its subpath.
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.9.1 (2026-09-07)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
+## 0.9.0 (2026-09-07)
+
+### 💅 Refactors
+
+- ⚠️  **jsonapi:** widen negotiation, move its middleware out ([d28eb2b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d28eb2b))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** widen negotiation, move its middleware out  ([d28eb2b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d28eb2b))
+  jsonApiContentNegotiation is no longer exported here; it is
+  @zeroxsolutions/server. negotiateJsonApi answers 415 for any
+  Content-Type that is not the JSON:API media type, and 406 for an Accept naming
+  no range this surface answers, an empty one included - headers that previously
+  passed. Its errors now carry `detail` and `source`.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.8.4 (2026-09-03)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.7.3
+
+## 0.8.3 (2026-09-03)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.7.2
+
+## 0.8.2 (2026-09-03)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.7.1
+
+## 0.8.1 (2026-09-02)
+
+### 🚀 Features
+
+- **jsonapi:** read the related model an include resolved ([6faf408](https://github.com/zeroxsolutions/zeroxsolutions/commit/6faf408))
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.8.0 (2026-09-02)
+
+### 🚀 Features
+
+- **jsonapi:** carry a failed response as ApiError on the client half ([71e9554](https://github.com/zeroxsolutions/zeroxsolutions/commit/71e9554))
+
+### 🩹 Fixes
+
+- ⚠️  **jsonapi:** shape the collection model on the document, not the other spelling ([4ae8d26](https://github.com/zeroxsolutions/zeroxsolutions/commit/4ae8d26))
+- **jsonapi:** add the reader source the previous commit left untracked ([7399114](https://github.com/zeroxsolutions/zeroxsolutions/commit/7399114))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** shape the collection model on the document, not the other spelling  ([4ae8d26](https://github.com/zeroxsolutions/zeroxsolutions/commit/4ae8d26))
+  `Collection.items` is `Collection.data`, and `Collection.total`
+  is gone - read `meta` for it.
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.7.9 (2026-09-02)
+
+### 🚀 Features
+
+- **jsonapi:** read a document into a model typed off the route ([02d2205](https://github.com/zeroxsolutions/zeroxsolutions/commit/02d2205))
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.7.8 (2026-09-02)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.7.0
+
+## 0.7.7 (2026-09-02)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.6.1
+
+## 0.7.6 (2026-09-02)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.6.0
+
+## 0.7.5 (2026-09-02)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.5.0
+
+## 0.7.4 (2026-08-31)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.4.0
+
+## 0.7.3 (2026-08-31)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.3.0
+
+## 0.7.2 (2026-08-29)
+
+### 💅 Refactors
+
+- state an explicit return type on every function ([8ee4264](https://github.com/zeroxsolutions/zeroxsolutions/commit/8ee4264))
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.2.2
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
+## 0.7.1 (2026-08-28)
+
+### 🧱 Updated Dependencies
+
+- Updated @zeroxsolutions/response to 0.2.1
+
+## 0.6.0 (2026-08-16)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
+## 0.5.0 (2026-08-15)
+
+### 🚀 Features
+
+- **jsonapi:** let the query guard raise a plain typed error ([3d2084d](https://github.com/zeroxsolutions/zeroxsolutions/commit/3d2084d))
+
+### ❤️ Thank You
+
+- Claude Opus 5
+- Lương Văn Tú
+
+## 0.4.1 (2026-08-15)
+
+### 🚀 Features
+
+- **jsonapi:** compose a serialized document, not just validate one ([2135153](https://github.com/zeroxsolutions/zeroxsolutions/commit/2135153))
+
+### ❤️ Thank You
+
+- Claude Opus 5
+- Lương Văn Tú
+
+## 0.4.0 (2026-08-14)
+
+### 🚀 Features
+
+- ⚠️  **jsonapi:** bind the permit-list to a row and an operator vocabulary, and pipe the schema through it ([5f824d0](https://github.com/zeroxsolutions/zeroxsolutions/commit/5f824d0))
+- **jsonapi:** declare a list endpoint's query parameters from its permit-list ([bb3c3c8](https://github.com/zeroxsolutions/zeroxsolutions/commit/bb3c3c8))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** bind the permit-list to a row and an operator vocabulary, and pipe the schema through it  ([5f824d0](https://github.com/zeroxsolutions/zeroxsolutions/commit/5f824d0))
+  `jsonApiQuerySchema` now returns a piped schema whose output is
+  `GuardedJsonApiQuery`, not the raw query map. Unreleased, so no consumer is affected.
+  The two type-level checks are pinned by `@ts-expect-error` in a spec, watched failing
+  first: unbinding the generics turns both directives into "unused", which is the whole
+  failure mode a type test has.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú
+
+## 0.3.1 (2026-08-08)
+
+### 🩹 Fixes
+
+- **jsonapi:** state that an included resource needs its own serializer built from the query ([803aa30](https://github.com/zeroxsolutions/zeroxsolutions/commit/803aa30))
+- **db:** declare the query types once, in the package that owns the wire ([1c3498c](https://github.com/zeroxsolutions/zeroxsolutions/commit/1c3498c))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- luongvantuit
+
+## 0.3.0 (2026-08-08)
+
+### 🚀 Features
+
+- ⚠️  **jsonapi:** shape the document by the query, and close the escape hatch ([79da0f2](https://github.com/zeroxsolutions/zeroxsolutions/commit/79da0f2))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** shape the document by the query, and close the escape hatch  ([79da0f2](https://github.com/zeroxsolutions/zeroxsolutions/commit/79da0f2))
+  `customFamilies` removed from `JsonApiQuerySpec`, its
+  argument removed from `unprocessableQueryParams`, and `isCustomFamilyBase` no
+  longer exported. No declaration can accept a parameter outside the families
+  the wire standard defines.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- luongvantuit
+
+## 0.2.0 (2026-08-06)
+
+### 🚀 Features
+
+- ⚠️  **jsonapi:** bind the list query to a permit-list and parse the filter tree ([2c212b0](https://github.com/zeroxsolutions/zeroxsolutions/commit/2c212b0))
+- **jsonapi:** screen query parameters against the standard's grammar ([e7bd26c](https://github.com/zeroxsolutions/zeroxsolutions/commit/e7bd26c))
+- **jsonapi:** refuse a query the endpoint did not permit ([1dd1df6](https://github.com/zeroxsolutions/zeroxsolutions/commit/1dd1df6))
+
+### ⚠️  Breaking Changes
+
+- **jsonapi:** bind the list query to a permit-list and parse the filter tree  ([2c212b0](https://github.com/zeroxsolutions/zeroxsolutions/commit/2c212b0))
+  `parseJsonApiQuery` and `parseFilter` are removed;
+  `filterable` entries are `{ operators, type }` rather than a bare operator
+  list; `filter` is a bracketed family, not a JSON-encoded array; queries
+  that previously passed unnoticed now receive 400.
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- luongvantuit
+
+## 0.1.1 (2026-07-15)
+
+### 🚀 Features
+
+- **jsonapi:** allow typing the compound-document included array ([f1faa07](https://github.com/zeroxsolutions/zeroxsolutions/commit/f1faa07))
+
+### ❤️ Thank You
+
+- Claude Opus 4.8
+- Lương Văn Tú
+
+## 0.1.0 (2026-07-08)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
+## 0.0.4 (2026-07-06)
+
+### 🚀 Features
+
+- **jsonapi:** add a server error handler + error response to /server ([18eedc2](https://github.com/zeroxsolutions/zeroxsolutions/commit/18eedc2))
+
+### ❤️ Thank You
+
+- Claude Opus 4.8 (1M context)
+- Lương Văn Tú
+
+## 0.0.3 (2026-07-05)
+
+This was a version bump only for @zeroxsolutions/jsonapi to align it with other projects, there were no code changes.
+
+## 0.0.2 (2026-07-05)
+
+### 🚀 Features
+
+- **jsonapi:** extract framework-neutral negotiateJsonApi() from the Hono middleware ([e88d8ea](https://github.com/zeroxsolutions/zeroxsolutions/commit/e88d8ea))
+
+### ❤️ Thank You
+
+- Claude Opus 4.8 (1M context)
+- Lương Văn Tú
+
+## 0.0.1 (2026-07-05)
+
+### 🚀 Features
+
+- ⚠️  add JSON:API v1.1 toolkit and routing lib, dissolve common ([53545a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/53545a6))
+
+### ⚠️  Breaking Changes
+
+- add JSON:API v1.1 toolkit and routing lib, dissolve common  ([53545a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/53545a6))
+  @zeroxsolutions/common is removed. Its error/response
+  schemas move to @zeroxsolutions/jsonapi; its path/is-match helpers move to
+  @zeroxsolutions/routing.
+
+### ❤️ Thank You
+
+- Claude Opus 4.8 (1M context)
+- Lương Văn Tú

package/README.md

@@ -0,0 +1,70 @@
+# @zeroxsolutions/jsonapi
+
+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[]`
+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,
+`fields[TYPE]` and `include`).
+
+Three packages for one standard, split by which side of the exchange each serves: what the client
+asks for, what the server answers, and what the caller may address.
+
+## Install
+
+```sh
+pnpm add @zeroxsolutions/jsonapi @zeroxsolutions/response
+```
+
+No peer dep, and no framework: every export here is a plain function over strings and documents. The
+Hono middleware that mounts the negotiation decision is `@zeroxsolutions/server`, which is
+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 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/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
+namespace, because the refusal it returns is an error object the surface publishes.
+
+```ts
+// one middleware, before the routes - never a per-handler check
+import { jsonApiContentNegotiation } from '@zeroxsolutions/server';
+
+app.use('*', jsonApiContentNegotiation({ namespace: 'api' }));
+```
+
+A client flattens the envelope ONCE, at the layer that fetches, so nothing downstream reads
+`data[i].attributes`. `ResourceOf` / `CollectionOf` derive that flattened shape from the route's own
+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));
+const { data, meta } = readCollection(await res.json());
+```
+
+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.
+
+Negotiation raises `JsonApiError` from `@zeroxsolutions/response`, so the refusal renders
+through the same central `onError` as every other failure rather than a shape of its own. It names the
+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:
+
+- **`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.
+- **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.

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

@@ -0,0 +1,14 @@
+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

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

package/dist/client/api-error.js

@@ -0,0 +1,17 @@
+/**
+ * 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';
+    }
+}

package/dist/client/deserialize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Flattens a JSON:API document into plain model object(s) - `{ id, ...attributes }` - via jsona.
+ * Returns a single model or an array, mirroring the document's `data`.
+ *
+ * @example
+ * ```ts
+ * const student = deserializeDocument<Student>(document); // { id, ...attributes }
+ * ```
+ */
+export declare function deserializeDocument<T = unknown>(document: unknown): T;
+//# sourceMappingURL=deserialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deserialize.d.ts","sourceRoot":"","sources":["../../src/client/deserialize.ts"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,CAAC,CAErE"}

package/dist/client/deserialize.js

@@ -0,0 +1,14 @@
+import { Jsona } from 'jsona';
+const formatter = new Jsona();
+/**
+ * Flattens a JSON:API document into plain model object(s) - `{ id, ...attributes }` - via jsona.
+ * Returns a single model or an array, mirroring the document's `data`.
+ *
+ * @example
+ * ```ts
+ * const student = deserializeDocument<Student>(document); // { id, ...attributes }
+ * ```
+ */
+export function deserializeDocument(document) {
+    return formatter.deserialize(document);
+}

package/dist/client/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The client half of the standard: the document a response carries, flattened once, and the failure a caller throws.
+ */
+export { ApiError } 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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;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"}

package/dist/client/index.js

@@ -0,0 +1,6 @@
+/**
+ * The client half of the standard: the document a response carries, flattened once, and the failure a caller throws.
+ */
+export { ApiError } from './api-error.js';
+export { deserializeDocument } from './deserialize.js';
+export { readCollection, readRelated, readResource, } from './read-document.js';

package/dist/client/read-document.d.ts

@@ -0,0 +1,51 @@
+import type { CollectionDocument, Meta, PaginationLinks, ResourceDocument } from '@zeroxsolutions/response';
+/** One resource as a client holds it - the attributes, with the resource's own `id` and `type` beside them. */
+export type Resource<A> = A & {
+    id: string;
+    type: string;
+};
+/** A collection document with its `data` flattened; every other member keeps the name the standard gives it. */
+export interface Collection<A> {
+    data: Resource<A>[];
+    links?: PaginationLinks;
+    meta?: Meta;
+}
+/** The client shape of a single-resource route body, derived from the document that route declares. */
+export type ResourceOf<D> = D extends {
+    data: {
+        attributes: infer A;
+    };
+} ? Resource<A> : never;
+/** The client shape of a collection route body, derived from the document that route declares. */
+export type CollectionOf<D> = D extends {
+    data: readonly {
+        attributes: infer A;
+    }[];
+} ? Collection<A> : never;
+/** Reads a single-resource document into the model a client holds. */
+export declare function readResource<A>(document: ResourceDocument<A>): Resource<A>;
+/**
+ * Reads a collection document, flattening `data` and carrying `links` and `meta` through.
+ *
+ * jsona deserializes `data` alone, so the two top-level members are read here rather than from what
+ * {@link deserializeDocument} returns. `meta` stays free-form: the standard puts no member in it, and a
+ * count there is one surface's own convention, not a shape this package can promise.
+ */
+export declare function readCollection<A>(document: CollectionDocument<A>): Collection<A>;
+/**
+ * The related model an `include` resolved onto `name`, or null where the document carried none.
+ *
+ * A resource's declared attributes cannot name it: the standard puts a related resource in `included`
+ * and leaves `relationships.<name>` carrying linkage alone, so what an include resolved to is reachable
+ * at runtime and never from the type a route publishes. The caller therefore names the `type` it expects
+ * and gets null for anything else.
+ *
+ * A relationship the document declared but did NOT include deserializes to that linkage - `{ type, id }`
+ * and nothing more - which is answered null rather than handed back as a model missing every attribute.
+ * A related resource that declares no attributes of its own is indistinguishable from it.
+ */
+export declare function readRelated<M extends {
+    id: string;
+    type: string;
+}>(model: unknown, name: string, type: string): M | null;
+//# sourceMappingURL=read-document.d.ts.map

package/dist/client/read-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-document.d.ts","sourceRoot":"","sources":["../../src/client/read-document.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG5G,+GAA+G;AAC/G,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,gHAAgH;AAChH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED,uGAAuG;AACvG,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAE9F,kGAAkG;AAClG,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,IAAI,EAAE,SAAS;QAAE,UAAU,EAAE,MAAM,CAAC,CAAA;KAAE,EAAE,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;AAE7G,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAMhF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAChE,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,CAAC,GAAG,IAAI,CAMV"}

package/dist/client/read-document.js

@@ -0,0 +1,40 @@
+import { deserializeDocument } from './deserialize.js';
+/** Reads a single-resource document into the model a client holds. */
+export function readResource(document) {
+    return deserializeDocument(document);
+}
+/**
+ * Reads a collection document, flattening `data` and carrying `links` and `meta` through.
+ *
+ * jsona deserializes `data` alone, so the two top-level members are read here rather than from what
+ * {@link deserializeDocument} returns. `meta` stays free-form: the standard puts no member in it, and a
+ * count there is one surface's own convention, not a shape this package can promise.
+ */
+export function readCollection(document) {
+    return {
+        data: deserializeDocument(document),
+        ...(document.links ? { links: document.links } : {}),
+        ...(document.meta ? { meta: document.meta } : {}),
+    };
+}
+/**
+ * The related model an `include` resolved onto `name`, or null where the document carried none.
+ *
+ * A resource's declared attributes cannot name it: the standard puts a related resource in `included`
+ * and leaves `relationships.<name>` carrying linkage alone, so what an include resolved to is reachable
+ * at runtime and never from the type a route publishes. The caller therefore names the `type` it expects
+ * and gets null for anything else.
+ *
+ * A relationship the document declared but did NOT include deserializes to that linkage - `{ type, id }`
+ * and nothing more - which is answered null rather than handed back as a model missing every attribute.
+ * A related resource that declares no attributes of its own is indistinguishable from it.
+ */
+export function readRelated(model, name, type) {
+    const related = model?.[name];
+    if (related === null || typeof related !== 'object')
+        return null;
+    const candidate = related;
+    if (candidate['type'] !== type)
+        return null;
+    return Object.keys(candidate).some((key) => key !== 'type' && key !== 'id') ? candidate : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { negotiateJsonApi } from './lib/negotiation/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { negotiateJsonApi } from './lib/negotiation/index.js';

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

@@ -0,0 +1,3 @@
+export * from './media-type.js';
+export * from './negotiate.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/negotiation/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}

package/dist/lib/negotiation/index.js

@@ -0,0 +1,2 @@
+export * from './media-type.js';
+export * from './negotiate.js';

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

@@ -0,0 +1,10 @@
+/** A parsed media type: its base `type` (lower-cased) and the parameter names present. */
+export interface ParsedMediaType {
+    type: string;
+    params: string[];
+}
+/** 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;
+/** 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

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

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

@@ -0,0 +1,16 @@
+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 [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 };
+}
+/** 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));
+}

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

@@ -0,0 +1,18 @@
+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.
+ *
+ * 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.
+ *
+ * @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
+ * @param namespace - the vocabulary this surface's own codes carry, so a refusal reads as one of them
+ * @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;
+//# sourceMappingURL=negotiate.d.ts.map

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

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

package/dist/lib/negotiation/negotiate.js

@@ -0,0 +1,47 @@
+import { BASE_ERROR_CODES, JsonApiError, JSON_API_MEDIA_TYPE } from '@zeroxsolutions/response';
+import { 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);
+}
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @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
+ * @param namespace - the vocabulary this surface's own codes carry, so a refusal reads as one of them
+ * @returns the {@link JsonApiError} to reject with, or `null` when negotiation passes
+ */
+export function negotiateJsonApi(contentType, accept, namespace) {
+    if (contentType !== undefined && !isAcceptable(parseMediaType(contentType))) {
+        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}.`,
+            source: { header: 'Content-Type' },
+        });
+    }
+    if (accept !== undefined && !accept.split(',').map(parseMediaType).some(isAcceptable)) {
+        return new JsonApiError({
+            ...BASE_ERROR_CODES.NOT_ACCEPTABLE,
+            code: `${namespace}.not_acceptable`,
+            detail: `This surface answers ${JSON_API_MEDIA_TYPE}.`,
+            source: { header: 'Accept' },
+        });
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@zeroxsolutions/jsonapi",
+  "version": "0.11.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "The JSON:API halves that are not the response body: v1.1 content negotiation (media type, 415/406/400) and the client-side document deserializer. The response document, its serializers and its error document live in @zeroxsolutions/response.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "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"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "default": "./dist/client/index.js"
+    }
+  },
+  "dependencies": {
+    "jsona": "^1.12.0",
+    "tslib": "^2.3.0",
+    "@zeroxsolutions/response": "0.12.0"
+  }
+}