@haddowg/json-api-codegen 1.13.0 → 1.15.0

package/README.md

@@ -30,19 +30,23 @@ pnpm add -D @haddowg/json-api-codegen
 
 Two bin names are installed: `json-api-codegen` and the short alias `japi`.
 
+The codegen reads documents up to generator contract 18 (`info.x-generator.contract`). A newer
+document still generates, with a warning that the client may miss what the server added.
+
 ## CLI
 
 ```bash
-json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]
+json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]
 ```
 
-| Flag        | Required | Description                                                                           |
-| ----------- | -------- | ------------------------------------------------------------------------------------- |
-| `--input`   | yes      | OpenAPI document source — an http(s) URL or a local file path (JSON or YAML).         |
-| `--output`  | yes      | Output file for the generated client (e.g. `src/api/music.gen.ts`).                   |
-| `--server`  | no       | Server name to target. Metadata-only — the served document is already per-server.     |
-| `--schemas` | no       | JSON Schema source (URL or path) for the validation seam. Omit to skip schema output. |
-| `--check`   | no       | Drift gate — regenerate in memory and exit non-zero if the committed output differs.  |
+| Flag         | Required | Description                                                                           |
+| ------------ | -------- | ------------------------------------------------------------------------------------- |
+| `--input`    | yes      | OpenAPI document source — an http(s) URL or a local file path (JSON or YAML).         |
+| `--output`   | yes      | Output file for the generated client (e.g. `src/api/music.gen.ts`).                   |
+| `--server`   | no       | Server name to target. Metadata-only — the served document is already per-server.     |
+| `--schemas`  | no       | JSON Schema source (URL or path) for the validation seam. Omit to skip schema output. |
+| `--examples` | no       | Also write the operations' worked examples to a sibling `.examples.gen.ts` module.    |
+| `--check`    | no       | Drift gate — regenerate in memory and exit non-zero if the committed output differs.  |
 
 Example — generate against a served API, with the validation schemas:
 
@@ -57,6 +61,8 @@ This writes:
 
 - `src/api/music.gen.ts` — the typed client (descriptor + types + bound `createClient`);
 - `src/api/music.schemas.gen.ts` — the per-type JSON Schema map (only with `--schemas`).
+- `src/api/music.examples.gen.ts` — each operation's worked examples (only with `--examples`, and
+  only when the document declares some).
 
 The schema artifact path is derived from `--output`: a `.gen.ts` suffix becomes `.schemas.gen.ts`,
 a plain `.ts` becomes `.schemas.ts`.
@@ -118,6 +124,13 @@ The output module exports:
 - `Attributes` / `WriteAttributes` — the per-type attribute maps (read vs create/update).
 - Per-type `…Attributes` / `…CreateAttributes` / `…UpdateAttributes` interfaces, enum types
   (e.g. `AlbumStatus`), and action input/output types.
+- `Links` — the typed declared links of each type that declares any.
+- `ErrorCodes` / `ErrorCode` / `ErrorCodeByStatus` / `hasErrorCode` — the server's documented
+  error codes and a type guard bound to them.
+- `pageLimits` / `relatedPageLimits` — the page defaults and page-size caps of each collection and
+  each related collection.
+- `pageKinds` / `relatedPageKinds` — the pagination strategies each collection and related
+  collection offers, the server's default first.
 
 With `--schemas`, the sibling module exports `schemas` — the per-type JSON Schema 2020-12 map.
 
