@haddowg/json-api-client 1.1.0 → 1.3.0

package/dist/index.mjs

@@ -15,6 +15,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;
@@ -79,6 +82,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). */
@@ -191,9 +248,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) {
@@ -246,7 +304,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;
@@ -256,13 +314,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,
@@ -369,33 +427,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);
@@ -422,18 +482,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
@@ -441,11 +501,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
@@ -475,6 +538,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))}`);
@@ -511,14 +582,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;
@@ -948,6 +1019,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
@@ -960,7 +1043,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;
@@ -969,8 +1052,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);
 }
 /**
@@ -1008,7 +1093,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;
@@ -1107,8 +1192,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);
@@ -1187,7 +1273,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 = {
@@ -1205,6 +1291,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);
@@ -1235,6 +1322,6 @@ function createClient(descriptor, options) {
 	});
 }
 //#endregion
-export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, HANDLE_RESERVED, JSON_API_MEDIA_TYPE, JsonApiError, StructuralGuardError, assertJsonApiDocument, createClient, execute, fetchTransport, materialise, mediaType, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
+export { ATOMIC_EXT, ATOMIC_MEDIA_TYPE, CANONICAL_PAGE_KEYS, HANDLE_RESERVED, JSON_API_MEDIA_TYPE, JsonApiError, StructuralGuardError, assertJsonApiDocument, createClient, execute, fetchTransport, hasErrorCode, materialise, mediaType, relatedPaginator, relatedPaginatorKind, remapPointer, remapRelationshipPointer, resolvePaginator, resolveValidator, runAtomic, serializeQuery, toDocument, toRelationshipDocument, validateDocument, withRemappedAtomicPaths, withRemappedPaths, withRemappedRelationshipPaths };
 
 //# sourceMappingURL=index.mjs.map