@haddowg/json-api-codegen 1.7.1 → 1.8.1

package/dist/cli.d.mts

@@ -1,11 +1,11 @@
-import { r as CodegenConfig } from "./index-CeSU_OuC.mjs";
+import { r as CodegenConfig } from "./index-COQQrn7a.mjs";
 
 //#region src/cli.d.ts
-declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]";
+declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]";
 /**
  * Thin CLI wrapper. Real arg parsing + `japi.config.ts` discovery land with the
  * generator itself; this stub establishes the bin entry and the shape of invocation.
- * `--check` is a boolean flag (drift gate) with no value.
+ * `--check` (drift gate) and `--examples` are boolean flags with no value.
  */
 declare function parseArgs(argv: string[]): Partial<CodegenConfig>;
 declare function run(argv: string[]): Promise<number>;

package/dist/cli.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";;;cAKa,KAAA;AAAb;;;;AAAkB;AAAlB,iBAQgB,SAAA,CAAU,IAAA,aAAiB,OAAO,CAAC,aAAA;AAAA,iBA6B7B,GAAA,CAAI,IAAA,aAAiB,OAAO;;;;;;iBAgClC,OAAA,CAAQ,SAAA,UAAmB,KAAyB"}
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";;;cAKa,KAAA;AAAb;;;;AAAkB;AAAlB,iBAQgB,SAAA,CAAU,IAAA,aAAiB,OAAO,CAAC,aAAA;AAAA,iBAiC7B,GAAA,CAAI,IAAA,aAAiB,OAAO;;;;;;iBA+BlC,OAAA,CAAQ,SAAA,UAAmB,KAAyB"}

