@haddowg/json-api-client 1.1.0 → 1.3.0

package/README.md

@@ -132,7 +132,7 @@ const albums = await client.albums.list({ withCount: ['tracks'] })
 All three collection surfaces (top-level lists, related collections, to-many relationship arrays)
 expose the same `$page` + `$next()` / `$prev()`. Navigation is **count-free-safe** — driven by
 link presence, not a total. Cursor pagination is just a paginator `kind`; page with
-`page[cursor]` / `page[size]` query params and walk it with `$next()`:
+`page[after]` / `page[before]` / `page[size]` query params and walk it with `$next()`:
 
 ```ts
 let page = await client.tracks.list({ page: { size: 50 } })
@@ -262,6 +262,10 @@ Status matchers: `hasStatus(n)`, `is4xx()`, `is5xx()`, `isBadRequest()` /400,
 `parameter`) — the payoff for form/validation UX. Each error keeps its raw `source.pointer` as an
 escape hatch; atomic errors also carry an `opIndex`.
 
+`hasErrorCode(err, code)` is true when `err` is a `JsonApiError` and any of its error objects
+carries `code`. A generated client exports a version bound to its server's documented `ErrorCode`
+union, so a misspelt code fails to compile and a match narrows to `JsonApiError<ErrorCode>`.
+
 > A response that parses but violates the JSON:API envelope shape (not a document, a member
 > missing `type`/`id`) throws a `StructuralGuardError` — distinct from a server-reported
 > `JsonApiError`. These light structural guards are always on; full per-field validation is opt-in

package/dist/ajv.d.cts

@@ -1,4 +1,4 @@
-import { a as Validator, n as SchemaMap } from "./validate-CfrCMZkA.cjs";
+import { a as Validator, n as SchemaMap } from "./validate-CJPivkqT.cjs";
 import { ValidateFunction } from "ajv";
 
 //#region src/ajv.d.ts

package/dist/ajv.d.mts

@@ -1,4 +1,4 @@
-import { a as Validator, n as SchemaMap } from "./validate-CfrCMZkA.mjs";
+import { a as Validator, n as SchemaMap } from "./validate-CJPivkqT.mjs";
 import { ValidateFunction } from "ajv";
 
 //#region src/ajv.d.ts

package/dist/index.cjs

@@ -16,6 +16,9 @@ var StructuralGuardError = class extends Error {
 /**
 * Thrown for any non-2xx JSON:API response. Carries the parsed error document plus
 * expressive status matchers and pointer-grouping helpers.
+*
+* `C` types each error object's `code` (see {@link JsonApiErrorObject}). It is a compile-time
+* hint only: the runtime never checks a code against it.
 */
 var JsonApiError = class extends Error {
 	status;
@@ -80,6 +83,60 @@ var JsonApiError = class extends Error {
 		return out;
 	}
 };
+/**
+* True when `err` is a {@link JsonApiError} and any of its error objects carries `code`. Takes
+* any string, so it also matches codes the server never documented. A generated client exports a
+* `hasErrorCode` bound to its server's `ErrorCode` union, which rejects a misspelt code at
+* compile time; reach for this one only to match an undocumented code.
+*/
+function hasErrorCode(err, code) {
+	return err instanceof JsonApiError && err.errors.some((e) => e.code === code);
+}
+//#endregion
+//#region src/pagination.ts
+/** The wire key for each role when the server keeps the default names. */
+const CANONICAL_PAGE_KEYS = {
+	page: {
+		number: "number",
+		size: "size"
+	},
+	offset: {
+		offset: "offset",
+		limit: "limit"
+	},
+	cursor: {
+		after: "after",
+		before: "before",
+		size: "size"
+	},
+	fixed: { number: "number" },
+	none: {}
+};
+/**
+* Resolve the strategy that answers a read from the endpoint's paginator and the `page` the
+* request sends. A menu answers with the arm named by `page.kind`, else its `default`.
+*/
+function resolvePaginator(paginator, page) {
+	if (paginator === void 0) return {
+		kind: "none",
+		keys: {}
+	};
+	if (typeof paginator === "string") return {
+		kind: paginator,
+		keys: CANONICAL_PAGE_KEYS[paginator]
+	};
+	if (paginator.strategy !== "multi") return {
+		kind: paginator.strategy,
+		keys: paginator.keys
+	};
+	const picked = page?.["kind"];
+	const arm = typeof picked === "string" && Object.hasOwn(paginator.arms, picked) ? picked : void 0;
+	const resolved = resolvePaginator(paginator.arms[arm ?? paginator.default]);
+	return arm === void 0 ? resolved : {
+		...resolved,
+		arm
+	};
+}
 //#endregion
 //#region src/validate.ts
 /** Whether a `validate` option is the schema-driven config (vs a bare validator function). */
@@ -192,9 +249,10 @@ const defineGetter = (target, key, get) => {
 * full resource) — a structural guess can't tell them apart for an attribute-less,
 * relation-less resource, so the caller passes the surface it issued.
 *
-* `paginatorOverride` sets the top-level array's `$page.kind` for a related/relationship read,
-* where the paginator is the RELATION's (which may diverge from the related type's collection —
-* D6a) and an empty page carries no member to sniff a type from. `primaryType` is preferred for a
+* `paginatorOverride` sets the top-level array's `$page` for a related/relationship read, where the
+* paginator is the RELATION's (which may diverge from the related type's collection — D6a), for a
+* menu read that picked an arm, and where an empty page carries no member to sniff a type from. A
+* bare kind is read with its canonical wire keys. `primaryType` is preferred for a
 * top-level collection read (statically-known); both override the sniff-from-`data[0]` fallback.
 */
 function materialise(doc, ctx, linkage = false, primaryType, paginatorOverride) {
@@ -247,7 +305,7 @@ function buildNode(raw, env, index, nodes, ctx) {
 	for (const [name, rel] of Object.entries(rels)) {
 		if (!("data" in rel)) continue;
 		const relDesc = resType?.relations[name];
-		node[name] = hydrateRelation(rel, relDesc?.cardinality, relatedPaginatorKind(relDesc, ctx), env, index, nodes, ctx);
+		node[name] = hydrateRelation(rel, relDesc?.cardinality, resolvePaginator(relatedPaginator(relDesc, ctx)), env, index, nodes, ctx);
 	}
 	attachResourceEnvelope(node, raw, env, rels);
 	return node;
@@ -257,13 +315,13 @@ function buildNode(raw, env, index, nodes, ctx) {
 * linked-but-not-included member stays an identifier, an empty to-one is `null`, and a
 * to-many is always an augmented array (of views and/or identifiers).
 *
-* `relatedKind` is the related type's paginator kind (from the descriptor), threaded so a
-* to-many array reports the same `$page.kind` it would on its dedicated endpoint.
+* `related` is the relation's paginator (from the descriptor), threaded so a to-many array
+* reports the same `$page` it would on its dedicated endpoint without a `page` argument.
 */
-function hydrateRelation(rel, cardinality, relatedKind, env, index, nodes, ctx) {
+function hydrateRelation(rel, cardinality, related, env, index, nodes, ctx) {
 	const data = rel.data;
-	if (Array.isArray(data)) return augmentRelationArray(data.map((member) => resolveMember(member, env, index, nodes, ctx)), rel, relatedKind, ctx);
-	if (data === void 0 && cardinality === "many") return augmentRelationArray([], rel, relatedKind, ctx);
+	if (Array.isArray(data)) return augmentRelationArray(data.map((member) => resolveMember(member, env, index, nodes, ctx)), rel, related, ctx);
+	if (data === void 0 && cardinality === "many") return augmentRelationArray([], rel, related, ctx);
 	if (data === null || data === void 0) return data === null ? null : void 0;
 	if (isObject$2(data)) return resolveMember(data, env, index, nodes, ctx, {
 		links: rel.links,
@@ -370,33 +428,35 @@ function augmentArray(members, doc, ctx, linkage, primaryType, paginatorOverride
 	const links = doc.links;
 	defineGetter(arr, "$links", () => links);
 	defineGetter(arr, "$meta", () => doc.meta);
-	attachPage(arr, paginatorOverride ?? paginatorKind(doc, ctx, primaryType), pageMeta(doc.meta), links, ctx, linkage);
+	attachPage(arr, paginatorOverride === void 0 ? resolvePaginator(primaryPaginator(doc, ctx, primaryType)) : typeof paginatorOverride === "string" ? resolvePaginator(paginatorOverride) : paginatorOverride, pageMeta(doc.meta), links, ctx, linkage);
 	return arr;
 }
 /**
-* A to-many relationship array: `$page`/links/meta come from the relationship object. `kind`
-* is the related type's paginator (so an in-document compound-include to-many reports the same
+* A to-many relationship array: `$page`/links/meta come from the relationship object.
+* `paginator` is the relation's (so an in-document compound-include to-many reports the same
 * discriminant it would when fetched at its own relationship/related endpoint — "one model,
 * three surfaces").
 */
-function augmentRelationArray(members, rel, kind, ctx) {
+function augmentRelationArray(members, rel, paginator, ctx) {
 	const arr = [...members];
 	const links = rel.links;
 	defineGetter(arr, "$links", () => links);
 	defineGetter(arr, "$meta", () => rel.meta);
-	attachPage(arr, kind, pageMeta(rel.meta), links, ctx, false);
+	attachPage(arr, paginator, pageMeta(rel.meta), links, ctx, false);
 	return arr;
 }
 /** Attach `$page` + `$next()`/`$prev()` driven by link presence (count-free-safe). */
-function attachPage(arr, kind, meta, links, ctx, linkage) {
+function attachPage(arr, paginator, meta, links, ctx, linkage) {
 	const page = {
-		kind,
+		kind: paginator.kind,
+		keys: paginator.keys,
 		links: pageLinks(links)
 	};
+	if (paginator.arm !== void 0) page.arm = paginator.arm;
 	if (meta !== void 0) page.meta = meta;
 	defineGetter(arr, "$page", () => page);
-	define(arr, "$next", (options) => navigateLink(page.links.next, ctx, linkage, kind, options?.signal));
-	define(arr, "$prev", (options) => navigateLink(page.links.prev, ctx, linkage, kind, options?.signal));
+	define(arr, "$next", (options) => navigateLink(page.links.next, ctx, linkage, paginator, options?.signal));
+	define(arr, "$prev", (options) => navigateLink(page.links.prev, ctx, linkage, paginator, options?.signal));
 }
 const navigateLink = (link, ctx, linkage, paginator, signal) => {
 	if (link === void 0) return Promise.resolve(void 0);
@@ -423,18 +483,18 @@ const linkHref = (link) => {
 };
 const pageMeta = (meta) => isObject$2(meta?.["page"]) ? meta["page"] : void 0;
 /**
-* The document's paginator kind (from the primary type's descriptor; default `none`). Prefers the
-* statically-known `primaryType` (passed by the descriptor binding at the call site) so an EMPTY
-* page still reports the collection's real kind; falls back to sniffing the first member's type
-* (for a re-materialised `$next()` page or a related read, where the primary type isn't threaded).
+* The document's paginator (from the primary type's descriptor). Prefers the statically-known
+* `primaryType` (passed by the descriptor binding at the call site) so an EMPTY page still reports
+* the collection's real kind; falls back to sniffing the first member's type (for a re-materialised
+* `$next()` page or a related read, where the primary type isn't threaded).
 */
-function paginatorKind(doc, ctx, primaryType) {
+function primaryPaginator(doc, ctx, primaryType) {
 	const first = Array.isArray(doc.data) ? doc.data[0] : doc.data;
 	const type = primaryType ?? (isObject$2(first) && typeof first["type"] === "string" ? first["type"] : void 0);
-	return type !== void 0 ? ctx.descriptor[type]?.paginator ?? "none" : "none";
+	return type !== void 0 ? ctx.descriptor[type]?.paginator : void 0;
 }
 /**
-* A to-many relation's paginator kind. The relation's OWN related/relationship endpoint may
+* A to-many relation's paginator. The relation's OWN related/relationship endpoint may
 * paginate differently than the related type's top-level collection (D6a), so prefer the
 * per-relation `paginator` (carried in the descriptor only when it diverges); otherwise fall back
 * to the related type's own paginator (the relationship and related endpoints both paginate that
@@ -442,11 +502,14 @@ function paginatorKind(doc, ctx, primaryType) {
 * resolves off its first declared related type (its members span types, matching the relationship
 * endpoint's first-member resolution).
 */
-function relatedPaginatorKind(relation, ctx) {
+function relatedPaginator(relation, ctx) {
 	if (relation?.paginator !== void 0) return relation.paginator;
 	const relatedType = relation?.types[0];
-	if (relatedType === void 0) return "none";
-	return ctx.descriptor[relatedType]?.paginator ?? "none";
+	return relatedType === void 0 ? void 0 : ctx.descriptor[relatedType]?.paginator;
+}
+/** The kind a relation's related read answers with when it sends no `page`. See {@link relatedPaginator}. */
+function relatedPaginatorKind(relation, ctx) {
+	return resolvePaginator(relatedPaginator(relation, ctx)).kind;
 }
 //#endregion
 //#region src/types.ts
@@ -476,6 +539,14 @@ const ATOMIC_MEDIA_TYPE = mediaType({ ext: [ATOMIC_EXT] });
 //#endregion
 //#region src/request.ts
 const isAbsolute = (path) => /^https?:\/\//i.test(path);
+const RELATIVE_ORIGIN = "http://relative.invalid";
+/** Resolve a server link against `baseUrl` per RFC 3986. An absolute link is kept verbatim. */
+function resolveLink(link, baseUrl) {
+	if (isAbsolute(link)) return link;
+	if (isAbsolute(baseUrl)) return new URL(link, baseUrl).href;
+	const resolved = new URL(link, new URL(baseUrl, RELATIVE_ORIGIN));
+	return resolved.origin === RELATIVE_ORIGIN ? resolved.pathname + resolved.search + resolved.hash : resolved.href;
+}
 const append = (parts, key, value) => {
 	if (value === void 0 || value === null || value === "") return;
 	parts.push(`${key}=${encodeURIComponent(String(value))}`);
@@ -512,14 +583,14 @@ function serializeQuery(query) {
 	return parts.join("&");
 }
 /**
-* Execute a request: build the URL (verbatim when already absolute — for page links —
-* else `baseUrl + path`), apply content negotiation and any async per-request headers,
+* Execute a request: build the URL (a server link resolved against `baseUrl`, an absolute path
+* verbatim, else `baseUrl + path`), apply content negotiation and any async per-request headers,
 * then drive the transport. A 2xx with a body parses to a {@link Document}; an empty /
 * 204 body resolves to `undefined`. A non-2xx throws a {@link JsonApiError} carrying the
 * parsed error objects (tolerating a non-JSON error body with an empty list).
 */
 async function execute(ctx, req) {
-	let url = isAbsolute(req.path) ? req.path : ctx.baseUrl + req.path;
+	let url = req.link ? resolveLink(req.path, ctx.baseUrl) : isAbsolute(req.path) ? req.path : ctx.baseUrl + req.path;
 	if (req.query) {
 		const qs = serializeQuery(req.query);
 		if (qs) url += (url.includes("?") ? "&" : "?") + qs;
@@ -949,6 +1020,18 @@ const fetchTransport = async (req) => {
 /** Substitute `{key}` placeholders in a path template (`/albums/{id}/{rel}` -> `/albums/1/tracks`). */
 const fill = (template, vars) => template.replace(/\{(\w+)\}/g, (_, key) => vars[key] ?? `{${key}}`);
 /**
+* Fill a type's path template, putting a relation's URI segment (its `uriField`, else its name)
+* in place of `{rel}`. `vars.rel` stays the relation's name everywhere else.
+*/
+function fillPath(ctx, type, template, vars) {
+	const rel = vars["rel"];
+	const uriField = rel === void 0 ? void 0 : ctx.descriptor[type]?.relations[rel]?.uriField;
+	return fill(template, uriField === void 0 ? vars : {
+		...vars,
+		rel: uriField
+	});
+}
+/**
 * Run an operation: resolve the path template from the type's descriptor, fill its
 * placeholders, execute, and materialise the resulting document. A no-body / 204 response
 * materialises to `undefined`; an operation the type does not declare (no path template) throws
@@ -961,7 +1044,7 @@ async function run(ctx, type, operation, vars, query, linkage = false, relationF
 	if (template === void 0) throw new Error(`No "${operation}" path declared for type "${type}"`);
 	const req = {
 		method: "GET",
-		path: fill(template, vars)
+		path: fillPath(ctx, type, template, vars)
 	};
 	if (query !== void 0) {
 		const { signal, ...params } = query;
@@ -970,8 +1053,10 @@ async function run(ctx, type, operation, vars, query, linkage = false, relationF
 		negotiateProfiles(ctx, type, params, req, relationForCount);
 	}
 	const doc = await execute(ctx.request, req);
+	const relation = (operation === "fetchRelated" || operation === "fetchRelationship") && vars["rel"] !== void 0 ? ctx.descriptor[type]?.relations[vars["rel"]] : void 0;
+	const paginator = operation === "fetchMany" ? ctx.descriptor[type]?.paginator : relation !== void 0 ? relatedPaginator(relation, ctx.materialise) : void 0;
 	const primaryType = operation === "fetchMany" ? type : void 0;
-	const paginatorOverride = (operation === "fetchRelated" || operation === "fetchRelationship") && vars["rel"] !== void 0 ? relatedPaginatorKind(ctx.descriptor[type]?.relations[vars["rel"]], ctx.materialise) : void 0;
+	const paginatorOverride = paginator === void 0 ? void 0 : resolvePaginator(paginator, query?.page);
 	return doc === void 0 ? void 0 : materialise(doc, ctx.materialise, linkage, primaryType, paginatorOverride);
 }
 /**
@@ -1009,7 +1094,7 @@ async function runWrite(ctx, spec) {
 	if (template === void 0) throw new Error(`No "${spec.operation}" path declared for type "${spec.type}"`);
 	const req = {
 		method: spec.method,
-		path: fill(template, spec.vars),
+		path: fillPath(ctx, spec.type, template, spec.vars),
 		body: spec.body
 	};
 	if (spec.query !== void 0) req.query = spec.query;
@@ -1108,8 +1193,9 @@ function relationshipAccessor(ctx, type, id, rel) {
 		return mutations === void 0 ? true : mutations[verb] === true;
 	};
 	const accessor = {};
-	if (relation?.relationship !== false) accessor["get"] = (query) => run(ctx, type, "fetchRelationship", vars, query, true, rel);
-	if (relation?.related !== false) accessor["related"] = (query) => run(ctx, type, "fetchRelated", vars, query, false, rel);
+	const readable = relation?.writeOnly !== true;
+	if (readable && relation?.relationship !== false) accessor["get"] = (query) => run(ctx, type, "fetchRelationship", vars, query, true, rel);
+	if (readable && relation?.related !== false) accessor["related"] = (query) => run(ctx, type, "fetchRelated", vars, query, false, rel);
 	if (cardinality === "many") {
 		if (advertises("add")) accessor["add"] = (refs) => mutate("POST", refs);
 		if (advertises("remove")) accessor["remove"] = (refs) => mutate("DELETE", refs);
@@ -1188,7 +1274,7 @@ function typeAccessor(ctx, type) {
 * not per-type codegen: `client.<type>` yields a {@link TypeAccessor}, `.id(id)` a handle,
 * and a handle's relation accessors drive the relationship/related endpoints. Navigation
 * (`$next()`/`$prev()`, related links) is wired through `materialise`'s `navigate` seam,
-* which executes the (absolute) link and re-materialises.
+* which resolves the server's link against `baseUrl`, executes it and re-materialises.
 */
 function createClient(descriptor, options) {
 	const request = {
@@ -1206,6 +1292,7 @@ function createClient(descriptor, options) {
 				const doc = await execute(request, {
 					method: "GET",
 					path: url,
+					link: true,
 					...signal !== void 0 ? { signal } : {}
 				});
 				return doc === void 0 ? void 0 : materialise(doc, ctx.materialise, linkage, void 0, paginator);
@@ -1238,6 +1325,7 @@ function createClient(descriptor, options) {
 //#endregion
 exports.ATOMIC_EXT = ATOMIC_EXT;
 exports.ATOMIC_MEDIA_TYPE = ATOMIC_MEDIA_TYPE;
+exports.CANONICAL_PAGE_KEYS = CANONICAL_PAGE_KEYS;
 exports.HANDLE_RESERVED = HANDLE_RESERVED;
 exports.JSON_API_MEDIA_TYPE = JSON_API_MEDIA_TYPE;
 exports.JsonApiError = JsonApiError;
@@ -1246,11 +1334,14 @@ exports.assertJsonApiDocument = assertJsonApiDocument;
 exports.createClient = createClient;
 exports.execute = execute;
 exports.fetchTransport = fetchTransport;
+exports.hasErrorCode = hasErrorCode;
 exports.materialise = materialise;
 exports.mediaType = mediaType;
+exports.relatedPaginator = relatedPaginator;
 exports.relatedPaginatorKind = relatedPaginatorKind;
 exports.remapPointer = remapPointer;
 exports.remapRelationshipPointer = remapRelationshipPointer;
+exports.resolvePaginator = resolvePaginator;
 exports.resolveValidator = resolveValidator;
 exports.runAtomic = runAtomic;
 exports.serializeQuery = serializeQuery;

package/dist/index.d.cts

@@ -1,11 +1,17 @@
-import { $ as SortQuery, A as DefaultActionTypes, At as Page, B as IncludePath, Bt as ApiDescriptor, C as fetchTransport, Ct as mediaType, D as Collection, Dt as EdgeEnvelope, E as Client, Et as Edge, F as FieldsMap, Ft as relatedPaginatorKind, G as ReadResult, Gt as PaginatorKind, H as LinkageRef, Ht as Cardinality, I as FilterKey, It as ActionDescriptor, J as RelationshipAccessor, Jt as ResourceDescriptor, K as RelationName, Kt as RelationDescriptor, L as FilterQuery, Lt as ActionInput, M as DefaultWriteAttributes, Mt as ResourceEnvelope, N as EdgeMembers, Nt as ResourceLinks, O as CountToken, Ot as MaterialiseContext, P as FieldSelectionMap, Pt as materialise, Q as SingleReadQuery, R as HydratedMember, Rt as ActionOutput, S as TransportResponse, St as ResourceIdentifier, T as AtomicResultOf, Tt as DocumentEnvelope, U as MemberName, Ut as ClientIdPolicy, V as IncludedRelations, Vt as AtomicDescriptor, W as PivotInput, Wt as CountableDescriptor, X as ResourceHandle, Y as ResourceAccessors, Z as ResourceObjectView, _ as HANDLE_RESERVED, _t as ATOMIC_EXT, a as Validator, at as WriteOptions, b as JsonApiTransport, bt as LocalIdentifier, c as resolveValidator, ct as AtomicDeleteHandle, d as JsonApiContext, dt as AtomicRef, et as SortToken, f as JsonApiRequest, ft as AtomicResult, g as ClientOptions, gt as runAtomic, h as serializeQuery, ht as AtomicUpdateInput, i as ValidationOption, it as UpdateInput, j as DefaultAttributes, jt as RelationView, k as CreateInput, kt as NavigateOptions, l as validateDocument, lt as AtomicHandle, m as execute, mt as AtomicUpdateHandle, n as SchemaMap, nt as TypeName, o as WireResource, ot as AtomicCreateHandle, p as ReadQuery, pt as AtomicResults, q as RelationReadQuery, qt as RelationMutations, r as ValidationConfig, rt as TypedReadQuery, s as assertJsonApiDocument, st as AtomicCreateInput, t as ResolvedValidator, tt as TypeAccessor, u as Document, ut as AtomicRecorder, v as HeadersInit, vt as ATOMIC_MEDIA_TYPE, w as ActionsAccessor, wt as ArrayEnvelope, x as TransportRequest, xt as MediaTypeParams, y as createClient, yt as JSON_API_MEDIA_TYPE, z as IdentifierMember, zt as ActionScope } from "./validate-CfrCMZkA.cjs";
+import { $ as RelationshipAccessor, $t as ActionDescriptor, A as DefaultActionTypes, At as DocumentEnvelope, B as IdentifierMember, Bt as relatedPaginatorKind, C as fetchTransport, Ct as ATOMIC_MEDIA_TYPE, D as Collection, Dt as ResourceIdentifier, E as Client, Et as MediaTypeParams, F as FieldSelectionMap, Ft as RelationView, G as MemberName, Gt as PageLinks, H as IncludedRelations, Ht as ExactPageParams, I as FieldsMap, It as ResourceEnvelope, J as ReadableRelationName, Jt as PageParams, K as PivotInput, Kt as PageMeta, L as FilterKey, Lt as ResourceLinks, M as DefaultWriteAttributes, Mt as EdgeEnvelope, N as EdgeMembers, Nt as MaterialiseContext, O as CountToken, Ot as mediaType, P as ErrorCodeOf, Pt as NavigateOptions, Q as RelationReadQuery, Qt as resolvePaginator, R as FilterQuery, Rt as materialise, S as TransportResponse, St as ATOMIC_EXT, T as AtomicResultOf, Tt as LocalIdentifier, U as LinkageRef, Ut as Page, V as IncludePath, Vt as CANONICAL_PAGE_KEYS, W as ListPageParams, Wt as PageKeys, X as RelationPageParams, Xt as ResolvedPaginator, Y as RelationName, Yt as PageParamsOf, Z as RelationPaginator, Zt as TypedPage, _ as HANDLE_RESERVED, _n as StrategyDescriptor, _t as AtomicResult, a as Validator, an as Cardinality, at as SortToken, b as JsonApiTransport, bt as AtomicUpdateInput, c as resolveValidator, cn as MenuDescriptor, ct as TypedReadQuery, d as JsonApiContext, dn as PaginatorRole, dt as AtomicCreateHandle, en as ActionInput, et as ResourceAccessors, f as JsonApiRequest, fn as PaginatorStrategy, ft as AtomicCreateInput, g as ClientOptions, gn as ResourceDescriptor, gt as AtomicRef, h as serializeQuery, hn as RelationMutations, ht as AtomicRecorder, i as ValidationOption, in as AtomicDescriptor, it as SortQuery, j as DefaultAttributes, jt as Edge, k as CreateInput, kt as ArrayEnvelope, l as validateDocument, ln as PaginatorDescriptor, lt as UpdateInput, m as execute, mn as RelationDescriptor, mt as AtomicHandle, n as SchemaMap, nn as ActionScope, nt as ResourceObjectView, o as WireResource, on as ClientIdPolicy, ot as TypeAccessor, p as ReadQuery, pn as PivotDescriptor, pt as AtomicDeleteHandle, q as ReadResult, qt as PageOf, r as ValidationConfig, rn as ApiDescriptor, rt as SingleReadQuery, s as assertJsonApiDocument, sn as CountableDescriptor, st as TypeName, t as ResolvedValidator, tn as ActionOutput, tt as ResourceHandle, u as Document, un as PaginatorKind, ut as WriteOptions, v as HeadersInit, vt as AtomicResults, w as ActionsAccessor, wt as JSON_API_MEDIA_TYPE, x as TransportRequest, xt as runAtomic, y as createClient, yt as AtomicUpdateHandle, z as HydratedMember, zt as relatedPaginator } from "./validate-CJPivkqT.cjs";
 
 //#region src/errors.d.ts
-/** A single JSON:API error object (spec: error objects). */
-interface JsonApiErrorObject {
+/**
+ * A single JSON:API error object (spec: error objects).
+ *
+ * `C` is the server's documented error-code union (a generated client's `ErrorCode`). `code` is
+ * typed `C | (string & {})`: editors suggest the documented codes, yet any other string still
+ * fits, because the catalogue is open and a server may send a code it never documented.
+ */
+interface JsonApiErrorObject<C extends string = string> {
   id?: string;
   status?: string;
-  code?: string;
+  code?: C | (string & {});
   title?: string;
   detail?: string;
   source?: {
@@ -40,11 +46,14 @@ declare class StructuralGuardError extends Error {
 /**
  * Thrown for any non-2xx JSON:API response. Carries the parsed error document plus
  * expressive status matchers and pointer-grouping helpers.
+ *
+ * `C` types each error object's `code` (see {@link JsonApiErrorObject}). It is a compile-time
+ * hint only: the runtime never checks a code against it.
  */
-declare class JsonApiError extends Error {
+declare class JsonApiError<C extends string = string> extends Error {
   readonly status: number;
-  readonly errors: JsonApiErrorObject[];
-  constructor(status: number, errors: JsonApiErrorObject[], message?: string);
+  readonly errors: JsonApiErrorObject<C>[];
+  constructor(status: number, errors: JsonApiErrorObject<C>[], message?: string);
   hasStatus(status: number): boolean;
   is4xx(): boolean;
   is5xx(): boolean;
@@ -64,8 +73,21 @@ declare class JsonApiError extends Error {
    * query parameter). The payoff for form/validation UX — 422 `source.pointer`s are
    * remapped to the flat shape the caller actually supplied.
    */
-  byPath(): Record<string, JsonApiErrorObject[]>;
+  byPath(): Record<string, JsonApiErrorObject<C>[]>;
 }
+/**
+ * True when `err` is a {@link JsonApiError} and any of its error objects carries `code`. Takes
+ * any string, so it also matches codes the server never documented. A generated client exports a
+ * `hasErrorCode` bound to its server's `ErrorCode` union, which rejects a misspelt code at
+ * compile time; reach for this one only to match an undocumented code.
+ */
+declare function hasErrorCode(err: unknown, code: string): err is JsonApiError;
+/**
+ * {@link hasErrorCode} restricted to one server's documented codes. A generated client binds it:
+ * `export const hasErrorCode = hasErrorCodeRuntime as ErrorCodeGuard<ErrorCode>`. The cast is
+ * needed because `JsonApiError<string>` doesn't assign to `JsonApiError<ErrorCode>`.
+ */
+type ErrorCodeGuard<C extends string> = (err: unknown, code: C) => err is JsonApiError<C>;
 //#endregion
 //#region src/serialize-write.d.ts
 /**
@@ -194,5 +216,5 @@ declare function withRemappedRelationshipPaths(error: JsonApiError, rel: string,
  */
 declare function withRemappedAtomicPaths(error: JsonApiError, descriptor: ApiDescriptor, typeForOp: (opIndex: number) => string | undefined): JsonApiError;
 //#endregion
-export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, NavigateOptions, Page, PaginatorKind, PivotInput, ReadQuery, ReadResult, RelationDescriptor, RelationMutations, RelationName, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, materialise, mediaType, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, CANONICAL_PAGE_KEYS, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, ErrorCodeGuard, ErrorCodeOf, ExactPageParams, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, ListPageParams, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, MenuDescriptor, NavigateOptions, Page, PageKeys, PageLinks, PageMeta, PageOf, PageParams, PageParamsOf, PaginatorDescriptor, PaginatorKind, PaginatorRole, PaginatorStrategy, PivotDescriptor, PivotInput, ReadQuery, ReadResult, ReadableRelationName, RelationDescriptor, RelationMutations, RelationName, RelationPageParams, RelationPaginator, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedPaginator, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StrategyDescriptor, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedPage, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts","../src/serialize-write.ts"],"mappings":";;;;UACiB,kBAAA;EACf,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,MAAA;IAAW,OAAA;IAAkB,SAAA;IAAoB,MAAA;EAAA;EACjD,IAAA,GAAO,MAAM;EADF;;;;;EAOX,IAAA;EAMA;;AAAO;AAUT;;EAVE,OAAA;AAAA;;;;;AAW2B;AAU7B;;cAXa,oBAAA,SAA6B,KAAK;cACjC,OAAA;AAAA;;;;;cAUD,YAAA,SAAqB,KAAA;EAAA,SACvB,MAAA;EAAA,SACA,MAAA,EAAQ,kBAAA;cAEL,MAAA,UAAgB,MAAA,EAAQ,kBAAA,IAAsB,OAAA;EAO1D,SAAA,CAAU,MAAA;EAIV,KAAA;EAIA,KAAA;EAIA,YAAA;EAIA,cAAA;EAIA,WAAA;EAIA,UAAA;EAIA,eAAA;EAIA,UAAA;EAIA,sBAAA;EAIA,eAAA;EAxBA;EA6BA,iBAAA;EAIA,aAAA;EArBA;;;;;EA8BA,MAAA,IAAU,MAAA,SAAe,kBAAA;AAAA;;;;;;;;UClFjB,eAAA;EACR,IAAA;EACA,EAAA;EACA,GAAA;EACA,IAAA;IAAS,KAAA,EAAO,MAAA;EAAA,IAA4B,MAAM;AAAA;;UAInC,oBAAA;EACf,IAAA,EAAM,eAAA,GAAkB,eAAe;AAAA;ADNZ;AAAA,UCUZ,aAAA;EACf,IAAA;IACE,IAAA;IACA,EAAA;IACA,UAAA,GAAa,MAAA;IACb,aAAA,GAAgB,MAAA,SAAe,oBAAA;EAAA;AAAA;;UAKlB,iBAAA;EDViB;;;;;ECgBhC,EAAE;AAAA;;;;;;;;;;;;;;;iBAiBY,UAAA,CACd,UAAA,EAAY,aAAA,EACZ,IAAA,UACA,KAAA,EAAO,MAAA,mBACP,IAAA,GAAO,iBAAA,GACN,aAAA;;;;;;AD+B0C;;;;AClGmB;;;iBAmHhD,sBAAA,CACd,IAAA,WACA,WAAA,mBACC,oBAAoB;;;;;;;;;AAlG6B;AAIpD;;;;;;;;AACyC;iBAwLzB,YAAA,CAAa,UAAA,EAAY,aAAa,EAAE,IAAA,UAAc,OAAA;;;;;;;;;;;;;;;;;AA/Kf;iBA+PvC,wBAAA,CAAyB,GAAA,UAAa,QAAA,WAAmB,OAAA;;;;AApPrE;AAiBJ;;iBAqPgB,iBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,IAAA,WACC,YAAA;;;;;;;;iBAWa,6BAAA,CACd,KAAA,EAAO,YAAA,EACP,GAAA,UACA,QAAA,YACC,YAAY;;;;;;;;AAnQC;AAgDhB;iBAgOgB,uBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,SAAA,GAAY,OAAA,kCACX,YAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts","../src/serialize-write.ts"],"mappings":";;;;;;AAOA;;;;UAAiB,kBAAA;EACf,EAAA;EACA,MAAA;EACA,IAAA,GAAO,CAAA;EACP,KAAA;EACA,MAAA;EACA,MAAA;IAAW,OAAA;IAAkB,SAAA;IAAoB,MAAA;EAAA;EACjD,IAAA,GAAO,MAAM;EAAN;;;;AAYA;EANP,IAAA;EAgBgC;;;;;EAVhC,OAAA;AAAA;AAW2B;AAa7B;;;;;;AAb6B,cADhB,oBAAA,SAA6B,KAAK;cACjC,OAAA;AAAA;;;;;;;;cAaD,YAAA,oCAAgD,KAAA;EAAA,SAClD,MAAA;EAAA,SACA,MAAA,EAAQ,kBAAA,CAAmB,CAAA;cAExB,MAAA,UAAgB,MAAA,EAAQ,kBAAA,CAAmB,CAAA,KAAM,OAAA;EAO7D,SAAA,CAAU,MAAA;EAIV,KAAA;EAIA,KAAA;EAIA,YAAA;EAIA,cAAA;EAIA,WAAA;EAIA,UAAA;EAIA,eAAA;EAIA,UAAA;EAIA,sBAAA;EAIA,eAAA;EApBA;EAyBA,iBAAA;EAIA,aAAA;EAjBA;;;;;EA0BA,MAAA,IAAU,MAAA,SAAe,kBAAA,CAAmB,CAAA;AAAA;;;;AAAC;AAgB/C;;iBAAgB,YAAA,CAAa,GAAA,WAAc,IAAA,WAAe,GAAA,IAAO,YAAY;;;;;;KASjE,cAAA,sBAAoC,GAAA,WAAc,IAAA,EAAM,CAAA,KAAM,GAAA,IAAO,YAAA,CAAa,CAAA;;;;;;;;UCpHpF,eAAA;EACR,IAAA;EACA,EAAA;EACA,GAAA;EACA,IAAA;IAAS,KAAA,EAAO,MAAA;EAAA,IAA4B,MAAM;AAAA;;UAInC,oBAAA;EACf,IAAA,EAAM,eAAA,GAAkB,eAAe;AAAA;;UAIxB,aAAA;EACf,IAAA;IACE,IAAA;IACA,EAAA;IACA,UAAA,GAAa,MAAA;IACb,aAAA,GAAgB,MAAA,SAAe,oBAAA;EAAA;AAAA;;UAKlB,iBAAA;EDoEU;;;;;EC9DzB,EAAE;AAAA;;;;;;;;;;;;;;;iBAiBY,UAAA,CACd,UAAA,EAAY,aAAA,EACZ,IAAA,UACA,KAAA,EAAO,MAAA,mBACP,IAAA,GAAO,iBAAA,GACN,aAAA;;;;;;;;;;;;;iBAgDa,sBAAA,CACd,IAAA,WACA,WAAA,mBACC,oBAAoB;;ADXwB;AAgB/C;;;;;;;;;AAA6E;AAS7E;;;;;;iBC6EgB,YAAA,CAAa,UAAA,EAAY,aAAa,EAAE,IAAA,UAAc,OAAA;;;;;;;;;;AD7EyB;;;;ACpI/B;;;;iBAiShD,wBAAA,CAAyB,GAAA,UAAa,QAAA,WAAmB,OAAA;;;;;;;iBAkBzD,iBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,IAAA,WACC,YAAA;AAnSiD;AAIpD;;;;;;AAJoD,iBA8SpC,6BAAA,CACd,KAAA,EAAO,YAAA,EACP,GAAA,UACA,QAAA,YACC,YAAY;;AA7S0B;AAIzC;;;;;;;iBAsTgB,uBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,SAAA,GAAY,OAAA,kCACX,YAAA"}

package/dist/index.d.mts

@@ -1,11 +1,17 @@
-import { $ as SortQuery, A as DefaultActionTypes, At as Page, B as IncludePath, Bt as ApiDescriptor, C as fetchTransport, Ct as mediaType, D as Collection, Dt as EdgeEnvelope, E as Client, Et as Edge, F as FieldsMap, Ft as relatedPaginatorKind, G as ReadResult, Gt as PaginatorKind, H as LinkageRef, Ht as Cardinality, I as FilterKey, It as ActionDescriptor, J as RelationshipAccessor, Jt as ResourceDescriptor, K as RelationName, Kt as RelationDescriptor, L as FilterQuery, Lt as ActionInput, M as DefaultWriteAttributes, Mt as ResourceEnvelope, N as EdgeMembers, Nt as ResourceLinks, O as CountToken, Ot as MaterialiseContext, P as FieldSelectionMap, Pt as materialise, Q as SingleReadQuery, R as HydratedMember, Rt as ActionOutput, S as TransportResponse, St as ResourceIdentifier, T as AtomicResultOf, Tt as DocumentEnvelope, U as MemberName, Ut as ClientIdPolicy, V as IncludedRelations, Vt as AtomicDescriptor, W as PivotInput, Wt as CountableDescriptor, X as ResourceHandle, Y as ResourceAccessors, Z as ResourceObjectView, _ as HANDLE_RESERVED, _t as ATOMIC_EXT, a as Validator, at as WriteOptions, b as JsonApiTransport, bt as LocalIdentifier, c as resolveValidator, ct as AtomicDeleteHandle, d as JsonApiContext, dt as AtomicRef, et as SortToken, f as JsonApiRequest, ft as AtomicResult, g as ClientOptions, gt as runAtomic, h as serializeQuery, ht as AtomicUpdateInput, i as ValidationOption, it as UpdateInput, j as DefaultAttributes, jt as RelationView, k as CreateInput, kt as NavigateOptions, l as validateDocument, lt as AtomicHandle, m as execute, mt as AtomicUpdateHandle, n as SchemaMap, nt as TypeName, o as WireResource, ot as AtomicCreateHandle, p as ReadQuery, pt as AtomicResults, q as RelationReadQuery, qt as RelationMutations, r as ValidationConfig, rt as TypedReadQuery, s as assertJsonApiDocument, st as AtomicCreateInput, t as ResolvedValidator, tt as TypeAccessor, u as Document, ut as AtomicRecorder, v as HeadersInit, vt as ATOMIC_MEDIA_TYPE, w as ActionsAccessor, wt as ArrayEnvelope, x as TransportRequest, xt as MediaTypeParams, y as createClient, yt as JSON_API_MEDIA_TYPE, z as IdentifierMember, zt as ActionScope } from "./validate-CfrCMZkA.mjs";
+import { $ as RelationshipAccessor, $t as ActionDescriptor, A as DefaultActionTypes, At as DocumentEnvelope, B as IdentifierMember, Bt as relatedPaginatorKind, C as fetchTransport, Ct as ATOMIC_MEDIA_TYPE, D as Collection, Dt as ResourceIdentifier, E as Client, Et as MediaTypeParams, F as FieldSelectionMap, Ft as RelationView, G as MemberName, Gt as PageLinks, H as IncludedRelations, Ht as ExactPageParams, I as FieldsMap, It as ResourceEnvelope, J as ReadableRelationName, Jt as PageParams, K as PivotInput, Kt as PageMeta, L as FilterKey, Lt as ResourceLinks, M as DefaultWriteAttributes, Mt as EdgeEnvelope, N as EdgeMembers, Nt as MaterialiseContext, O as CountToken, Ot as mediaType, P as ErrorCodeOf, Pt as NavigateOptions, Q as RelationReadQuery, Qt as resolvePaginator, R as FilterQuery, Rt as materialise, S as TransportResponse, St as ATOMIC_EXT, T as AtomicResultOf, Tt as LocalIdentifier, U as LinkageRef, Ut as Page, V as IncludePath, Vt as CANONICAL_PAGE_KEYS, W as ListPageParams, Wt as PageKeys, X as RelationPageParams, Xt as ResolvedPaginator, Y as RelationName, Yt as PageParamsOf, Z as RelationPaginator, Zt as TypedPage, _ as HANDLE_RESERVED, _n as StrategyDescriptor, _t as AtomicResult, a as Validator, an as Cardinality, at as SortToken, b as JsonApiTransport, bt as AtomicUpdateInput, c as resolveValidator, cn as MenuDescriptor, ct as TypedReadQuery, d as JsonApiContext, dn as PaginatorRole, dt as AtomicCreateHandle, en as ActionInput, et as ResourceAccessors, f as JsonApiRequest, fn as PaginatorStrategy, ft as AtomicCreateInput, g as ClientOptions, gn as ResourceDescriptor, gt as AtomicRef, h as serializeQuery, hn as RelationMutations, ht as AtomicRecorder, i as ValidationOption, in as AtomicDescriptor, it as SortQuery, j as DefaultAttributes, jt as Edge, k as CreateInput, kt as ArrayEnvelope, l as validateDocument, ln as PaginatorDescriptor, lt as UpdateInput, m as execute, mn as RelationDescriptor, mt as AtomicHandle, n as SchemaMap, nn as ActionScope, nt as ResourceObjectView, o as WireResource, on as ClientIdPolicy, ot as TypeAccessor, p as ReadQuery, pn as PivotDescriptor, pt as AtomicDeleteHandle, q as ReadResult, qt as PageOf, r as ValidationConfig, rn as ApiDescriptor, rt as SingleReadQuery, s as assertJsonApiDocument, sn as CountableDescriptor, st as TypeName, t as ResolvedValidator, tn as ActionOutput, tt as ResourceHandle, u as Document, un as PaginatorKind, ut as WriteOptions, v as HeadersInit, vt as AtomicResults, w as ActionsAccessor, wt as JSON_API_MEDIA_TYPE, x as TransportRequest, xt as runAtomic, y as createClient, yt as AtomicUpdateHandle, z as HydratedMember, zt as relatedPaginator } from "./validate-CJPivkqT.mjs";
 
 //#region src/errors.d.ts
-/** A single JSON:API error object (spec: error objects). */
-interface JsonApiErrorObject {
+/**
+ * A single JSON:API error object (spec: error objects).
+ *
+ * `C` is the server's documented error-code union (a generated client's `ErrorCode`). `code` is
+ * typed `C | (string & {})`: editors suggest the documented codes, yet any other string still
+ * fits, because the catalogue is open and a server may send a code it never documented.
+ */
+interface JsonApiErrorObject<C extends string = string> {
   id?: string;
   status?: string;
-  code?: string;
+  code?: C | (string & {});
   title?: string;
   detail?: string;
   source?: {
@@ -40,11 +46,14 @@ declare class StructuralGuardError extends Error {
 /**
  * Thrown for any non-2xx JSON:API response. Carries the parsed error document plus
  * expressive status matchers and pointer-grouping helpers.
+ *
+ * `C` types each error object's `code` (see {@link JsonApiErrorObject}). It is a compile-time
+ * hint only: the runtime never checks a code against it.
  */
-declare class JsonApiError extends Error {
+declare class JsonApiError<C extends string = string> extends Error {
   readonly status: number;
-  readonly errors: JsonApiErrorObject[];
-  constructor(status: number, errors: JsonApiErrorObject[], message?: string);
+  readonly errors: JsonApiErrorObject<C>[];
+  constructor(status: number, errors: JsonApiErrorObject<C>[], message?: string);
   hasStatus(status: number): boolean;
   is4xx(): boolean;
   is5xx(): boolean;
@@ -64,8 +73,21 @@ declare class JsonApiError extends Error {
    * query parameter). The payoff for form/validation UX — 422 `source.pointer`s are
    * remapped to the flat shape the caller actually supplied.
    */
-  byPath(): Record<string, JsonApiErrorObject[]>;
+  byPath(): Record<string, JsonApiErrorObject<C>[]>;
 }
+/**
+ * True when `err` is a {@link JsonApiError} and any of its error objects carries `code`. Takes
+ * any string, so it also matches codes the server never documented. A generated client exports a
+ * `hasErrorCode` bound to its server's `ErrorCode` union, which rejects a misspelt code at
+ * compile time; reach for this one only to match an undocumented code.
+ */
+declare function hasErrorCode(err: unknown, code: string): err is JsonApiError;
+/**
+ * {@link hasErrorCode} restricted to one server's documented codes. A generated client binds it:
+ * `export const hasErrorCode = hasErrorCodeRuntime as ErrorCodeGuard<ErrorCode>`. The cast is
+ * needed because `JsonApiError<string>` doesn't assign to `JsonApiError<ErrorCode>`.
+ */
+type ErrorCodeGuard<C extends string> = (err: unknown, code: C) => err is JsonApiError<C>;
 //#endregion
 //#region src/serialize-write.d.ts
 /**
@@ -194,5 +216,5 @@ declare function withRemappedRelationshipPaths(error: JsonApiError, rel: string,
  */
 declare function withRemappedAtomicPaths(error: JsonApiError, descriptor: ApiDescriptor, typeForOp: (opIndex: number) => string | undefined): JsonApiError;
 //#endregion
-export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, NavigateOptions, Page, PaginatorKind, PivotInput, ReadQuery, ReadResult, RelationDescriptor, RelationMutations, RelationName, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, materialise, mediaType, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, ActionDescriptor, ActionInput, ActionOutput, ActionScope, ActionsAccessor, ApiDescriptor, ArrayEnvelope, AtomicCreateHandle, AtomicCreateInput, AtomicDeleteHandle, AtomicDescriptor, AtomicHandle, AtomicRecorder, AtomicRef, AtomicResult, AtomicResultOf, AtomicResults, AtomicUpdateHandle, AtomicUpdateInput, CANONICAL_PAGE_KEYS, Cardinality, Client, ClientIdPolicy, ClientOptions, Collection, CountToken, CountableDescriptor, CreateInput, DefaultActionTypes, DefaultAttributes, DefaultWriteAttributes, Document, DocumentEnvelope, Edge, EdgeEnvelope, EdgeMembers, ErrorCodeGuard, ErrorCodeOf, ExactPageParams, FieldSelectionMap, FieldsMap, FilterKey, FilterQuery, HANDLE_RESERVED, HeadersInit, HydratedMember, IdentifierMember, IncludePath, IncludedRelations, JSON_API_MEDIA_TYPE, JsonApiContext, JsonApiError, JsonApiErrorObject, JsonApiRequest, JsonApiTransport, LinkageRef, ListPageParams, LocalIdentifier, MaterialiseContext, MediaTypeParams, MemberName, MenuDescriptor, NavigateOptions, Page, PageKeys, PageLinks, PageMeta, PageOf, PageParams, PageParamsOf, PaginatorDescriptor, PaginatorKind, PaginatorRole, PaginatorStrategy, PivotDescriptor, PivotInput, ReadQuery, ReadResult, ReadableRelationName, RelationDescriptor, RelationMutations, RelationName, RelationPageParams, RelationPaginator, RelationReadQuery, RelationView, RelationshipAccessor, RelationshipDocument, ResolvedPaginator, ResolvedValidator, ResourceAccessors, ResourceDescriptor, ResourceEnvelope, ResourceHandle, ResourceIdentifier, ResourceLinks, ResourceObjectView, SchemaMap, SingleReadQuery, SortQuery, SortToken, StrategyDescriptor, StructuralGuardError, ToDocumentOptions, TransportRequest, TransportResponse, TypeAccessor, TypeName, TypedPage, TypedReadQuery, UpdateInput, ValidationConfig, ValidationOption, Validator, WireResource, WriteDocument, WriteOptions, assertJsonApiDocument, createClient, execute, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/serialize-write.ts"],"mappings":";;;;UACiB,kBAAA;EACf,EAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,MAAA;EACA,MAAA;IAAW,OAAA;IAAkB,SAAA;IAAoB,MAAA;EAAA;EACjD,IAAA,GAAO,MAAM;EADF;;;;;EAOX,IAAA;EAMA;;AAAO;AAUT;;EAVE,OAAA;AAAA;;;;;AAW2B;AAU7B;;cAXa,oBAAA,SAA6B,KAAK;cACjC,OAAA;AAAA;;;;;cAUD,YAAA,SAAqB,KAAA;EAAA,SACvB,MAAA;EAAA,SACA,MAAA,EAAQ,kBAAA;cAEL,MAAA,UAAgB,MAAA,EAAQ,kBAAA,IAAsB,OAAA;EAO1D,SAAA,CAAU,MAAA;EAIV,KAAA;EAIA,KAAA;EAIA,YAAA;EAIA,cAAA;EAIA,WAAA;EAIA,UAAA;EAIA,eAAA;EAIA,UAAA;EAIA,sBAAA;EAIA,eAAA;EAxBA;EA6BA,iBAAA;EAIA,aAAA;EArBA;;;;;EA8BA,MAAA,IAAU,MAAA,SAAe,kBAAA;AAAA;;;;;;;;UClFjB,eAAA;EACR,IAAA;EACA,EAAA;EACA,GAAA;EACA,IAAA;IAAS,KAAA,EAAO,MAAA;EAAA,IAA4B,MAAM;AAAA;;UAInC,oBAAA;EACf,IAAA,EAAM,eAAA,GAAkB,eAAe;AAAA;ADNZ;AAAA,UCUZ,aAAA;EACf,IAAA;IACE,IAAA;IACA,EAAA;IACA,UAAA,GAAa,MAAA;IACb,aAAA,GAAgB,MAAA,SAAe,oBAAA;EAAA;AAAA;;UAKlB,iBAAA;EDViB;;;;;ECgBhC,EAAE;AAAA;;;;;;;;;;;;;;;iBAiBY,UAAA,CACd,UAAA,EAAY,aAAA,EACZ,IAAA,UACA,KAAA,EAAO,MAAA,mBACP,IAAA,GAAO,iBAAA,GACN,aAAA;;;;;;AD+B0C;;;;AClGmB;;;iBAmHhD,sBAAA,CACd,IAAA,WACA,WAAA,mBACC,oBAAoB;;;;;;;;;AAlG6B;AAIpD;;;;;;;;AACyC;iBAwLzB,YAAA,CAAa,UAAA,EAAY,aAAa,EAAE,IAAA,UAAc,OAAA;;;;;;;;;;;;;;;;;AA/Kf;iBA+PvC,wBAAA,CAAyB,GAAA,UAAa,QAAA,WAAmB,OAAA;;;;AApPrE;AAiBJ;;iBAqPgB,iBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,IAAA,WACC,YAAA;;;;;;;;iBAWa,6BAAA,CACd,KAAA,EAAO,YAAA,EACP,GAAA,UACA,QAAA,YACC,YAAY;;;;;;;;AAnQC;AAgDhB;iBAgOgB,uBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,SAAA,GAAY,OAAA,kCACX,YAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/serialize-write.ts"],"mappings":";;;;;;AAOA;;;;UAAiB,kBAAA;EACf,EAAA;EACA,MAAA;EACA,IAAA,GAAO,CAAA;EACP,KAAA;EACA,MAAA;EACA,MAAA;IAAW,OAAA;IAAkB,SAAA;IAAoB,MAAA;EAAA;EACjD,IAAA,GAAO,MAAM;EAAN;;;;AAYA;EANP,IAAA;EAgBgC;;;;;EAVhC,OAAA;AAAA;AAW2B;AAa7B;;;;;;AAb6B,cADhB,oBAAA,SAA6B,KAAK;cACjC,OAAA;AAAA;;;;;;;;cAaD,YAAA,oCAAgD,KAAA;EAAA,SAClD,MAAA;EAAA,SACA,MAAA,EAAQ,kBAAA,CAAmB,CAAA;cAExB,MAAA,UAAgB,MAAA,EAAQ,kBAAA,CAAmB,CAAA,KAAM,OAAA;EAO7D,SAAA,CAAU,MAAA;EAIV,KAAA;EAIA,KAAA;EAIA,YAAA;EAIA,cAAA;EAIA,WAAA;EAIA,UAAA;EAIA,eAAA;EAIA,UAAA;EAIA,sBAAA;EAIA,eAAA;EApBA;EAyBA,iBAAA;EAIA,aAAA;EAjBA;;;;;EA0BA,MAAA,IAAU,MAAA,SAAe,kBAAA,CAAmB,CAAA;AAAA;;;;AAAC;AAgB/C;;iBAAgB,YAAA,CAAa,GAAA,WAAc,IAAA,WAAe,GAAA,IAAO,YAAY;;;;;;KASjE,cAAA,sBAAoC,GAAA,WAAc,IAAA,EAAM,CAAA,KAAM,GAAA,IAAO,YAAA,CAAa,CAAA;;;;;;;;UCpHpF,eAAA;EACR,IAAA;EACA,EAAA;EACA,GAAA;EACA,IAAA;IAAS,KAAA,EAAO,MAAA;EAAA,IAA4B,MAAM;AAAA;;UAInC,oBAAA;EACf,IAAA,EAAM,eAAA,GAAkB,eAAe;AAAA;;UAIxB,aAAA;EACf,IAAA;IACE,IAAA;IACA,EAAA;IACA,UAAA,GAAa,MAAA;IACb,aAAA,GAAgB,MAAA,SAAe,oBAAA;EAAA;AAAA;;UAKlB,iBAAA;EDoEU;;;;;EC9DzB,EAAE;AAAA;;;;;;;;;;;;;;;iBAiBY,UAAA,CACd,UAAA,EAAY,aAAA,EACZ,IAAA,UACA,KAAA,EAAO,MAAA,mBACP,IAAA,GAAO,iBAAA,GACN,aAAA;;;;;;;;;;;;;iBAgDa,sBAAA,CACd,IAAA,WACA,WAAA,mBACC,oBAAoB;;ADXwB;AAgB/C;;;;;;;;;AAA6E;AAS7E;;;;;;iBC6EgB,YAAA,CAAa,UAAA,EAAY,aAAa,EAAE,IAAA,UAAc,OAAA;;;;;;;;;;AD7EyB;;;;ACpI/B;;;;iBAiShD,wBAAA,CAAyB,GAAA,UAAa,QAAA,WAAmB,OAAA;;;;;;;iBAkBzD,iBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,IAAA,WACC,YAAA;AAnSiD;AAIpD;;;;;;AAJoD,iBA8SpC,6BAAA,CACd,KAAA,EAAO,YAAA,EACP,GAAA,UACA,QAAA,YACC,YAAY;;AA7S0B;AAIzC;;;;;;;iBAsTgB,uBAAA,CACd,KAAA,EAAO,YAAA,EACP,UAAA,EAAY,aAAA,EACZ,SAAA,GAAY,OAAA,kCACX,YAAA"}