@haddowg/json-api-codegen 1.0.1 → 1.2.0

package/dist/{src-B24cYyjM.mjs → src-C3hOfyvh.mjs}

@@ -1,10 +1,10 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { ATOMIC_EXT, HANDLE_RESERVED } from "@haddowg/json-api-client";
+import { ATOMIC_EXT, CANONICAL_PAGE_KEYS, HANDLE_RESERVED } from "@haddowg/json-api-client";
 import { createHash } from "node:crypto";
 import { parse } from "yaml";
 //#region src/build-descriptor.ts
-const REF_PREFIX$1 = "#/components/schemas/";
+const REF_PREFIX$2 = "#/components/schemas/";
 const JSON_API_MEDIA_TYPE$1 = "application/vnd.api+json";
 /** Sort a record's keys for deterministic, snapshot-stable output. */
 function sortRecord(record) {
@@ -14,9 +14,9 @@ function sortRecord(record) {
 }
 /** Resolve a local schema name from a `#/components/schemas/X` ref. */
 function refName$1(ref) {
-	return ref.startsWith(REF_PREFIX$1) ? ref.slice(21) : void 0;
+	return ref.startsWith(REF_PREFIX$2) ? ref.slice(21) : void 0;
 }
-function isSchema$1(value) {
+function isSchema$2(value) {
 	return typeof value === "object" && value !== null;
 }
 /** The set of `type` keys a JSON type node declares, with `"null"` removed. */
@@ -75,11 +75,27 @@ var DescriptorBuilder = class {
 			if (filterable !== void 0) descriptor.filterable = filterable;
 			if (Object.keys(actions).length > 0) descriptor.actions = actions;
 			if (Object.keys(schema.properties ?? {}).every((prop) => prop === "type") && Object.keys(descriptor.paths).length === 0) continue;
+			this.warnWriteOnlyRelations(wireType, base, descriptor.relations);
 			out[wireType] = descriptor;
 		}
 		return sortRecord(out);
 	}
 	/**
+	* Warn about relations a create or update body accepts but the resource never renders. A
+	* write-only relation (generator contract 5) is left out of the response schema, and the
+	* descriptor has no way to mark a relation as writable but unreadable, so it is missing from
+	* the client entirely rather than typed onto reads that never carry it.
+	*/
+	warnWriteOnlyRelations(wireType, base, readable) {
+		const writeOnly = /* @__PURE__ */ new Set();
+		for (const request of [`${base}CreateRequest`, `${base}UpdateRequest`]) {
+			const data = this.schemas[request]?.properties?.["data"];
+			const relationships = isSchema$2(data) ? data.properties?.["relationships"] : void 0;
+			for (const name of Object.keys(isSchema$2(relationships) ? relationships.properties ?? {} : {})) if (!(name in readable)) writeOnly.add(name);
+		}
+		for (const name of writeOnly) console.warn(`json-api codegen: relationship "${name}" on "${wireType}" is accepted on writes but never rendered (a write-only relation); the client has no slot for a relation it can't read, so it is left out.`);
+	}
+	/**
 	* The server-level Atomic Operations capability: the path whose `POST` requestBody
 	* declares the atomic ext media type ({@link ATOMIC_EXT}). `null` when no such endpoint
 	* exists. Server-level, so it rides {@link buildAtomic}, not the per-type descriptor.
@@ -99,28 +115,28 @@ var DescriptorBuilder = class {
 	resourceType(name, schema) {
 		if (!name.endsWith("Resource") || name.endsWith("ResourceIdentifier")) return;
 		const constValue = schema.properties?.["type"];
-		if (isSchema$1(constValue) && typeof constValue.const === "string") return constValue.const;
+		if (isSchema$2(constValue) && typeof constValue.const === "string") return constValue.const;
 	}
 	/** Follow a `$ref` to its identifier/resource schema and read `properties.type.const`. */
 	resolveConst(ref) {
 		const target = refName$1(ref);
 		if (target === void 0) return;
 		const typeProp = this.schemas[target]?.properties?.["type"];
-		return isSchema$1(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
+		return isSchema$2(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
 	}
 	attributes(base) {
 		const props = this.schemas[`${base}Attributes`]?.properties;
 		if (props === void 0) return {};
 		const out = {};
-		for (const [name, prop] of Object.entries(props)) if (isSchema$1(prop)) out[name] = formatHint(prop);
+		for (const [name, prop] of Object.entries(props)) if (isSchema$2(prop)) out[name] = formatHint(prop);
 		return sortRecord(out);
 	}
 	relations(resource, collection) {
-		const relProps = isSchema$1(resource.properties?.["relationships"]) ? resource.properties["relationships"].properties : void 0;
+		const relProps = isSchema$2(resource.properties?.["relationships"]) ? resource.properties["relationships"].properties : void 0;
 		if (relProps === void 0) return {};
 		const out = {};
 		for (const [name, prop] of Object.entries(relProps)) {
-			if (!isSchema$1(prop) || typeof prop.$ref !== "string") continue;
+			if (!isSchema$2(prop) || typeof prop.$ref !== "string") continue;
 			const component = this.schemas[refName$1(prop.$ref) ?? ""];
 			const descriptor = component ? this.relationFromComponent(component) : void 0;
 			if (descriptor === void 0) {
@@ -171,10 +187,10 @@ var DescriptorBuilder = class {
 		const countable = withCountParam(relatedGet) ?? withCountParam(this.operation(`${collection}/{id}/relationships/${name}`, "get"));
 		if (countable !== void 0) out.countable = countable;
 		if (descriptor.cardinality === "many") {
-			const relatedKind = this.paginatorKindOf(relatedGet) === "none" ? this.paginatorKindOf(this.operation(`${collection}/{id}/relationships/${name}`, "get")) : this.paginatorKindOf(relatedGet);
+			const relatedPaginator = this.paginatorOf(relatedGet) === "none" ? this.paginatorOf(this.operation(`${collection}/{id}/relationships/${name}`, "get")) : this.paginatorOf(relatedGet);
 			const relatedType = descriptor.types[0];
-			const typeKind = relatedType !== void 0 ? this.typePaginator(relatedType) : "none";
-			if (relatedKind !== "none" && relatedKind !== typeKind) out.paginator = relatedKind;
+			const typePaginator = relatedType !== void 0 ? this.typePaginator(relatedType) : "none";
+			if (relatedPaginator !== "none" && JSON.stringify(relatedPaginator) !== JSON.stringify(typePaginator)) out.paginator = relatedPaginator;
 		}
 		return out;
 	}
@@ -243,8 +259,8 @@ var DescriptorBuilder = class {
 		if (typeof ref !== "string") return;
 		const component = refName$1(ref);
 		const data = component === void 0 ? void 0 : this.schemas[component]?.properties?.["data"];
-		if (!isSchema$1(data)) return;
-		if (isSchema$1(data.items)) {
+		if (!isSchema$2(data)) return;
+		if (isSchema$2(data.items)) {
 			const itemRef = data.items.$ref;
 			const many = typeof itemRef === "string" ? this.resolveConst(itemRef) : void 0;
 			return many === void 0 ? void 0 : {
@@ -262,7 +278,7 @@ var DescriptorBuilder = class {
 	dataConst(data) {
 		if (typeof data.$ref === "string") return this.resolveConst(data.$ref);
 		const typeProp = data.properties?.["type"];
-		return isSchema$1(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
+		return isSchema$2(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
 	}
 	/** The `$ref` of the first 2xx JSON:API response body on an operation (the output document). */
 	firstOkJsonApiRef(op) {
@@ -275,7 +291,7 @@ var DescriptorBuilder = class {
 	/** Resolve a relationship component's `data` into a {@link RelationDescriptor}. */
 	relationFromComponent(component) {
 		const data = component.properties?.["data"];
-		if (!isSchema$1(data)) return;
+		if (!isSchema$2(data)) return;
 		if (data.type === "array") {
 			const items = data.items;
 			if (items === void 0) return;
@@ -340,11 +356,11 @@ var DescriptorBuilder = class {
 	pivotFieldsFromAllOf(allOf) {
 		for (const entry of allOf) {
 			const meta = entry.properties?.["meta"];
-			const pivot = isSchema$1(meta) ? meta.properties?.["pivot"] : void 0;
-			const props = isSchema$1(pivot) ? pivot.properties : void 0;
+			const pivot = isSchema$2(meta) ? meta.properties?.["pivot"] : void 0;
+			const props = isSchema$2(pivot) ? pivot.properties : void 0;
 			if (props === void 0) continue;
 			const out = {};
-			for (const [name, schema] of Object.entries(props)) if (isSchema$1(schema)) out[name] = formatHint(schema);
+			for (const [name, schema] of Object.entries(props)) if (isSchema$2(schema)) out[name] = formatHint(schema);
 			return Object.keys(out).length > 0 ? sortRecord(out) : void 0;
 		}
 	}
@@ -366,7 +382,7 @@ var DescriptorBuilder = class {
 	}
 	clientId(base) {
 		const create = this.schemas[`${base}CreateRequest`];
-		const data = isSchema$1(create?.properties?.["data"]) ? create.properties["data"] : void 0;
+		const data = isSchema$2(create?.properties?.["data"]) ? create.properties["data"] : void 0;
 		if (data === void 0) return "forbidden";
 		if (data.properties?.["id"] === false) return "forbidden";
 		return data.required?.includes("id") ? "required" : "optional";
@@ -412,24 +428,55 @@ var DescriptorBuilder = class {
 		const prefix = `${collection}/{id}/relationships/`;
 		return Object.keys(this.paths).some((path) => path.startsWith(prefix) && !path.slice(prefix.length).includes("/"));
 	}
-	/** Detect the paginator kind from the fetchMany operation's query parameter names. */
+	/** Detect the paginator from the fetchMany operation's page parameters. */
 	paginator(base) {
 		const collection = this.collectionPath(base);
-		return this.paginatorKindOf(this.operation(collection ?? "", "get"), collection);
+		return this.paginatorOf(this.operation(collection ?? "", "get"), collection);
+	}
+	/**
+	* Detect the paginator an operation advertises. A page schema stamped with `x-paginator`
+	* (contract 3) names its strategy and the wire key for each role, so it decides both. Without
+	* the stamp, the strategy is inferred from canonical member names (see {@link kindOfMembers}).
+	* Anything unrecognised warns and generates as unpaginated. `label` (a path) names the endpoint
+	* in the warning; without it nothing is logged.
+	*/
+	paginatorOf(op, label) {
+		const warn = (problem) => {
+			if (label !== void 0) console.warn(`json-api codegen: endpoint "${label}" ${problem}; treating it as unpaginated.`);
+			return "none";
+		};
+		const schema = op?.parameters?.find((param) => param.name === "page")?.schema;
+		if (schema?.["x-paginator"] !== void 0) return stampedPaginator(schema, warn);
+		const { members, menu } = this.pageMembers(op);
+		if (menu === void 0) {
+			const kind = kindOfMembers(members);
+			if (kind !== void 0) return kind;
+		}
+		if (menu !== void 0) return warn(`advertises a selectable page strategy menu (${menu.map((arm) => kindOfMembers(arm) ?? sortedList(arm)).join(" | ")}) without an x-paginator stamp naming its default`);
+		return members.size > 0 ? warn(`advertises page parameters matching no known paginator kind (members ${sortedList(members)})`) : "none";
 	}
 	/**
-	* Detect the paginator kind an operation advertises from its `page[...]` query parameter names.
-	* `page[number]`+`page[size]` = `page`; `page[offset]`+`page[limit]` = `offset`; either cursor
-	* bound (`page[after]`/`page[before]`) = `cursor` (link-driven, D44); anything else = `none`.
-	* `label` (a path, for the drift warning) names the endpoint when page params match no known kind.
+	* The `page` members an operation accepts, from either wire form: one `page` parameter
+	* (`style: deepObject`) whose schema `properties` name the members, as `haddowg/json-api` v1
+	* projects it, or the older flattened `page[number]`/`page[size]` parameters. A `oneOf` page
+	* schema (a MultiPaginator menu) yields each arm's members in `menu` instead, minus the
+	* `kind` discriminator.
 	*/
-	paginatorKindOf(op, label) {
-		const names = this.queryParamNames(op);
-		if (names.has("page[number]") && names.has("page[size]")) return "page";
-		if (names.has("page[offset]") && names.has("page[limit]")) return "offset";
-		if (names.has("page[after]") || names.has("page[before]")) return "cursor";
-		if (label !== void 0 && [...names].some((name) => name.startsWith("page["))) console.warn(`json-api codegen: endpoint "${label}" advertises page parameters matching no known paginator kind; treating it as unpaginated.`);
-		return "none";
+	pageMembers(op) {
+		const members = /* @__PURE__ */ new Set();
+		let menu;
+		for (const param of op?.parameters ?? []) {
+			const name = param.name;
+			if (name === "page") {
+				const arms = param.schema?.oneOf;
+				if (arms !== void 0) menu = arms.map((arm) => new Set(Object.keys(arm.properties ?? {}).filter((m) => m !== "kind")));
+				for (const member of Object.keys(param.schema?.properties ?? {})) members.add(member);
+			} else if (name?.startsWith("page[") === true && name.endsWith("]")) members.add(name.slice(5, -1));
+		}
+		return menu === void 0 ? { members } : {
+			members,
+			menu
+		};
 	}
 	/**
 	* The `withCount` capability (Countable profile) for a type's COLLECTION read (`list`): the
@@ -487,11 +534,6 @@ var DescriptorBuilder = class {
 		}
 		return keys.length > 0 ? keys.sort() : void 0;
 	}
-	queryParamNames(op) {
-		const names = /* @__PURE__ */ new Set();
-		for (const param of op?.parameters ?? []) if (typeof param.name === "string") names.add(param.name);
-		return names;
-	}
 	operation(path, method) {
 		return this.paths[path]?.[method];
 	}
@@ -508,6 +550,9 @@ function formatHint(schema) {
 	const types = typeKeys(schema.type);
 	if (types.length > 0) return types[0];
 	if (typeof schema.$ref === "string") return "string";
+	const isNullOnly = (branch) => branch.type !== void 0 && typeKeys(branch.type).length === 0;
+	const branches = (schema.anyOf ?? schema.oneOf ?? []).filter((branch) => !isNullOnly(branch));
+	if (branches.length === 1) return formatHint(branches[0]);
 	return "unknown";
 }
 function refEndsWith(ref, suffix) {
@@ -613,6 +658,234 @@ function buildDescriptor(doc) {
 function buildAtomic(doc) {
 	return new DescriptorBuilder(doc).buildAtomic();
 }
+/**
+* Classify a page member set: `number`+`size` = `page`; `offset`+`limit` = `offset`; either
+* cursor bound (`after`/`before`) = `cursor` (link-driven, D44); `number` alone = `fixed` (the
+* server fixes the size); no members = `none`; anything else = `undefined` (unrecognised).
+*/
+function kindOfMembers(members) {
+	if (members.has("number") && members.has("size")) return "page";
+	if (members.has("offset") && members.has("limit")) return "offset";
+	if (members.has("after") || members.has("before")) return "cursor";
+	if (members.size === 1 && members.has("number")) return "fixed";
+	return members.size === 0 ? "none" : void 0;
+}
+const sortedList = (members) => [...members].sort().join(", ");
+const STRATEGIES = [
+	"page",
+	"offset",
+	"cursor",
+	"fixed"
+];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Read a page schema's `x-paginator` stamp. A strategy keeps the wire key the stamp names for
+* each of its roles (a missing role keeps its canonical name) and collapses to the bare kind when
+* every key is canonical. A `multi` stamp reads each `oneOf` arm by its `kind` const: an arm's own
+* stamp decides it, an unstamped arm falls back to name inference, and an arm neither recognises
+* is left out of the menu.
+*/
+function stampedPaginator(schema, warn) {
+	const stamp = schema["x-paginator"];
+	const strategy = isRecord(stamp) ? stamp["strategy"] : void 0;
+	if (!isRecord(stamp) || typeof strategy !== "string") return warn("stamps a malformed x-paginator");
+	if (strategy === "multi") return stampedMenu(schema, stamp, warn);
+	if (!STRATEGIES.includes(strategy)) return warn(`stamps an x-paginator strategy "${strategy}" this codegen does not know`);
+	const kind = strategy;
+	const canonical = CANONICAL_PAGE_KEYS[kind];
+	const stamped = isRecord(stamp["keys"]) ? stamp["keys"] : {};
+	const keys = {};
+	let renamed = false;
+	for (const [role, fallback] of Object.entries(canonical)) {
+		const key = typeof stamped[role] === "string" ? stamped[role] : fallback;
+		keys[role] = key;
+		renamed ||= key !== fallback;
+	}
+	return renamed ? {
+		strategy: kind,
+		keys
+	} : kind;
+}
+function stampedMenu(schema, stamp, warn) {
+	const arms = {};
+	for (const arm of schema.oneOf ?? []) {
+		const discriminator = arm.properties?.["kind"];
+		const kind = isRecord(discriminator) ? discriminator["const"] : void 0;
+		if (typeof kind !== "string") {
+			warn("offers a page strategy menu arm without a kind const, which is left out");
+			continue;
+		}
+		const paginator = arm["x-paginator"] !== void 0 ? stampedPaginator(arm, (problem) => warn(`offers a menu arm "${kind}" that ${problem}, which is left out`)) : kindOfMembers(new Set(Object.keys(arm.properties ?? {}).filter((m) => m !== "kind"))) ?? warn(`offers a menu arm "${kind}" matching no known paginator kind, which is left out`);
+		if (typeof paginator === "object" && paginator.strategy === "multi") {
+			warn(`nests a page strategy menu in arm "${kind}", which is left out`);
+			continue;
+		}
+		if (paginator !== "none") arms[kind] = paginator;
+	}
+	const fallback = stamp["default"];
+	if (typeof fallback !== "string" || arms[fallback] === void 0) return warn(`stamps a page strategy menu whose default ${typeof fallback === "string" ? `"${fallback}"` : "(missing)"} is not one of its generated arms`);
+	return {
+		strategy: "multi",
+		default: fallback,
+		arms
+	};
+}
+//#endregion
+//#region src/contract.ts
+/** Below this the document predates the structures this codegen reads. */
+const MINIMUM_CONTRACT = 1;
+/** Above this the document carries structures this codegen does not read. */
+const MAXIMUM_CONTRACT = 5;
+/**
+* Check the document's `info.x-generator.contract` against the range this codegen reads. A
+* document older than the range throws; a newer one returns a warning, because its new
+* structures would go unread and the client would silently miss what the server offers. A
+* document with no contract (json-api before 1.1.0) passes.
+*/
+function checkContract(doc) {
+	const contract = doc.info?.["x-generator"]?.contract;
+	if (typeof contract !== "number") return;
+	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 5). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 5) return `the document declares contract ${contract} and this codegen reads up to 5. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
+}
+//#endregion
+//#region src/error-codes.ts
+const REF_PREFIX$1 = "#/components/schemas/";
+const ERROR_DOCUMENT = /^ErrorDocument(\d{3})?$/;
+function isSchema$1(value) {
+	return typeof value === "object" && value !== null;
+}
+/** A schema node and its `allOf` members, where a code variant keeps its narrowing. */
+function layers(schema) {
+	return [schema, ...(schema.allOf ?? []).filter((member) => member.$ref === void 0)];
+}
+function property(schema, name) {
+	for (const layer of layers(schema)) {
+		const prop = layer.properties?.[name];
+		if (isSchema$1(prop)) return prop;
+	}
+}
+function examplesOf(detail) {
+	if (detail === void 0) return [];
+	const examples = Array.isArray(detail["examples"]) ? [...detail["examples"]] : [];
+	if ("example" in detail && !examples.includes(detail["example"])) examples.unshift(detail["example"]);
+	return examples;
+}
+/**
+* Read the documented error codes off a document's error documents. `ErrorDocument` and each
+* `ErrorDocument<NNN>` offer their codes as `errors.items.anyOf` branches that `$ref` a
+* `<Code>Error` component; a branch with a `code` const names a code, and the generic `Error`
+* branch (no const) names none.
+*/
+function readErrorCatalogue(doc) {
+	const schemas = doc.components?.schemas ?? {};
+	const codes = /* @__PURE__ */ new Map();
+	const byStatus = /* @__PURE__ */ new Map();
+	for (const [name, schema] of Object.entries(schemas)) {
+		const match = ERROR_DOCUMENT.exec(name);
+		if (match === null) continue;
+		const items = property(schema, "errors")?.items;
+		const branches = items === void 0 ? [] : [...items.anyOf ?? [], ...items.oneOf ?? []];
+		const documentCodes = /* @__PURE__ */ new Set();
+		for (const branch of branches) {
+			const component = typeof branch.$ref === "string" && branch.$ref.startsWith(REF_PREFIX$1) ? schemas[branch.$ref.slice(21)] : branch;
+			const code = component === void 0 ? void 0 : property(component, "code")?.const;
+			if (component === void 0 || typeof code !== "string") continue;
+			documentCodes.add(code);
+			if (!codes.has(code)) {
+				const description = layers(component).map((layer) => layer.description?.trim()).find((text) => text !== void 0 && text !== "");
+				codes.set(code, {
+					code,
+					...description ? { description } : {},
+					examples: examplesOf(property(component, "detail"))
+				});
+			}
+		}
+		if (match[1] !== void 0) byStatus.set(Number(match[1]), [...documentCodes].sort());
+	}
+	return {
+		codes: [...codes.values()].sort((a, b) => a.code < b.code ? -1 : a.code > b.code ? 1 : 0),
+		byStatus: new Map([...byStatus].sort(([a], [b]) => a - b))
+	};
+}
+/** A TSDoc block for one code: its description, then each example detail as an `@example`. */
+function codeDoc(entry, indent) {
+	const lines = [];
+	if (entry.description !== void 0) lines.push(...entry.description.split("\n"));
+	for (const example of entry.examples) {
+		if (lines.length > 0) lines.push("");
+		const text = typeof example === "string" ? example : JSON.stringify(example);
+		lines.push(...`@example ${text}`.split("\n"));
+	}
+	if (lines.length === 0) return;
+	if (lines.length === 1) return `${indent}/** ${lines[0].replace(/\*\//g, "* /")} */`;
+	return [
+		`${indent}/**`,
+		...lines.map((line) => `${indent} * ${line.replace(/\*\//g, "* /")}`.trimEnd()),
+		`${indent} */`
+	].join("\n");
+}
+/** A bare object key when the code is a valid identifier, else a quoted one. */
+function codeKey(code) {
+	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(code) ? code : JSON.stringify(code);
+}
+/**
+* Emit `ErrorCodes`, a const object keyed by every documented code with its TSDoc on the key
+* (editors show TSDoc on an object key, not on a string-literal union member), the `ErrorCode`
+* union derived from it, and `ErrorCodeByStatus`, the codes each status's error document offers.
+* A document with no code catalogue gets an empty `ErrorCodes` and `ErrorCode = string`, so the
+* bound guard still takes any code.
+*/
+function emitErrorCodes(catalogue) {
+	const codeTypes = catalogue.codes.length === 0 ? [
+		"/** The documented error codes. This document catalogues none. */",
+		"export const ErrorCodes = {} as const",
+		"",
+		"/** The documented error codes. This document catalogues none, so any code is accepted. */",
+		"export type ErrorCode = string"
+	].join("\n") : [
+		"/**",
+		" * Every error code this server documents, keyed by itself. Hover a key for what the code",
+		" * means: `hasErrorCode(error, ErrorCodes.RESOURCE_NOT_FOUND)`.",
+		" */",
+		"export const ErrorCodes = {",
+		...catalogue.codes.flatMap((entry) => {
+			const doc = codeDoc(entry, "  ");
+			const member = `  ${codeKey(entry.code)}: ${JSON.stringify(entry.code)},`;
+			return doc === void 0 ? [member] : [doc, member];
+		}),
+		"} as const",
+		"",
+		"/**",
+		" * Every error code this server documents. An error may still carry a code that is not",
+		" * listed: the catalogue is open.",
+		" */",
+		"export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]"
+	].join("\n");
+	const statusLines = [...catalogue.byStatus].map(([status, codes]) => {
+		const members = codes.map((c) => JSON.stringify(c));
+		const line = `  ${status}: ${members.length === 0 ? "never" : members.join(" | ")}`;
+		return line.length <= 100 ? line : `  ${status}:\n${members.map((m) => `    | ${m}`).join("\n")}`;
+	});
+	return [
+		codeTypes,
+		[
+			"/**",
+			" * The documented error codes per HTTP status. `never` marks a status whose error document",
+			" * documents no specific code.",
+			" */",
+			statusLines.length === 0 ? "export interface ErrorCodeByStatus {}" : `export interface ErrorCodeByStatus {\n${statusLines.join("\n")}\n}`
+		].join("\n"),
+		[
+			"/**",
+			" * True when `err` is a `JsonApiError` and any of its error objects carries `code`. Only takes a",
+			" * documented code; match an undocumented one with `hasErrorCode` from",
+			" * '@haddowg/json-api-client'.",
+			" */",
+			"export const hasErrorCode = hasErrorCodeRuntime as ErrorCodeGuard<ErrorCode>"
+		].join("\n")
+	].join("\n\n");
+}
 //#endregion
 //#region src/provenance.ts
 /**
@@ -724,6 +997,53 @@ function jsDoc(text, indent) {
 		`${indent} */`
 	].join("\n");
 }
+/** The validation keywords a member's TSDoc states, each as a tag of the same name. */
+const CONSTRAINT_KEYWORDS = [
+	"format",
+	"pattern",
+	"minLength",
+	"maxLength",
+	"minimum",
+	"exclusiveMinimum",
+	"maximum",
+	"exclusiveMaximum",
+	"multipleOf",
+	"minItems",
+	"maxItems",
+	"uniqueItems",
+	"minProperties",
+	"maxProperties"
+];
+/** A tag value as TSDoc text: strings bare, a pattern or anything structured as code. */
+function tagValue(keyword, value) {
+	if (keyword === "pattern" || typeof value !== "string" && typeof value !== "number") return `\`${typeof value === "string" ? value : JSON.stringify(value)}\``;
+	return String(value);
+}
+/**
+* The TSDoc for an attribute: its description, then a tag per constraint the schema declares
+* (`@minLength 1`, `@pattern …`), its `@defaultValue`, any `@example` and `@deprecated`. Each
+* schema states the constraints of the context it describes, so a read member and its create
+* and update counterparts can document different bounds. The keywords are read off the member
+* and any inline `anyOf`/`oneOf` branch; a `$ref`'d component documents itself.
+*/
+function memberDoc(schema) {
+	const layers = [schema, ...[...schema.anyOf ?? [], ...schema.oneOf ?? []].filter((branch) => branch.$ref === void 0)];
+	const tags = [];
+	for (const keyword of CONSTRAINT_KEYWORDS) for (const layer of layers) {
+		const value = layer[keyword];
+		if (value === void 0 || value === false) continue;
+		tags.push(value === true ? `@${keyword}` : `@${keyword} ${tagValue(keyword, value)}`);
+		break;
+	}
+	if ("default" in schema) tags.push(`@defaultValue \`${JSON.stringify(schema["default"])}\``);
+	const examples = Array.isArray(schema["examples"]) ? [...schema["examples"]] : [];
+	if ("example" in schema && !examples.includes(schema["example"])) examples.unshift(schema["example"]);
+	for (const example of examples) tags.push(`@example ${typeof example === "string" ? example : JSON.stringify(example)}`);
+	if (schema["deprecated"] === true) tags.push("@deprecated");
+	const description = schema.description?.trim();
+	if (tags.length === 0) return description;
+	return description ? `${description}\n\n${tags.join("\n")}` : tags.join("\n");
+}
 var Emitter = class {
 	doc;
 	descriptor;
@@ -786,6 +1106,8 @@ var Emitter = class {
 			this.resourceMap(),
 			"export type ResourceMap = typeof resourceMap",
 			this.atomicConst(),
+			this.pageLimitsConst(),
+			emitErrorCodes(readErrorCatalogue(this.doc)),
 			this.boundFactory()
 		].join("\n\n")}\n`;
 	}
@@ -805,6 +1127,8 @@ var Emitter = class {
 			"  type ApiDescriptor,",
 			"  type ClientOptions,",
 			"  createClient as createClientRuntime,",
+			"  type ErrorCodeGuard,",
+			"  hasErrorCode as hasErrorCodeRuntime,",
 			"} from '@haddowg/json-api-client'"
 		].join("\n");
 	}
@@ -931,6 +1255,54 @@ var Emitter = class {
 		].join("\n")}\nexport const atomic = ${this.atomic === null ? "null" : `${this.literal(this.atomic, 0)} as const`}`;
 	}
 	/**
+	* The `pageLimits` const: per collection, the `default`, `minimum` and `maximum` each `page`
+	* member declares (generator contract 5 adds the paginator's default and page-size cap). A
+	* menu nests them under each arm's `kind`. Members declaring none, and collections with no
+	* such member, are left out. The client never clamps a `page` argument to these.
+	*/
+	pageLimitsConst() {
+		const typeLines = [];
+		for (const type of Object.keys(this.descriptor)) {
+			const path = this.descriptor[type].paths["fetchMany"];
+			const schema = (path === void 0 ? void 0 : this.doc.paths?.[path]?.get?.parameters)?.find((param) => param.name === "page")?.schema;
+			if (schema === void 0) continue;
+			let body = [];
+			if (schema.oneOf !== void 0) for (const arm of schema.oneOf) {
+				const kind = isSchema(arm.properties?.["kind"]) ? arm.properties["kind"].const : void 0;
+				const members = this.pageMemberLimits(arm, "      ");
+				if (typeof kind === "string" && members.length > 0) body.push(`    ${objectKey(kind)}: {\n${members.join("\n")}\n    },`);
+			}
+			else body = this.pageMemberLimits(schema, "    ");
+			if (body.length > 0) typeLines.push(`  ${objectKey(type)}: {\n${body.join("\n")}\n  },`);
+		}
+		return `${[
+			"/**",
+			" * The bounds each collection's `page` parameter declares, keyed by type, then by strategy for a",
+			" * collection offering several, then by wire key. `default` is what the server uses when the key",
+			" * is absent and `maximum` is the largest value it serves. The client sends the `page` you pass",
+			" * unchanged, so read these to bound a page-size picker.",
+			" */"
+		].join("\n")}\nexport const pageLimits = ${typeLines.length === 0 ? "{}" : `{\n${typeLines.join("\n")}\n}`} as const`;
+	}
+	/** One page schema's members that declare a `default`, `minimum` or `maximum`, as literal lines. */
+	pageMemberLimits(schema, indent) {
+		const lines = [];
+		for (const [name, prop] of Object.entries(schema.properties ?? {})) {
+			if (!isSchema(prop) || name === "kind") continue;
+			const limits = [];
+			for (const keyword of [
+				"default",
+				"minimum",
+				"maximum"
+			]) if (typeof prop[keyword] === "number") limits.push(`${keyword}: ${String(prop[keyword])}`);
+			if (limits.length === 0) continue;
+			const doc = jsDoc(memberDoc(prop), indent);
+			if (doc !== void 0) lines.push(doc);
+			lines.push(`${indent}${objectKey(name)}: { ${limits.join(", ")} },`);
+		}
+		return lines;
+	}
+	/**
 	* Render an attribute interface from a property map, a field order, and a `required`
 	* predicate (true => no `?`). Shared by the read and write attribute interfaces so the
 	* tsType/JSDoc logic stays in one place.
@@ -940,7 +1312,7 @@ var Emitter = class {
 		for (const field of fields) {
 			const schema = props?.[field];
 			const tsType = isSchema(schema) ? this.tsType(schema) : "unknown";
-			const doc = isSchema(schema) ? jsDoc(schema.description, "  ") : void 0;
+			const doc = isSchema(schema) ? jsDoc(memberDoc(schema), "  ") : void 0;
 			if (doc) lines.push(doc);
 			const optional = required(field) ? "" : "?";
 			lines.push(`  ${objectKey(field)}${optional}: ${tsType}`);
@@ -965,7 +1337,16 @@ var Emitter = class {
 			this.expanding.delete(target);
 			return expanded;
 		}
+		const branches = schema.anyOf ?? schema.oneOf;
+		if (schema.type === void 0 && branches !== void 0 && branches.length > 0) {
+			const members = branches.map((branch) => this.tsType(branch));
+			const nullable = members.includes("null");
+			const rest = [...new Set(members.filter((member) => member !== "null"))];
+			if (rest.length === 0) return "null";
+			return nullable ? `${rest.join(" | ")} | null` : rest.join(" | ");
+		}
 		const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+		if (types.length === 1 && types[0] === "null") return "null";
 		const nullable = types.includes("null");
 		const base = this.baseTsType(schema, types.filter((t) => t !== "null"));
 		return nullable ? `${base} | null` : base;
@@ -1005,7 +1386,9 @@ var Emitter = class {
 	arrayType(schema) {
 		const items = schema.items;
 		const element = isSchema(items) ? this.tsType(items) : "unknown";
-		return /[|&]/.test(element) ? `(${element})[]` : `${element}[]`;
+		const list = /[|&]/.test(element) ? `(${element})[]` : `${element}[]`;
+		const minItems = schema["minItems"];
+		return typeof minItems === "number" && minItems >= 1 ? `[${element}, ...${list}]` : list;
 	}
 	/** Union aliases for every enum component an attribute referenced, sorted by name. */
 	enumAliases() {
@@ -1083,10 +1466,11 @@ var Emitter = class {
 			"/**",
 			" * Descriptor-bound client factory; wraps the generic runtime with this API’s `resourceMap`.",
 			" * The server-level `atomic` capability is threaded in by default so `client.atomic` is wired",
-			" * (a caller may still override it via `options.atomic`).",
+			" * (a caller may still override it via `options.atomic`). The client type carries `ErrorCode`,",
+			" * so bindings that only see the client (the Angular refs) type its errors.",
 			" */",
 			"export const createClient = (options: ClientOptions) =>",
-			"  createClientRuntime<typeof resourceMap, Attributes, WriteAttributes, ActionTypes>(",
+			"  createClientRuntime<typeof resourceMap, Attributes, WriteAttributes, ActionTypes, ErrorCode>(",
 			"    resourceMap,",
 			"    {",
 			"      atomic,",
@@ -1211,8 +1595,11 @@ function schemasOutputPath(output) {
 */
 async function render(config) {
 	const doc = await readDocument(config.input);
+	const contractWarning = checkContract(doc);
+	if (contractWarning !== void 0) console.warn(`[json-api-codegen] ${contractWarning}`);
 	const descriptor = buildDescriptor(doc);
 	for (const { type, relation } of detectVerbCollisions(descriptor)) console.warn(`[json-api-codegen] "${type}" has a relation named "${relation}" which collides with a reserved verb on the resource handle; it will be reachable via .rel("${relation}") in the fluent client.`);
+	if (Object.keys(descriptor).length === 0) console.warn(`[json-api-codegen] found no JSON:API resource types in ${config.input}; the generated client is empty.`);
 	const artifacts = [{
 		path: config.output,
 		content: emit(doc, descriptor)
@@ -1273,6 +1660,6 @@ async function check(config) {
 	};
 }
 //#endregion
-export { readSchemas as a, detectVerbCollisions as c, hashJson as d, provenanceLines as f, buildDescriptor as h, readDocument as i, emit as l, buildAtomic as m, generate as n, emitSchemas as o, DescriptorBuilder as p, schemasOutputPath as r, Emitter as s, check as t, deriveProvenance as u };
+export { checkContract as _, readSchemas as a, buildDescriptor as b, detectVerbCollisions as c, hashJson as d, provenanceLines as f, MINIMUM_CONTRACT as g, MAXIMUM_CONTRACT as h, readDocument as i, emit as l, readErrorCatalogue as m, generate as n, emitSchemas as o, emitErrorCodes as p, schemasOutputPath as r, Emitter as s, check as t, deriveProvenance as u, DescriptorBuilder as v, buildAtomic as y };
 
-//# sourceMappingURL=src-B24cYyjM.mjs.map
+//# sourceMappingURL=src-C3hOfyvh.mjs.map