@@ -162,8 +175,10 @@ if (!result.ok) process.exit(1)
 ```
 
 Lower-level building blocks are also exported for advanced use: `readDocument` / `readSchemas`,
-`buildDescriptor`, `emit`, `emitSchemas`, `detectVerbCollisions`, `schemasOutputPath`, and the
-provenance helpers `deriveProvenance` / `provenanceLines` / `hashJson`.
+`buildDescriptor`, `buildExamples`, `emit`, `emitSchemas`, `emitExamples`, `readErrorCatalogue`,
+`emitErrorCodes`, `checkContract`, `detectVerbCollisions`, `schemasOutputPath`,
+`examplesOutputPath`, and the provenance helpers `deriveProvenance` / `provenanceLines` /
+`hashJson`. `generateFiles(config)` generates like `generate` and returns the paths it wrote.
 
 ## License
 

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { r as CodegenConfig } from "./index-C0T-tofN.mjs";
+import { r as CodegenConfig } from "./index-FaJ8Xx6v.mjs";
 
 //#region src/cli.d.ts
 declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]";

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as generateFiles, t as check } from "./src-Qe0YLO-w.mjs";
+import { i as generateFiles, t as check } from "./src-i5j2I9fk.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{index-C0T-tofN.d.mts → index-FaJ8Xx6v.d.mts}

@@ -169,9 +169,9 @@ declare class DescriptorBuilder {
    */
   private relationMutations;
   /**
-   * Attach the per-relation endpoint-exposure signal to a relation descriptor (D24). The bundle
+   * Attach the per-relation endpoint-exposure signal to a relation descriptor. The bundle
    * can suppress a relation's related or relationship endpoint (`withoutRelatedEndpoint()` /
-   * `withoutRelationshipEndpoint()`, ADR 0027), which the OpenAPI reflects by simply omitting that
+   * `withoutRelationshipEndpoint()`), which the OpenAPI reflects by simply omitting that
    * relation's path — but codegen synthesizes generic `{rel}` templates, erasing the per-relation
    * distinction. So mark `related: false` / `relationship: false` when this relation's specific
    * path is absent, and ALWAYS emit an explicit `mutations` object (the verb flags when the
@@ -213,6 +213,12 @@ declare class DescriptorBuilder {
   private documentPrimary;
   /** The wire type of a single `data` schema — a `$ref` to a resource, or an inline `type.const`. */
   private dataConst;
+  /**
+   * The wire types a read's compound document can carry in `included`: the members of its
+   * document's `included.items` union. `undefined` when the document has no `included`, or types
+   * its items only as a generic `{type, id}` object.
+   */
+  private includedTypes;
   /** The `$ref` of the first 2xx JSON:API response body on an operation (the output document). */
   private firstOkJsonApiRef;
   /** Resolve a relationship component's `data` into a {@link RelationDescriptor}. */
@@ -233,6 +239,12 @@ declare class DescriptorBuilder {
   private pivotDescriptor;
   /** Pull the related type from the `$ref` entry of an `allOf` (the pivot shape). */
   private constFromAllOf;
+  /**
+   * The wire types of a union of `$ref`s: a `oneOf` discriminated by `type`, or the `anyOf` an
+   * older document writes. A member whose component carries no `type` const falls back to the
+   * discriminator mapping's key for its `$ref`. `undefined` when the schema is no union.
+   */
+  private unionTypes;
   /** Resolve every `$ref` entry in a list to its wire type. */
   private constsFromRefs;
   private clientId;
@@ -330,7 +342,7 @@ declare function buildExamples(doc: OpenApiDocument, descriptor: ApiDescriptor):
 /** Below this the document predates the structures this codegen reads. */
 declare const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-declare const MAXIMUM_CONTRACT = 18;
+declare const MAXIMUM_CONTRACT = 19;
 /**
  * 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
@@ -397,6 +409,11 @@ declare class Emitter {
   emit(): string;
   private header;
   private imports;
+  /**
+   * The typed `included` of each read: a resource union discriminated by `type` over the types
+   * the document's typed `included` lists, or over every type when the document doesn't type it.
+   */
+  private includedAliases;
   /**
    * The links interface of a type that declares links, e.g. `ImagesLinks`: each declared link an
    * optional member, since the server leaves a link out when its href resolves to `null`. It
@@ -475,11 +492,39 @@ declare class Emitter {
   private atomicConst;
   /**
    * 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.
+   * member declares. 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.
    */
   private pageLimitsConst;
+  /**
+   * The `relatedPageLimits` const: the `pageLimits` shape for each related collection
+   * (`GET /{type}/{id}/{rel}`), keyed by parent type, then by relation name. Relations with no
+   * bounded member, and parents left with none, are left out.
+   */
+  private relatedPageLimitsConst;
+  /**
+   * The `pageKinds` const: per paginated collection, the strategies its `page` parameter offers,
+   * the server's default first.
+   */
+  private pageKindsConst;
+  /**
+   * The `relatedPageKinds` const: `pageKinds` for each related collection, keyed by parent type,
+   * then by relation name.
+   */
+  private relatedPageKindsConst;
+  /**
+   * One line per parent type holding `render`'s value for each relation whose related endpoint
+   * it answers for. Relations it skips, and parents left with none, are left out.
+   */
+  private byRelation;
+  /** The `page` parameter schema of the GET at `path`, if it has one. */
+  private pageSchema;
+  /**
+   * A page schema's bounded members as literal lines at `depth` (two spaces per level): flat for
+   * one strategy, nested under each arm's `kind` for a menu.
+   */
+  private pageLimitLines;
   /** One page schema's members that declare a `default`, `minimum` or `maximum`, as literal lines. */
   private pageMemberLimits;
   /**
@@ -612,7 +657,7 @@ declare function readSchemas(input: string): Promise<SchemaBundle>;
  *
  * The values are the raw, self-contained resource-object JSON Schema documents the bundle
  * serves at `GET /schemas.json` — suitable to hand straight to a validation engine via the
- * opt-in `validate?` seam (ADR 0004). This is a separate file from the client so the main
+ * opt-in `validate?` seam. This is a separate file from the client so the main
  * descriptor/client output is unaffected when `--schemas` is absent.
  *
  * The schemas are emitted as JSON (deterministic, key order preserved) so the artifact is
@@ -697,8 +742,8 @@ declare function examplesOutputPath(output: string): string;
  *
  * When `config.schemas` is set, also read the bundle's JSON Schema bundle and write a
  * separate per-type schema artifact (`<output>.schemas.gen.ts`) beside the client, wiring
- * the opt-in validation seam (ADR 0004). The main client output is unchanged either way.
- * `config.examples` writes the operation examples the same way (ADR 0011).
+ * the opt-in validation seam. The main client output is unchanged either way.
+ * `config.examples` writes the operation examples the same way.
  *
  * `config.server` is metadata-only for now: the served document is already per-server,
  * so the caller selects the server by pointing `input` at the right document.
@@ -718,4 +763,4 @@ declare function generateFiles(config: CodegenConfig): Promise<string[]>;
 declare function check(config: CodegenConfig): Promise<CheckResult>;
 //#endregion
 export { operationExamples as A, PathItemObject as B, VerbCollision as C, MINIMUM_CONTRACT as D, MAXIMUM_CONTRACT as E, InfoObject as F, SecurityRequirement as G, ResponseObject as H, MediaTypeObject as I, SecuritySchemeObject as K, OpenApiDocument as L, buildAtomic as M, buildDescriptor as N, checkContract as O, HttpMethod as P, OperationObject as R, Emitter as S, emit as T, SchemaObject as U, RequestBodyObject as V, SchemaOrBool as W, emitExamples as _, examplesOutputPath as a, emitErrorCodes as b, schemasOutputPath as c, hashJson as d, provenanceLines as f, readSchemas as g, readDocument as h, check as i, DescriptorBuilder as j, buildExamples as k, Provenance as l, SchemaBundle as m, CheckResult as n, generate as o, emitSchemas as p, CodegenConfig as r, generateFiles as s, ArtifactDrift as t, deriveProvenance as u, DocumentedErrorCode as v, detectVerbCollisions as w, readErrorCatalogue as x, ErrorCatalogue as y, ParameterObject as z };
-//# sourceMappingURL=index-C0T-tofN.d.mts.map
+//# sourceMappingURL=index-FaJ8Xx6v.d.mts.map

package/dist/index-FaJ8Xx6v.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-FaJ8Xx6v.d.mts","names":[],"sources":["../src/openapi.ts","../src/build-descriptor.ts","../src/build-examples.ts","../src/contract.ts","../src/emit.ts","../src/error-codes.ts","../src/emit-examples.ts","../src/reader.ts","../src/emit-schemas.ts","../src/provenance.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as operationExamples, B as PathItemObject, C as VerbCollision, D as MINIMUM_CONTRACT, E as MAXIMUM_CONTRACT, F as InfoObject, G as SecurityRequirement, H as ResponseObject, I as MediaTypeObject, K as SecuritySchemeObject, L as OpenApiDocument, M as buildAtomic, N as buildDescriptor, O as checkContract, P as HttpMethod, R as OperationObject, S as Emitter, T as emit, U as SchemaObject, V as RequestBodyObject, W as SchemaOrBool, _ as emitExamples, a as examplesOutputPath, b as emitErrorCodes, c as schemasOutputPath, d as hashJson, f as provenanceLines, g as readSchemas, h as readDocument, i as check, j as DescriptorBuilder, k as buildExamples, l as Provenance, m as SchemaBundle, n as CheckResult, o as generate, p as emitSchemas, r as CodegenConfig, s as generateFiles, t as ArtifactDrift, u as deriveProvenance, v as DocumentedErrorCode, w as detectVerbCollisions, x as readErrorCatalogue, y as ErrorCatalogue, z as ParameterObject } from "./index-C0T-tofN.mjs";
+import { A as operationExamples, B as PathItemObject, C as VerbCollision, D as MINIMUM_CONTRACT, E as MAXIMUM_CONTRACT, F as InfoObject, G as SecurityRequirement, H as ResponseObject, I as MediaTypeObject, K as SecuritySchemeObject, L as OpenApiDocument, M as buildAtomic, N as buildDescriptor, O as checkContract, P as HttpMethod, R as OperationObject, S as Emitter, T as emit, U as SchemaObject, V as RequestBodyObject, W as SchemaOrBool, _ as emitExamples, a as examplesOutputPath, b as emitErrorCodes, c as schemasOutputPath, d as hashJson, f as provenanceLines, g as readSchemas, h as readDocument, i as check, j as DescriptorBuilder, k as buildExamples, l as Provenance, m as SchemaBundle, n as CheckResult, o as generate, p as emitSchemas, r as CodegenConfig, s as generateFiles, t as ArtifactDrift, u as deriveProvenance, v as DocumentedErrorCode, w as detectVerbCollisions, x as readErrorCatalogue, y as ErrorCatalogue, z as ParameterObject } from "./index-FaJ8Xx6v.mjs";
 export { ArtifactDrift, CheckResult, CodegenConfig, DescriptorBuilder, type DocumentedErrorCode, Emitter, type ErrorCatalogue, type HttpMethod, type InfoObject, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, type MediaTypeObject, type OpenApiDocument, type OperationObject, type ParameterObject, type PathItemObject, type Provenance, type RequestBodyObject, type ResponseObject, type SchemaBundle, type SchemaObject, type SchemaOrBool, type SecurityRequirement, type SecuritySchemeObject, type VerbCollision, buildAtomic, buildDescriptor, buildExamples, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitExamples, emitSchemas, examplesOutputPath, generate, generateFiles, hashJson, operationExamples, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { C as DescriptorBuilder, S as operationExamples, T as buildDescriptor, _ as readErrorCatalogue, a as schemasOutputPath, b as checkContract, c as emitSchemas, d as detectVerbCollisions, f as emit, g as emitErrorCodes, h as provenanceLines, i as generateFiles, l as emitExamples, m as hashJson, n as examplesOutputPath, o as readDocument, p as deriveProvenance, r as generate, s as readSchemas, t as check, u as Emitter, v as MAXIMUM_CONTRACT, w as buildAtomic, x as buildExamples, y as MINIMUM_CONTRACT } from "./src-Qe0YLO-w.mjs";
+import { C as DescriptorBuilder, S as operationExamples, T as buildDescriptor, _ as readErrorCatalogue, a as schemasOutputPath, b as checkContract, c as emitSchemas, d as detectVerbCollisions, f as emit, g as emitErrorCodes, h as provenanceLines, i as generateFiles, l as emitExamples, m as hashJson, n as examplesOutputPath, o as readDocument, p as deriveProvenance, r as generate, s as readSchemas, t as check, u as Emitter, v as MAXIMUM_CONTRACT, w as buildAtomic, x as buildExamples, y as MINIMUM_CONTRACT } from "./src-i5j2I9fk.mjs";
 export { DescriptorBuilder, Emitter, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, buildAtomic, buildDescriptor, buildExamples, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitExamples, emitSchemas, examplesOutputPath, generate, generateFiles, hashJson, operationExamples, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/{src-Qe0YLO-w.mjs → src-i5j2I9fk.mjs}

@@ -173,6 +173,8 @@ var DescriptorBuilder = class {
 			if (countable !== void 0) descriptor.countable = countable;
 			const includable = this.includable(collection);
 			if (includable !== void 0) descriptor.includable = includable;
+			const included = this.includedTypes(collection === void 0 ? void 0 : this.operation(collection, "get"));
+			if (included !== void 0) descriptor.included = included;
 			const sortable = this.sortable(collection);
 			if (sortable !== void 0) descriptor.sortable = sortable;
 			const filterable = this.filterable(collection);
@@ -337,9 +339,9 @@ var DescriptorBuilder = class {
 		return mutations;
 	}
 	/**
-	* Attach the per-relation endpoint-exposure signal to a relation descriptor (D24). The bundle
+	* Attach the per-relation endpoint-exposure signal to a relation descriptor. The bundle
 	* can suppress a relation's related or relationship endpoint (`withoutRelatedEndpoint()` /
-	* `withoutRelationshipEndpoint()`, ADR 0027), which the OpenAPI reflects by simply omitting that
+	* `withoutRelationshipEndpoint()`), which the OpenAPI reflects by simply omitting that
 	* relation's path — but codegen synthesizes generic `{rel}` templates, erasing the per-relation
 	* distinction. So mark `related: false` / `relationship: false` when this relation's specific
 	* path is absent, and ALWAYS emit an explicit `mutations` object (the verb flags when the
@@ -359,6 +361,8 @@ var DescriptorBuilder = class {
 			out.relationship = false;
 			out.mutations = {};
 		} else out.mutations = mutations;
+		const included = this.includedTypes(relatedGet);
+		if (included !== void 0) out.included = included;
 		const countable = withCountParam(relatedGet) ?? withCountParam(this.operation(relationshipPath, "get"));
 		if (countable !== void 0) out.countable = countable;
 		if (descriptor.cardinality === "many") {
@@ -532,6 +536,18 @@ var DescriptorBuilder = class {
 		const typeProp = data.properties?.["type"];
 		return isSchema$3(typeProp) && typeof typeProp.const === "string" ? typeProp.const : void 0;
 	}
+	/**
+	* The wire types a read's compound document can carry in `included`: the members of its
+	* document's `included.items` union. `undefined` when the document has no `included`, or types
+	* its items only as a generic `{type, id}` object.
+	*/
+	includedTypes(op) {
+		const ref = op === void 0 ? void 0 : this.firstOkJsonApiRef(op);
+		const included = (ref === void 0 ? void 0 : this.schemas[refName$1(ref) ?? ""])?.properties?.["included"];
+		const items = isSchema$3(included) ? included.items : void 0;
+		const types = items === void 0 || !Array.isArray(items.oneOf) ? void 0 : this.unionTypes(items);
+		return types !== void 0 && types.length > 0 ? types : void 0;
+	}
 	/** The `$ref` of the first 2xx JSON:API response body on an operation (the output document). */
 	firstOkJsonApiRef(op) {
 		for (const [code, response] of Object.entries(op.responses ?? {})) {
@@ -568,15 +584,13 @@ var DescriptorBuilder = class {
 				if (readPivot !== void 0) relation.readPivot = readPivot;
 				return relation;
 			}
-			if (Array.isArray(items.anyOf)) {
-				const types = this.constsFromRefs(items.anyOf);
-				return types.length === 0 ? void 0 : {
-					cardinality: "many",
-					types,
-					polymorphic: true,
-					pivot: false
-				};
-			}
+			const types = this.unionTypes(items);
+			if (types !== void 0) return types.length === 0 ? void 0 : {
+				cardinality: "many",
+				types,
+				polymorphic: true,
+				pivot: false
+			};
 			return;
 		}
 		if (Array.isArray(data.anyOf)) {
@@ -594,9 +608,12 @@ var DescriptorBuilder = class {
 					pivot = true;
 					readPivot = this.pivotDescriptor(pivotNodeFromAllOf(entry.allOf), "read");
 				}
-			} else if (Array.isArray(entry.anyOf)) {
-				types.push(...this.constsFromRefs(entry.anyOf));
-				polymorphic = true;
+			} else {
+				const union = this.unionTypes(entry);
+				if (union !== void 0) {
+					types.push(...union);
+					polymorphic = true;
+				}
 			}
 			if (types.length === 0) return;
 			const relation = polymorphic ? {
@@ -655,6 +672,24 @@ var DescriptorBuilder = class {
 			if (type !== void 0) return type;
 		}
 	}
+	/**
+	* The wire types of a union of `$ref`s: a `oneOf` discriminated by `type`, or the `anyOf` an
+	* older document writes. A member whose component carries no `type` const falls back to the
+	* discriminator mapping's key for its `$ref`. `undefined` when the schema is no union.
+	*/
+	unionTypes(schema) {
+		if (Array.isArray(schema.oneOf)) {
+			const byRef = discriminatorTypesByRef(schema);
+			const types = [];
+			for (const entry of schema.oneOf) {
+				if (typeof entry.$ref !== "string") continue;
+				const type = this.resolveConst(entry.$ref) ?? byRef.get(entry.$ref);
+				if (type !== void 0) types.push(type);
+			}
+			return types;
+		}
+		return Array.isArray(schema.anyOf) ? this.constsFromRefs(schema.anyOf) : void 0;
+	}
 	/** Resolve every `$ref` entry in a list to its wire type. */
 	constsFromRefs(entries) {
 		const types = [];
@@ -846,6 +881,16 @@ function pivotNodeOf(component) {
 	if (Array.isArray(data.items?.allOf)) return pivotNodeFromAllOf(data.items.allOf);
 	for (const entry of data.anyOf ?? []) if (Array.isArray(entry.allOf)) return pivotNodeFromAllOf(entry.allOf);
 }
+/** A `type` discriminator's mapping, inverted to the wire type each `$ref` stands for. */
+function discriminatorTypesByRef(schema) {
+	const byRef = /* @__PURE__ */ new Map();
+	const discriminator = schema["discriminator"];
+	if (typeof discriminator !== "object" || discriminator === null) return byRef;
+	const { propertyName, mapping } = discriminator;
+	if (propertyName !== "type" || typeof mapping !== "object" || mapping === null) return byRef;
+	for (const [type, ref] of Object.entries(mapping)) if (typeof ref === "string") byRef.set(ref, type);
+	return byRef;
+}
 /** Whether a schema admits `null`: a `null` type, or a `null` branch in `anyOf`/`oneOf`. */
 function isNullable(schema) {
 	const type = schema.type;
@@ -1032,7 +1077,7 @@ function buildAtomic(doc) {
 }
 /**
 * Classify a page member set: `number`+`size` = `page`; `offset`+`limit` = `offset`; either
-* cursor bound (`after`/`before`) = `cursor` (link-driven, D44); `number` alone = `fixed` (the
+* cursor bound (`after`/`before`) = `cursor` (link-driven); `number` alone = `fixed` (the
 * server fixes the size); no members = `none`; anything else = `undefined` (unrecognised).
 */
 function kindOfMembers(members) {
@@ -1185,7 +1230,7 @@ function buildExamples(doc, descriptor) {
 /** 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 = 18;
+const MAXIMUM_CONTRACT = 19;
 /**
 * 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
@@ -1195,8 +1240,8 @@ const MAXIMUM_CONTRACT = 18;
 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 18). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 18) return `the document declares contract ${contract} and this codegen reads up to 18. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