package/dist/cli.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { n as generate, r as schemasOutputPath, t as check } from "./src-DhZyiWge.mjs";
+import { i as generateFiles, t as check } from "./src-AWTGjMiX.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts
-const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]";
+const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]";
 /**
 * Thin CLI wrapper. Real arg parsing + `japi.config.ts` discovery land with the
 * generator itself; this stub establishes the bin entry and the shape of invocation.
-* `--check` is a boolean flag (drift gate) with no value.
+* `--check` (drift gate) and `--examples` are boolean flags with no value.
 */
 function parseArgs(argv) {
 	const config = {};
@@ -17,6 +17,10 @@ function parseArgs(argv) {
 			config.check = true;
 			continue;
 		}
+		if (arg === "--examples") {
+			config.examples = true;
+			continue;
+		}
 		const next = argv[i + 1];
 		if (next === void 0) continue;
 		if (arg === "--input") {
@@ -50,9 +54,8 @@ async function run(argv) {
 		}
 		return 0;
 	}
-	await generate(config);
-	console.error(`wrote ${config.output}`);
-	if (config.schemas !== void 0) console.error(`wrote ${schemasOutputPath(config.output)}`);
+	const written = await generateFiles(config);
+	for (const path of written) console.error(`wrote ${path}`);
 	return 0;
 }
 /**

package/dist/cli.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { realpathSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\nimport { check, generate, schemasOutputPath, type CodegenConfig } from './index'\n\nexport const USAGE =\n  'Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]'\n\n/**\n * Thin CLI wrapper. Real arg parsing + `japi.config.ts` discovery land with the\n * generator itself; this stub establishes the bin entry and the shape of invocation.\n * `--check` is a boolean flag (drift gate) with no value.\n */\nexport function parseArgs(argv: string[]): Partial<CodegenConfig> {\n  const config: Partial<CodegenConfig> = {}\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i]\n    if (arg === '--check') {\n      config.check = true\n      continue\n    }\n    const next = argv[i + 1]\n    if (next === undefined) {\n      continue\n    }\n    if (arg === '--input') {\n      config.input = next\n      i++\n    } else if (arg === '--output') {\n      config.output = next\n      i++\n    } else if (arg === '--server') {\n      config.server = next\n      i++\n    } else if (arg === '--schemas') {\n      config.schemas = next\n      i++\n    }\n  }\n  return config\n}\n\nexport async function run(argv: string[]): Promise<number> {\n  const config = parseArgs(argv)\n  if (!config.input || !config.output) {\n    console.error(USAGE)\n    return 1\n  }\n  if (config.check) {\n    const result = await check(config as CodegenConfig)\n    for (const { path, upToDate } of result.artifacts) {\n      console.error(`${upToDate ? 'ok  ' : 'DRIFT'} ${path}`)\n    }\n    if (!result.ok) {\n      console.error(\n        'Generated client is out of date with the source spec. Regenerate (drop --check) and commit the result.',\n      )\n      return 1\n    }\n    return 0\n  }\n  await generate(config as CodegenConfig)\n  console.error(`wrote ${config.output}`)\n  if (config.schemas !== undefined) {\n    console.error(`wrote ${schemasOutputPath(config.output)}`)\n  }\n  return 0\n}\n\n/**\n * Whether the module at `moduleUrl` is the script node was asked to run (`argv1`). Compares real\n * paths, because a package manager installs the bin as a symlink (`node_modules/.bin/...`) and\n * node reports the symlink in `process.argv[1]` but the resolved file in `import.meta.url`.\n */\nexport function isEntry(moduleUrl: string, argv1: string | undefined): boolean {\n  if (argv1 === undefined) {\n    return false\n  }\n  try {\n    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argv1)\n  } catch {\n    return false\n  }\n}\n\nasync function main(): Promise<void> {\n  process.exitCode = await run(process.argv.slice(2))\n}\n\n// Only run when invoked as the bin, not when imported (e.g. by tests).\nif (isEntry(import.meta.url, process.argv[1])) {\n  main().catch((error: unknown) => {\n    console.error(error instanceof Error ? error.message : error)\n    process.exitCode = 1\n  })\n}\n"],"mappings":";;;;;AAKA,MAAa,QACX;;;;;;AAOF,SAAgB,UAAU,MAAwC;CAChE,MAAM,SAAiC,CAAC;CACxC,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,MAAM,KAAK;EACjB,IAAI,QAAQ,WAAW;GACrB,OAAO,QAAQ;GACf;EACF;EACA,MAAM,OAAO,KAAK,IAAI;EACtB,IAAI,SAAS,KAAA,GACX;EAEF,IAAI,QAAQ,WAAW;GACrB,OAAO,QAAQ;GACf;EACF,OAAO,IAAI,QAAQ,YAAY;GAC7B,OAAO,SAAS;GAChB;EACF,OAAO,IAAI,QAAQ,YAAY;GAC7B,OAAO,SAAS;GAChB;EACF,OAAO,IAAI,QAAQ,aAAa;GAC9B,OAAO,UAAU;GACjB;EACF;CACF;CACA,OAAO;AACT;AAEA,eAAsB,IAAI,MAAiC;CACzD,MAAM,SAAS,UAAU,IAAI;CAC7B,IAAI,CAAC,OAAO,SAAS,CAAC,OAAO,QAAQ;EACnC,QAAQ,MAAM,KAAK;EACnB,OAAO;CACT;CACA,IAAI,OAAO,OAAO;EAChB,MAAM,SAAS,MAAM,MAAM,MAAuB;EAClD,KAAK,MAAM,EAAE,MAAM,cAAc,OAAO,WACtC,QAAQ,MAAM,GAAG,WAAW,SAAS,QAAQ,GAAG,MAAM;EAExD,IAAI,CAAC,OAAO,IAAI;GACd,QAAQ,MACN,wGACF;GACA,OAAO;EACT;EACA,OAAO;CACT;CACA,MAAM,SAAS,MAAuB;CACtC,QAAQ,MAAM,SAAS,OAAO,QAAQ;CACtC,IAAI,OAAO,YAAY,KAAA,GACrB,QAAQ,MAAM,SAAS,kBAAkB,OAAO,MAAM,GAAG;CAE3D,OAAO;AACT;;;;;;AAOA,SAAgB,QAAQ,WAAmB,OAAoC;CAC7E,IAAI,UAAU,KAAA,GACZ,OAAO;CAET,IAAI;EACF,OAAO,aAAa,cAAc,SAAS,CAAC,MAAM,aAAa,KAAK;CACtE,QAAQ;EACN,OAAO;CACT;AACF;AAEA,eAAe,OAAsB;CACnC,QAAQ,WAAW,MAAM,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC;AACpD;AAGA,IAAI,QAAQ,OAAO,KAAK,KAAK,QAAQ,KAAK,EAAE,GAC1C,KAAK,CAAC,CAAC,OAAO,UAAmB;CAC/B,QAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,KAAK;CAC5D,QAAQ,WAAW;AACrB,CAAC"}
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { realpathSync } from 'node:fs'\nimport { fileURLToPath } from 'node:url'\nimport { check, generateFiles, type CodegenConfig } from './index'\n\nexport const USAGE =\n  'Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--examples] [--check]'\n\n/**\n * Thin CLI wrapper. Real arg parsing + `japi.config.ts` discovery land with the\n * generator itself; this stub establishes the bin entry and the shape of invocation.\n * `--check` (drift gate) and `--examples` are boolean flags with no value.\n */\nexport function parseArgs(argv: string[]): Partial<CodegenConfig> {\n  const config: Partial<CodegenConfig> = {}\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i]\n    if (arg === '--check') {\n      config.check = true\n      continue\n    }\n    if (arg === '--examples') {\n      config.examples = true\n      continue\n    }\n    const next = argv[i + 1]\n    if (next === undefined) {\n      continue\n    }\n    if (arg === '--input') {\n      config.input = next\n      i++\n    } else if (arg === '--output') {\n      config.output = next\n      i++\n    } else if (arg === '--server') {\n      config.server = next\n      i++\n    } else if (arg === '--schemas') {\n      config.schemas = next\n      i++\n    }\n  }\n  return config\n}\n\nexport async function run(argv: string[]): Promise<number> {\n  const config = parseArgs(argv)\n  if (!config.input || !config.output) {\n    console.error(USAGE)\n    return 1\n  }\n  if (config.check) {\n    const result = await check(config as CodegenConfig)\n    for (const { path, upToDate } of result.artifacts) {\n      console.error(`${upToDate ? 'ok  ' : 'DRIFT'} ${path}`)\n    }\n    if (!result.ok) {\n      console.error(\n        'Generated client is out of date with the source spec. Regenerate (drop --check) and commit the result.',\n      )\n      return 1\n    }\n    return 0\n  }\n  const written = await generateFiles(config as CodegenConfig)\n  for (const path of written) {\n    console.error(`wrote ${path}`)\n  }\n  return 0\n}\n\n/**\n * Whether the module at `moduleUrl` is the script node was asked to run (`argv1`). Compares real\n * paths, because a package manager installs the bin as a symlink (`node_modules/.bin/...`) and\n * node reports the symlink in `process.argv[1]` but the resolved file in `import.meta.url`.\n */\nexport function isEntry(moduleUrl: string, argv1: string | undefined): boolean {\n  if (argv1 === undefined) {\n    return false\n  }\n  try {\n    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argv1)\n  } catch {\n    return false\n  }\n}\n\nasync function main(): Promise<void> {\n  process.exitCode = await run(process.argv.slice(2))\n}\n\n// Only run when invoked as the bin, not when imported (e.g. by tests).\nif (isEntry(import.meta.url, process.argv[1])) {\n  main().catch((error: unknown) => {\n    console.error(error instanceof Error ? error.message : error)\n    process.exitCode = 1\n  })\n}\n"],"mappings":";;;;;AAKA,MAAa,QACX;;;;;;AAOF,SAAgB,UAAU,MAAwC;CAChE,MAAM,SAAiC,CAAC;CACxC,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;EACpC,MAAM,MAAM,KAAK;EACjB,IAAI,QAAQ,WAAW;GACrB,OAAO,QAAQ;GACf;EACF;EACA,IAAI,QAAQ,cAAc;GACxB,OAAO,WAAW;GAClB;EACF;EACA,MAAM,OAAO,KAAK,IAAI;EACtB,IAAI,SAAS,KAAA,GACX;EAEF,IAAI,QAAQ,WAAW;GACrB,OAAO,QAAQ;GACf;EACF,OAAO,IAAI,QAAQ,YAAY;GAC7B,OAAO,SAAS;GAChB;EACF,OAAO,IAAI,QAAQ,YAAY;GAC7B,OAAO,SAAS;GAChB;EACF,OAAO,IAAI,QAAQ,aAAa;GAC9B,OAAO,UAAU;GACjB;EACF;CACF;CACA,OAAO;AACT;AAEA,eAAsB,IAAI,MAAiC;CACzD,MAAM,SAAS,UAAU,IAAI;CAC7B,IAAI,CAAC,OAAO,SAAS,CAAC,OAAO,QAAQ;EACnC,QAAQ,MAAM,KAAK;EACnB,OAAO;CACT;CACA,IAAI,OAAO,OAAO;EAChB,MAAM,SAAS,MAAM,MAAM,MAAuB;EAClD,KAAK,MAAM,EAAE,MAAM,cAAc,OAAO,WACtC,QAAQ,MAAM,GAAG,WAAW,SAAS,QAAQ,GAAG,MAAM;EAExD,IAAI,CAAC,OAAO,IAAI;GACd,QAAQ,MACN,wGACF;GACA,OAAO;EACT;EACA,OAAO;CACT;CACA,MAAM,UAAU,MAAM,cAAc,MAAuB;CAC3D,KAAK,MAAM,QAAQ,SACjB,QAAQ,MAAM,SAAS,MAAM;CAE/B,OAAO;AACT;;;;;;AAOA,SAAgB,QAAQ,WAAmB,OAAoC;CAC7E,IAAI,UAAU,KAAA,GACZ,OAAO;CAET,IAAI;EACF,OAAO,aAAa,cAAc,SAAS,CAAC,MAAM,aAAa,KAAK;CACtE,QAAQ;EACN,OAAO;CACT;AACF;AAEA,eAAe,OAAsB;CACnC,QAAQ,WAAW,MAAM,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC;AACpD;AAGA,IAAI,QAAQ,OAAO,KAAK,KAAK,QAAQ,KAAK,EAAE,GAC1C,KAAK,CAAC,CAAC,OAAO,UAAmB;CAC/B,QAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,KAAK;CAC5D,QAAQ,WAAW;AACrB,CAAC"}