+	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 19). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 19) return `the document declares contract ${contract} and this codegen reads up to 19. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
 }
 //#endregion
 //#region src/declared-links.ts
@@ -1559,6 +1604,33 @@ function refName(ref) {
 function isSchema(value) {
 	return typeof value === "object" && value !== null;
 }
+/** A `{ … }` object literal of pre-rendered entry lines, or `{}` when there are none. */
+function objectBody(lines) {
+	return lines.length === 0 ? "{}" : `{\n${lines.join("\n")}\n}`;
+}
+/** The `kind` const a page strategy menu arm is selected by. */
+function armKind(arm) {
+	const kind = arm.properties?.["kind"];
+	return isSchema(kind) && typeof kind.const === "string" ? kind.const : void 0;
+}
+/**
+* The strategies a page schema offers, as a tuple literal, read from the `x-paginator` stamp: a
+* single strategy's name, or a menu's arm kinds with its stamped default first. `undefined` when
+* the schema is absent, unstamped, or a menu whose default is not one of its arms.
+*/
+function pageKinds(schema) {
+	const stamp = schema?.["x-paginator"];
+	if (typeof stamp !== "object" || stamp === null) return;
+	const { strategy, default: fallback } = stamp;
+	let kinds;
+	if (strategy === "multi") {
+		const arms = (schema?.oneOf ?? []).flatMap((arm) => armKind(arm) ?? []);
+		if (typeof fallback !== "string" || !arms.includes(fallback)) return;
+		kinds = [fallback, ...arms.filter((kind) => kind !== fallback)];
+	} else if (typeof strategy === "string") kinds = [strategy];
+	else return;
+	return `[${kinds.map((kind) => stringLiteral(kind)).join(", ")}]`;
+}
 /** PascalCase a JSON:API wire type for use in a TS identifier (e.g. `public-profiles` -> `PublicProfiles`). */
 function pascalCase(value) {
 	return value.split(/[^a-zA-Z0-9]+/).filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
@@ -1912,8 +1984,12 @@ var Emitter = class {
 			this.actionTypesMap(),
 			this.resourceMap(),
 			"export type ResourceMap = typeof resourceMap",
+			this.includedAliases(),
 			this.atomicConst(),
 			this.pageLimitsConst(),
+			this.relatedPageLimitsConst(),
+			this.pageKindsConst(),
+			this.relatedPageKindsConst(),
 			emitErrorCodes(readErrorCatalogue(this.doc)),
 			this.boundFactory()
 		].join("\n\n")}\n`;