package/dist/{index-CeSU_OuC.d.mts → index-COQQrn7a.d.mts}

@@ -1,4 +1,4 @@
-import { ApiDescriptor, AtomicDescriptor } from "@haddowg/json-api-client";
+import { ApiDescriptor, ApiExamples, AtomicDescriptor, OperationExamples } from "@haddowg/json-api-client";
 
 //#region src/openapi.d.ts
 /**
@@ -29,6 +29,8 @@ interface SchemaObject {
 type SchemaOrBool = SchemaObject | boolean;
 interface MediaTypeObject {
   schema?: SchemaObject;
+  /** A whole worked body for this media type (generator contract 12 on an operation). */
+  example?: unknown;
 }
 interface RequestBodyObject {
   content?: Record<string, MediaTypeObject>;
@@ -273,11 +275,27 @@ declare function buildDescriptor(doc: OpenApiDocument): ApiDescriptor;
 /** Detect the server-level Atomic Operations capability (`null` when none). */
 declare function buildAtomic(doc: OpenApiDocument): AtomicDescriptor | null;
 //#endregion
+//#region src/build-examples.d.ts
+/**
+ * The request example and the `2xx` response examples of one operation, or `undefined` when it
+ * declares none. Error responses are shared components rather than per-operation, so they are
+ * left out.
+ */
+declare function operationExamples(op: OperationObject | undefined): OperationExamples | undefined;
+/**
+ * Collect the worked examples a contract 12 document puts on each operation, per type. A type's
+ * operations are found by the `operationId`s the projector stamps (`create.albums`,
+ * `fetchRelated.albums.tracks`) and keyed by that id without the type; its actions are keyed by
+ * name, as the descriptor keys them. Types, operations and parts with no example are left out, so
+ * a document without examples gives `{}`.
+ */
+declare function buildExamples(doc: OpenApiDocument, descriptor: ApiDescriptor): ApiExamples;
+//#endregion
 //#region src/contract.d.ts
 /** 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 = 11;
+declare const MAXIMUM_CONTRACT = 13;
 /**
  * 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
@@ -332,8 +350,6 @@ declare class Emitter {
   private readonly provenance;
   private readonly doc;
   constructor(source: OpenApiDocument, descriptor: ApiDescriptor, atomic: AtomicDescriptor | null);
-  /** The operation an action is invoked over: its declared method, else `POST`. */
-  private actionOperation;
   /**
    * The alias an enum component is emitted under: its own name when that's a usable type name,
    * else one derived from it (with a warning), kept clear of every other name in the module.
@@ -496,6 +512,21 @@ declare function readErrorCatalogue(doc: OpenApiDocument): ErrorCatalogue;
  */
 declare function emitErrorCodes(catalogue: ErrorCatalogue): string;
 //#endregion
+//#region src/emit-examples.d.ts
+/**
+ * Emit the operation examples as a standalone generated artifact:
+ *
+ * ```ts
+ * export const examples: ApiExamples = { <type>: { operations: { … }, actions: { … } }, … }
+ * ```
+ *
+ * It sits beside the client rather than in it because the examples outweigh the rest of the
+ * client several times over and only a few consumers, such as a tool describing each operation,
+ * read them. The const is annotated rather than `as const`, so a large document costs the type
+ * checker nothing beyond the assignability check.
+ */
+declare function emitExamples(doc: OpenApiDocument, examples: ApiExamples): string;
+//#endregion
 //#region src/reader.d.ts
 /** A self-contained JSON Schema document, keyed by JSON:API type, as served at `GET /schemas.json`. */
 type SchemaBundle = Record<string, SchemaObject>;
@@ -569,6 +600,11 @@ interface CodegenConfig {
   server?: string;
   /** JSON Schema source for the validation seam (URL or path). Off when omitted. */
   schemas?: string;
+  /**
+   * Also write the operation examples the document declares (generator contract 12) to a sibling
+   * module, `<output>.examples.gen.ts`. Nothing is written when the document has none.
+   */
+  examples?: boolean;
   /**
    * Drift-check mode: regenerate in-memory and compare against the committed `output`
    * (and its schema artifact when `schemas` is set) instead of writing. Nothing is
@@ -593,6 +629,8 @@ interface CheckResult {
  * (any `.gen.ts`/`.ts` suffix is preserved; a suffix-less path just gains `.schemas`).
  */
 declare function schemasOutputPath(output: string): string;
+/** The examples-artifact path beside a client output path, named as {@link schemasOutputPath} names its. */
+declare function examplesOutputPath(output: string): string;
 /**
  * Read the OpenAPI document, build the runtime descriptor, emit the generated client
  * module and write it to `config.output` (creating parent directories as needed).
@@ -600,6 +638,7 @@ declare function schemasOutputPath(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).
  *
  * `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.
@@ -608,6 +647,8 @@ declare function schemasOutputPath(output: string): string;
  * call {@link check} instead for the drift-gate result.
  */
 declare function generate(config: CodegenConfig): Promise<string>;
+/** {@link generate}, returning the path of every artifact written, the client's first. */
+declare function generateFiles(config: CodegenConfig): Promise<string[]>;
 /**
  * Drift gate: regenerate every artifact in memory and compare it byte-for-byte against the
  * committed file on disk, WITHOUT writing anything. A missing committed file counts as drift
@@ -616,5 +657,5 @@ declare function generate(config: CodegenConfig): Promise<string>;
  */
 declare function check(config: CodegenConfig): Promise<CheckResult>;
 //#endregion
-export { InfoObject as A, MAXIMUM_CONTRACT as C, buildAtomic as D, DescriptorBuilder as E, PathItemObject as F, RequestBodyObject as I, ResponseObject as L, OpenApiDocument as M, OperationObject as N, buildDescriptor as O, ParameterObject as P, SchemaObject as R, emit as S, checkContract as T, emitErrorCodes as _, generate as a, VerbCollision as b, deriveProvenance as c, emitSchemas as d, SchemaBundle as f, ErrorCatalogue as g, DocumentedErrorCode as h, check as i, MediaTypeObject as j, HttpMethod as k, hashJson as l, readSchemas as m, CheckResult as n, schemasOutputPath as o, readDocument as p, CodegenConfig as r, Provenance as s, ArtifactDrift as t, provenanceLines as u, readErrorCatalogue as v, MINIMUM_CONTRACT as w, detectVerbCollisions as x, Emitter as y, SchemaOrBool as z };
-//# sourceMappingURL=index-CeSU_OuC.d.mts.map
+export { operationExamples as A, PathItemObject as B, VerbCollision as C, MINIMUM_CONTRACT as D, MAXIMUM_CONTRACT as E, InfoObject as F, ResponseObject as H, MediaTypeObject as I, 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-COQQrn7a.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-COQQrn7a.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 InfoObject, C as MAXIMUM_CONTRACT, D as buildAtomic, E as DescriptorBuilder, F as PathItemObject, I as RequestBodyObject, L as ResponseObject, M as OpenApiDocument, N as OperationObject, O as buildDescriptor, P as ParameterObject, R as SchemaObject, S as emit, T as checkContract, _ as emitErrorCodes, a as generate, b as VerbCollision, c as deriveProvenance, d as emitSchemas, f as SchemaBundle, g as ErrorCatalogue, h as DocumentedErrorCode, i as check, j as MediaTypeObject, k as HttpMethod, l as hashJson, m as readSchemas, n as CheckResult, o as schemasOutputPath, p as readDocument, r as CodegenConfig, s as Provenance, t as ArtifactDrift, u as provenanceLines, v as readErrorCatalogue, w as MINIMUM_CONTRACT, x as detectVerbCollisions, y as Emitter, z as SchemaOrBool } from "./index-CeSU_OuC.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 VerbCollision, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };
+import { A as operationExamples, B as PathItemObject, C as VerbCollision, D as MINIMUM_CONTRACT, E as MAXIMUM_CONTRACT, F as InfoObject, H as ResponseObject, I as MediaTypeObject, 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-COQQrn7a.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 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 { _ as checkContract, a as readSchemas, b as buildDescriptor, c as detectVerbCollisions, d as hashJson, f as provenanceLines, g as MINIMUM_CONTRACT, h as MAXIMUM_CONTRACT, i as readDocument, l as emit, m as readErrorCatalogue, n as generate, o as emitSchemas, p as emitErrorCodes, r as schemasOutputPath, s as Emitter, t as check, u as deriveProvenance, v as DescriptorBuilder, y as buildAtomic } from "./src-DhZyiWge.mjs";
-export { DescriptorBuilder, Emitter, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };
+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-AWTGjMiX.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-DhZyiWge.mjs → src-AWTGjMiX.mjs}

@@ -962,11 +962,89 @@ function stampedMenu(schema, stamp, warn) {
 	};
 }
 //#endregion
+//#region src/build-examples.ts
+/** Operations that belong to no single type, so they have no place under one. */
+const SERVER_OPERATIONS = /* @__PURE__ */ new Set(["action", "atomic"]);
+/** The `example` of each media type that declares one, in the document's order. */
+function mediaExamples(content) {
+	const out = {};
+	for (const [mediaType, media] of Object.entries(content ?? {})) if (media !== null && typeof media === "object" && "example" in media) out[mediaType] = media.example;
+	return Object.keys(out).length === 0 ? void 0 : out;
+}
+/**
+* The request example and the `2xx` response examples of one operation, or `undefined` when it
+* declares none. Error responses are shared components rather than per-operation, so they are
+* left out.
+*/
+function operationExamples(op) {
+	if (op === void 0) return;
+	const out = {};
+	const request = mediaExamples(op.requestBody?.content);
+	if (request !== void 0) out.request = request;
+	for (const [status, response] of Object.entries(op.responses ?? {})) {
+		const examples = status.startsWith("2") ? mediaExamples(response.content) : void 0;
+		if (examples !== void 0) {
+			out.responses ??= {};
+			out.responses[status] = examples;
+		}
+	}
+	return out.request === void 0 && out.responses === void 0 ? void 0 : out;
+}
+/** The operation an action is invoked over: its declared method, else `POST`. */
+function actionOperation(doc, action) {
+	const method = (action.method ?? "POST").toLowerCase();
+	return doc.paths?.[action.path]?.[method];
+}
+function sorted(record) {
+	const out = {};
+	for (const key of Object.keys(record).sort()) out[key] = record[key];
+	return out;
+}
+/**
+* Collect the worked examples a contract 12 document puts on each operation, per type. A type's
+* operations are found by the `operationId`s the projector stamps (`create.albums`,
+* `fetchRelated.albums.tracks`) and keyed by that id without the type; its actions are keyed by
+* name, as the descriptor keys them. Types, operations and parts with no example are left out, so
+* a document without examples gives `{}`.
+*/
+function buildExamples(doc, descriptor) {
+	const operations = /* @__PURE__ */ new Map();
+	for (const item of Object.values(doc.paths ?? {})) for (const op of Object.values(item)) {
+		const id = op?.operationId;
+		if (typeof id !== "string") continue;
+		const [prefix, type, ...relation] = id.split(".");
+		if (prefix === void 0 || type === void 0 || SERVER_OPERATIONS.has(prefix) || !Object.hasOwn(descriptor, type)) continue;
+		const examples = operationExamples(op);
+		if (examples === void 0) continue;
+		let byName = operations.get(type);
+		if (byName === void 0) {
+			byName = {};
+			operations.set(type, byName);
+		}
+		byName[[prefix, ...relation].join(".")] = examples;
+	}
+	const out = {};
+	for (const [type, resource] of Object.entries(descriptor)) {
+		const entry = {};
+		const byName = operations.get(type);
+		if (byName !== void 0) entry.operations = sorted(byName);
+		for (const [name, action] of Object.entries(resource.actions ?? {})) {
+			const examples = operationExamples(actionOperation(doc, action));
+			if (examples !== void 0) {
+				entry.actions ??= {};
+				entry.actions[name] = examples;
+			}
+		}
+		if (entry.operations !== void 0 || entry.actions !== void 0) out[type] = entry;
+	}
+	return out;
+}
+//#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 = 11;
+const MAXIMUM_CONTRACT = 13;
 /**
 * 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
@@ -976,8 +1054,8 @@ const MAXIMUM_CONTRACT = 11;
 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 11). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 11) return `the document declares contract ${contract} and this codegen reads up to 11. 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 13). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 13) return `the document declares contract ${contract} and this codegen reads up to 13. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
 }
 //#endregion
 //#region src/source.ts
@@ -992,6 +1070,13 @@ const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/;
 function stringLiteral(value) {
 	return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
+/**
+* A JSON value as a TS literal, indented two spaces with the value's key order kept. A
+* `__proto__` key becomes computed so it stays an own key, and U+2028/U+2029 are escaped.
+*/
+function jsonLiteral(value) {
+	return JSON.stringify(value, null, 2).replace(/^(\s*)"__proto__":/gm, "$1[\"__proto__\"]:").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
 /** True when a string is a bare identifier. */
 function isIdentifier(value) {
 	return IDENTIFIER.test(value);
@@ -1404,6 +1489,47 @@ function actionDoc(name, op) {
 	if (description && !generated.test(description)) parts.push(description);
 	return parts.length === 0 ? void 0 : parts.join("\n\n");
 }
+/** Whether a media type carries JSON: JSON:API, `application/json` or a `+json` suffix. */
+function isJsonMedia(mediaType) {
+	const essence = mediaType.split(";")[0].trim().toLowerCase();
+	return essence === "application/json" || essence.endsWith("+json");
+}
+/** The media type to show: JSON:API when it has an example, else the first that does. */
+function shownMedia(examples) {
+	return JSON_API_MEDIA_TYPE in examples ? JSON_API_MEDIA_TYPE : Object.keys(examples)[0];
+}
+/**
+* An `@example` for an action: its request body when it declares one, else its first success
+* response, as a fenced block of pretty-printed JSON (a text body as is). A body over
+* {@link EXAMPLE_DOC_MAX_LINES} lines is named but not shown. The fence is longer than any run of
+* backticks in the body, so the body can't close it.
+*/
+function exampleDoc(op) {
+	const examples = operationExamples(op);
+	if (examples === void 0) return;
+	let label;
+	let media;
+	if (examples.request !== void 0) {
+		label = "Request body";
+		media = examples.request;
+	} else {
+		const first = Object.entries(examples.responses ?? {})[0];
+		if (first === void 0) return;
+		label = `Response \`${first[0]}\``;
+		media = first[1];
+	}
+	const mediaType = shownMedia(media);
+	if (mediaType === void 0) return;
+	if (mediaType !== JSON_API_MEDIA_TYPE) label += ` as \`${mediaType}\``;
+	const value = media[mediaType];
+	const raw = typeof value === "string" && !isJsonMedia(mediaType);
+	const text = raw ? value.replace(/(?:\r\n|\r|\n)+$/, "") : JSON.stringify(value, null, 2);
+	const lines = text.split(/\r\n|\r|\n/).length;
+	if (lines > 80) return `@example ${label}\nThe example is ${lines} lines long, too long to show here.`;
+	const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+	const fence = "`".repeat(Math.max(3, longest + 1));
+	return `@example ${label}\n${fence}${raw ? "" : "json"}\n${text}\n${fence}`;
+}
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -1463,16 +1589,13 @@ var Emitter = class {
 				for (const { mediaType } of action.inputMedia ?? []) this.takenNames.add(`${stem}${pascalCase(name)}${pascalCase(mediaType)}Input`);
 				const single = action.contentType;
 				if (single !== void 0 && (single.startsWith("multipart/") || single === "application/x-www-form-urlencoded")) this.takenNames.add(`${stem}${pascalCase(name)}${pascalCase(single)}Input`);
-				const doc = actionDoc(name, this.actionOperation(action));
+				const op = actionOperation(this.doc, action);
+				const parts = [actionDoc(name, op), exampleDoc(op)].filter((part) => part !== void 0);
+				const doc = parts.length === 0 ? void 0 : parts.join("\n\n");
 				if (doc !== void 0) this.literalDocs.set(`${type}/actions/${name}`, doc);
 			}
 		}
 	}
-	/** The operation an action is invoked over: its declared method, else `POST`. */
-	actionOperation(action) {
-		const method = (action.method ?? "POST").toLowerCase();
-		return this.doc.paths?.[action.path]?.[method];
-	}
 	/**
 	* The alias an enum component is emitted under: its own name when that's a usable type name,
 	* else one derived from it (with a warning), kept clear of every other name in the module.
@@ -1605,7 +1728,7 @@ var Emitter = class {
 					out.push(`export type ${member}Output = ${outputType}`);
 					names.output = `${member}Output`;
 				}
-				const op = this.actionOperation(action);
+				const op = actionOperation(this.doc, action);
 				for (const { mediaType, kind } of action.rawOutput ?? []) if (kind === "json") {
 					const schema = firstSuccessSchema(op, mediaType);
 					names.responses ??= /* @__PURE__ */ new Map();
@@ -2016,6 +2139,34 @@ function emit(doc, descriptor, atomic = buildAtomic(doc)) {
 	return new Emitter(doc, descriptor, atomic).emit();
 }
 //#endregion
+//#region src/emit-examples.ts
+/**
+* Emit the operation examples as a standalone generated artifact:
+*
+* ```ts
+* export const examples: ApiExamples = { <type>: { operations: { … }, actions: { … } }, … }
+* ```
+*
+* It sits beside the client rather than in it because the examples outweigh the rest of the
+* client several times over and only a few consumers, such as a tool describing each operation,
+* read them. The const is annotated rather than `as const`, so a large document costs the type
+* checker nothing beyond the assignability check.
+*/
+function emitExamples(doc, examples) {
+	return `${[
+		[
+			"/**",
+			" * AUTO-GENERATED by @haddowg/json-api-codegen — do not edit by hand.",
+			" * Worked examples of each operation, as the source OpenAPI document declares them.",
+			" *",
+			...provenanceLines(deriveProvenance(doc)),
+			" */"
+		].join("\n"),
+		"import type { ApiExamples } from '@haddowg/json-api-client'",
+		`export const examples: ApiExamples = ${jsonLiteral(examples)}`
+	].join("\n\n")}\n`;
+}
+//#endregion
 //#region src/emit-schemas.ts
 /**
 * Emit the per-type JSON Schema map as a standalone generated artifact:
@@ -2046,7 +2197,7 @@ function header(bundle) {
 	].join("\n");
 }
 function body(bundle) {
-	return `export const schemas = ${JSON.stringify(bundle, null, 2).replace(/^(\s*)"__proto__":/gm, "$1[\"__proto__\"]:").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029")} as const`;
+	return `export const schemas = ${jsonLiteral(bundle)} as const`;
 }
 //#endregion
 //#region src/reader.ts
@@ -2115,9 +2266,16 @@ function schemasOutputPath(output) {
 	if (output.endsWith(".ts")) return `${output.slice(0, -3)}.schemas.ts`;
 	return `${output}.schemas`;
 }
+/** The examples-artifact path beside a client output path, named as {@link schemasOutputPath} names its. */
+function examplesOutputPath(output) {
+	if (output.endsWith(".gen.ts")) return `${output.slice(0, -7)}.examples.gen.ts`;
+	if (output.endsWith(".ts")) return `${output.slice(0, -3)}.examples.ts`;
+	return `${output}.examples`;
+}
 /**
 * Read the source spec(s), build the descriptor and render every generated artifact in
-* memory (the client source first, then the schema artifact when `config.schemas` is set)
+* memory (the client source first, then the schema artifact when `config.schemas` is set and
+* the examples artifact when `config.examples` is)
 * — the shared core of {@link generate} (which writes them) and {@link check} (which
 * compares them). Verb-collision warnings are emitted here so both paths surface them.
 */
@@ -2139,6 +2297,14 @@ async function render(config) {
 			content: emitSchemas(bundle)
 		});
 	}