@@ -1936,11 +2012,42 @@ var Emitter = class {
 			"  createClient as createClientRuntime,",
 			"  type ErrorCodeGuard,",
 			"  hasErrorCode as hasErrorCodeRuntime,",
+			"  type IncludedResource,",
+			"  type RelatedIncludedResource,",
+			"  type RelationName,",
 			...this.declaredLinks.size > 0 ? ["  type ResourceLinks,"] : [],
+			"  type TypeName,",
+			"  type WithLinks,",
 			"} from '@haddowg/json-api-client'"
 		].join("\n");
 	}
 	/**
+	* The typed `included` of each read: a resource union discriminated by `type` over the types
+	* the document's typed `included` lists, or over every type when the document doesn't type it.
+	*/
+	includedAliases() {
+		return [
+			"/**",
+			" * One resource of a compound document's `included` for a read of type `T`, discriminated by",
+			" * `type` over the types its `include` paths reach.",
+			" */",
+			"export type Included<T extends TypeName<ResourceMap>> = IncludedResource<",
+			"  ResourceMap,",
+			"  WithLinks<Attributes, Links>,",
+			"  T",
+			">",
+			"",
+			"/**",
+			" * One resource of the `included` of relation `R`'s related read on type `T`, discriminated by",
+			" * `type` over the types its `include` paths reach.",
+			" */",
+			"export type RelatedIncluded<",
+			"  T extends TypeName<ResourceMap>,",
+			"  R extends RelationName<ResourceMap, T>,",
+			"> = RelatedIncludedResource<ResourceMap, WithLinks<Attributes, Links>, T, R>"
+		].join("\n");
+	}
+	/**
 	* The links interface of a type that declares links, e.g. `ImagesLinks`: each declared link an
 	* optional member, since the server leaves a link out when its href resolves to `null`. It
 	* extends the loose `ResourceLinks`, so `self` and any link the type doesn't declare stay
@@ -2214,23 +2321,14 @@ var Emitter = class {
 	}
 	/**
 	* 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.
+	* member declares. 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(`    ${propertyKey(kind)}: {\n${members.join("\n")}\n    },`);
-			}
-			else body = this.pageMemberLimits(schema, "    ");
+			const body = this.pageLimitLines(this.pageSchema(this.descriptor[type].paths["fetchMany"]), 2);
 			if (body.length > 0) typeLines.push(`  ${propertyKey(type)}: {\n${body.join("\n")}\n  },`);
 		}
 		return `${[
@@ -2240,7 +2338,96 @@ var Emitter = class {
 			" * 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`;
+		].join("\n")}\nexport const pageLimits = ${objectBody(typeLines)} as const`;
+	}
+	/**
+	* The `relatedPageLimits` const: the `pageLimits` shape for each related collection
+	* (`GET /{type}/{id}/{rel}`), keyed by parent type, then by relation name. Relations with no
+	* bounded member, and parents left with none, are left out.
+	*/
+	relatedPageLimitsConst() {
+		const lines = this.byRelation((path) => {
+			const body = this.pageLimitLines(this.pageSchema(path), 3);
+			return body.length === 0 ? void 0 : `{\n${body.join("\n")}\n    }`;
+		});
+		return `${[
+			"/**",
+			" * The bounds each related collection's `page` parameter declares, keyed by parent type, then by",
+			" * relation name, then as in `pageLimits`: by strategy for a related collection offering several,",
+			" * then by wire key. Relations whose related endpoint declares no bounds are left out.",
+			" */"
+		].join("\n")}\nexport const relatedPageLimits = ${objectBody(lines)} as const`;
+	}
+	/**
+	* The `pageKinds` const: per paginated collection, the strategies its `page` parameter offers,
+	* the server's default first.
+	*/
+	pageKindsConst() {
+		const lines = [];
+		for (const type of Object.keys(this.descriptor)) {
+			const kinds = pageKinds(this.pageSchema(this.descriptor[type].paths["fetchMany"]));
+			if (kinds !== void 0) lines.push(`  ${propertyKey(type)}: ${kinds},`);
+		}
+		return `${[
+			"/**",
+			" * The pagination strategies each collection offers, keyed by type. A single strategy is a",
+			" * one-entry tuple; a menu lists its arms' `kind` values with the one the server uses when the",
+			" * request names none first. Unpaginated collections are left out.",
+			" */"
+		].join("\n")}\nexport const pageKinds = ${objectBody(lines)} as const`;
+	}
+	/**
+	* The `relatedPageKinds` const: `pageKinds` for each related collection, keyed by parent type,
+	* then by relation name.
+	*/
+	relatedPageKindsConst() {
+		const lines = this.byRelation((path) => pageKinds(this.pageSchema(path)));
+		return `${[
+			"/**",
+			" * The pagination strategies each related collection offers, keyed by parent type, then by",
+			" * relation name, in the same form as `pageKinds`. Unpaginated relations are left out.",
+			" */"
+		].join("\n")}\nexport const relatedPageKinds = ${objectBody(lines)} as const`;
+	}
+	/**
+	* One line per parent type holding `render`'s value for each relation whose related endpoint
+	* it answers for. Relations it skips, and parents left with none, are left out.
+	*/
+	byRelation(render) {
+		const lines = [];
+		for (const type of Object.keys(this.descriptor)) {
+			const resource = this.descriptor[type];
+			const template = resource.paths["fetchRelated"];
+			if (template === void 0) continue;
+			const relLines = [];
+			for (const [name, relation] of Object.entries(resource.relations)) {
+				if (relation.related === false) continue;
+				const value = render(template.replace("{rel}", relation.uriField ?? name));
+				if (value !== void 0) relLines.push(`    ${propertyKey(name)}: ${value},`);
+			}
+			if (relLines.length > 0) lines.push(`  ${propertyKey(type)}: {\n${relLines.join("\n")}\n  },`);
+		}
+		return lines;
+	}
+	/** The `page` parameter schema of the GET at `path`, if it has one. */
+	pageSchema(path) {
+		return (path === void 0 ? void 0 : this.doc.paths?.[path]?.get?.parameters)?.find((param) => param.name === "page")?.schema;
+	}
+	/**
+	* A page schema's bounded members as literal lines at `depth` (two spaces per level): flat for
+	* one strategy, nested under each arm's `kind` for a menu.
+	*/
+	pageLimitLines(schema, depth) {
+		if (schema === void 0) return [];
+		const indent = "  ".repeat(depth);
+		if (schema.oneOf === void 0) return this.pageMemberLimits(schema, indent);
+		const lines = [];
+		for (const arm of schema.oneOf) {
+			const kind = armKind(arm);
+			const members = this.pageMemberLimits(arm, `${indent}  `);
+			if (kind !== void 0 && members.length > 0) lines.push(`${indent}${propertyKey(kind)}: {\n${members.join("\n")}\n${indent}},`);
+		}
+		return lines;
 	}
 	/** One page schema's members that declare a `default`, `minimum` or `maximum`, as literal lines. */
 	pageMemberLimits(schema, indent) {
@@ -2501,7 +2688,7 @@ function emitExamples(doc, examples) {
 *
 * The values are the raw, self-contained resource-object JSON Schema documents the bundle
 * serves at `GET /schemas.json` — suitable to hand straight to a validation engine via the
-* opt-in `validate?` seam (ADR 0004). This is a separate file from the client so the main
+* opt-in `validate?` seam. This is a separate file from the client so the main
 * descriptor/client output is unaffected when `--schemas` is absent.
 *
 * The schemas are emitted as JSON (deterministic, key order preserved) so the artifact is
@@ -2572,10 +2759,10 @@ async function readSchemas(input) {
 /**
 * @haddowg/json-api-codegen — reads the bundle's OpenAPI 3.1 document (from a URL or
 * a local file) and emits the runtime descriptor + derived types + a bound
-* `createClient` (ADR 0001). Optionally reads the bundle's JSON Schemas to wire the
+* `createClient`. Optionally reads the bundle's JSON Schemas to wire the
 * opt-in validation seam.
 *
-* The spec is fully self-describing for our needs (see CONTEXT.md): type identity is
+* The spec is fully self-describing for our needs (see docs/concepts.md): type identity is
 * `properties.type.const`; relationships, cardinality and related types come from the
 * relationship components' `data`; allowed `?include` paths are a bounded, pre-expanded
 * enum per endpoint; the create client-id policy is encoded in the create request
@@ -2637,8 +2824,8 @@ async function render(config) {
 *
 * When `config.schemas` is set, also read the bundle's JSON Schema bundle and write a
 * separate per-type schema artifact (`<output>.schemas.gen.ts`) beside the client, wiring
-* the opt-in validation seam (ADR 0004). The main client output is unchanged either way.
-* `config.examples` writes the operation examples the same way (ADR 0011).
+* the opt-in validation seam. The main client output is unchanged either way.
+* `config.examples` writes the operation examples the same way.
 *
 * `config.server` is metadata-only for now: the served document is already per-server,
 * so the caller selects the server by pointing `input` at the right document.
@@ -2688,4 +2875,4 @@ async function check(config) {
 //#endregion
 export { DescriptorBuilder as C, operationExamples as S, buildDescriptor as T, readErrorCatalogue as _, schemasOutputPath as a, checkContract as b, emitSchemas as c, detectVerbCollisions as d, emit as f, emitErrorCodes as g, provenanceLines as h, generateFiles as i, emitExamples as l, hashJson as m, examplesOutputPath as n, readDocument as o, deriveProvenance as p, generate as r, readSchemas as s, check as t, Emitter as u, MAXIMUM_CONTRACT as v, buildAtomic as w, buildExamples as x, MINIMUM_CONTRACT as y };
 
-//# sourceMappingURL=src-Qe0YLO-w.mjs.map
+//# sourceMappingURL=src-i5j2I9fk.mjs.map