+	if (config.examples === true) {
+		const examples = buildExamples(doc, descriptor);
+		if (Object.keys(examples).length > 0) artifacts.push({
+			path: examplesOutputPath(config.output),
+			content: emitExamples(doc, examples)
+		});
+		else console.warn(`[json-api-codegen] ${config.input} declares no operation examples; no examples module was written.`);
+	}
 	return artifacts;
 }
 /**
@@ -2148,6 +2314,7 @@ 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).
 *
 * `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.
@@ -2156,10 +2323,17 @@ async function render(config) {
 * call {@link check} instead for the drift-gate result.
 */
 async function generate(config) {
+	return (await write(config))[0].content;
+}
+/** {@link generate}, returning the path of every artifact written, the client's first. */
+async function generateFiles(config) {
+	return (await write(config)).map(({ path }) => path);
+}
+async function write(config) {
 	const artifacts = await render(config);
 	await mkdir(dirname(config.output), { recursive: true });
 	for (const { path, content } of artifacts) await writeFile(path, content, "utf8");
-	return artifacts[0].content;
+	return artifacts;
 }
 /**
 * Drift gate: regenerate every artifact in memory and compare it byte-for-byte against the
@@ -2188,6 +2362,6 @@ async function check(config) {
 	};
 }
 //#endregion
-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 };
+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-DhZyiWge.mjs.map
+//# sourceMappingURL=src-AWTGjMiX.mjs.map