@haddowg/json-api-codegen 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gregory Haddow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @haddowg/json-api-codegen
+
+> **Part of the [jsonapi.rest](https://jsonapi.rest) suite** — a complete, spec-compliant
+> JSON:API 1.1 stack: a framework-agnostic PHP [core](https://github.com/haddowg/json-api), a
+> [Symfony bundle](https://github.com/haddowg/json-api-symfony), a
+> [Laravel package](https://github.com/haddowg/json-api-laravel), and this **typed TypeScript
+> client**, bound together by one conformance-tested OpenAPI 3.1 contract.
+> Full documentation: **[haddowg.github.io/json-api-ts](https://haddowg.github.io/json-api-ts/)**.
+
+The CLI (and programmatic API) that reads the
+[`haddowg/json-api-symfony`](https://github.com/haddowg/json-api-symfony) OpenAPI 3.1 document and
+emits a typed client: a runtime descriptor, per-type attribute interfaces, and a descriptor-bound
+`createClient`. Optionally reads the bundle's JSON Schemas to emit a per-type schema map for the
+[client's](../client) opt-in validation seam.
+
+The OpenAPI document is fully self-describing for the runtime's needs — type identity
+(`properties.type.const`), relationship cardinality and related types, the allowed `?include`
+paths (a bounded, pre-expanded enum per endpoint), the create client-id policy, and paginator
+kinds. The codegen only reads the spec; all real work is generic runtime machinery in
+`@haddowg/json-api-client`.
+
+## Install
+
+A dev-only dependency — the **generated output** has no runtime tie back to the codegen (it imports
+`@haddowg/json-api-client`).
+
+```bash
+pnpm add -D @haddowg/json-api-codegen
+```
+
+Two bin names are installed: `json-api-codegen` and the short alias `japi`.
+
+## CLI
+
+```bash
+json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--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.  |
+
+Example — generate against a served API, with the validation schemas:
+
+```bash
+json-api-codegen \
+  --input https://music.example/docs.json \
+  --output src/api/music.gen.ts \
+  --schemas https://music.example/schemas.json
+```
+
+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`).
+
+The schema artifact path is derived from `--output`: a `.gen.ts` suffix becomes `.schemas.gen.ts`,
+a plain `.ts` becomes `.schemas.ts`.
+
+> **Commit the generated files.** Like `openapi-typescript` / `graphql-codegen`, the output is one
+> small, reviewable, diffable, versioned module in your repo — not a published package. Regenerate
+> when the API changes.
+
+### Provenance stamp
+
+Every generated artifact carries a provenance record in its header — the source spec identifier
+(`<info.title> <info.version>`), the first declared server URL, and a stable 16-hex content hash of
+the source document (the schema artifact carries a `Schema hash` of the schema bundle). It is
+**timestamp-free and deterministic**: regenerating from the same spec yields byte-identical output.
+The hash tells a reviewer which spec a committed client was generated from, and lets the drift gate
+below compare regenerated output byte-for-byte.
+
+```
+/**
+ * AUTO-GENERATED by @haddowg/json-api-codegen — do not edit by hand.
+ * Regenerate from the source OpenAPI document instead.
+ *
+ * Source spec: Music Catalog API 1.0.0
+ * Server:      https://music.example
+ * Spec hash:   40e273dff0411f68
+ */
+```
+
+### Drift check (`--check`)
+
+`--check` regenerates in memory and compares against the committed `--output` (and its schema
+sibling when `--schemas` is set) **without writing anything**. It prints a per-artifact `ok`/`DRIFT`
+line and exits non-zero if any committed file is missing or out of date. Wire it into CI — pinning
+the spec to a committed fixture — so a stale generated client fails the build:
+
+```bash
+json-api-codegen \
+  --input spec/music-catalog.openapi.json \
+  --output src/api/music.gen.ts \
+  --schemas spec/music-catalog.schemas.json \
+  --check
+```
+
+### Multiple servers
+
+The bundle serves one OpenAPI document per server (e.g. `default` and `admin` differ in their
+type set and path prefix). Generate one client per server by pointing `--input` at each server's
+document — one typed client per server.
+
+## What it generates
+
+The output module exports:
+
+- `resourceMap` — the runtime descriptor (`as const`); what the [query](../query) package's
+  normalization needs.
+- `ResourceMap` — `typeof resourceMap`.
+- `createClient(options)` — the descriptor-bound factory (the descriptor and the server's `atomic`
+  capability are baked in; you supply only [`ClientOptions`](../client)).
+- `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.
+
+With `--schemas`, the sibling module exports `schemas` — the per-type JSON Schema 2020-12 map.
+
+```ts
+import { createClient, type ResourceMap, resourceMap } from './api/music.gen'
+import { schemas } from './api/music.schemas.gen'
+
+const client = createClient({ baseUrl: 'https://music.example' })
+```
+
+### Verb / relation collisions
+
+If a type has a relation named like a reserved verb on the resource handle (`get`, `update`,
+`delete`, `rel`, `actions`, …), the codegen emits a **build-time warning** and that relation routes
+through `.rel('name')` in the fluent client; the common case stays clean.
+
+## Programmatic API
+
+The same generation, callable from a script (`japi.config.ts`, a build step, etc.):
+
+```ts
+import { generate, type CodegenConfig } from '@haddowg/json-api-codegen'
+
+const config: CodegenConfig = {
+  input: 'https://music.example/docs.json',
+  output: 'src/api/music.gen.ts',
+  schemas: 'https://music.example/schemas.json', // optional
+  server: 'default', // optional, metadata-only
+}
+
+await generate(config) // writes the output file(s); returns the client source string
+```
+
+The drift gate is also programmatic — `check(config)` regenerates in memory and returns
+`{ ok, artifacts }` (per-artifact `{ path, upToDate }`) without writing:
+
+```ts
+import { check } from '@haddowg/json-api-codegen'
+
+const result = await check({ ...config, check: true })
+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`.
+
+## License
+
+MIT

package/dist/cli.d.mts

@@ -0,0 +1,14 @@
+import { r as CodegenConfig } from "./index-C0becRSc.mjs";
+
+//#region src/cli.d.ts
+declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--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.
+ */
+declare function parseArgs(argv: string[]): Partial<CodegenConfig>;
+declare function run(argv: string[]): Promise<number>;
+//#endregion
+export { USAGE, parseArgs, run };
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../src/cli.ts"],"mappings":";;;cAIa,KAAA;AAAb;;;;AAAkB;AAAlB,iBAQgB,SAAA,CAAU,IAAA,aAAiB,OAAO,CAAC,aAAA;AAAA,iBA6B7B,GAAA,CAAI,IAAA,aAAiB,OAAO"}

package/dist/cli.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { n as generate, t as check } from "./src-B24cYyjM.mjs";
+import { pathToFileURL } from "node:url";
+//#region src/cli.ts
+const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--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.
+*/
+function parseArgs(argv) {
+	const config = {};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--check") {
+			config.check = true;
+			continue;
+		}
+		const next = argv[i + 1];
+		if (next === void 0) continue;
+		if (arg === "--input") {
+			config.input = next;
+			i++;
+		} else if (arg === "--output") {
+			config.output = next;
+			i++;
+		} else if (arg === "--server") {
+			config.server = next;
+			i++;
+		} else if (arg === "--schemas") {
+			config.schemas = next;
+			i++;
+		}
+	}
+	return config;
+}
+async function run(argv) {
+	const config = parseArgs(argv);
+	if (!config.input || !config.output) {
+		console.error(USAGE);
+		return 1;
+	}
+	if (config.check) {
+		const result = await check(config);
+		for (const { path, upToDate } of result.artifacts) console.error(`${upToDate ? "ok  " : "DRIFT"} ${path}`);
+		if (!result.ok) {
+			console.error("Generated client is out of date with the source spec. Regenerate (drop --check) and commit the result.");
+			return 1;
+		}
+		return 0;
+	}
+	await generate(config);
+	return 0;
+}
+async function main() {
+	process.exitCode = await run(process.argv.slice(2));
+}
+const entry = process.argv[1];
+if (entry !== void 0 && import.meta.url === pathToFileURL(entry).href) main().catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exitCode = 1;
+});
+//#endregion
+export { USAGE, parseArgs, run };
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { pathToFileURL } from 'node:url'\nimport { check, generate, 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  return 0\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).\nconst entry = process.argv[1]\nif (entry !== undefined && import.meta.url === pathToFileURL(entry).href) {\n  main().catch((error: unknown) => {\n    console.error(error instanceof Error ? error.message : error)\n    process.exitCode = 1\n  })\n}\n"],"mappings":";;;;AAIA,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,OAAO;AACT;AAEA,eAAe,OAAsB;CACnC,QAAQ,WAAW,MAAM,IAAI,QAAQ,KAAK,MAAM,CAAC,CAAC;AACpD;AAGA,MAAM,QAAQ,QAAQ,KAAK;AAC3B,IAAI,UAAU,KAAA,KAAa,OAAO,KAAK,QAAQ,cAAc,KAAK,CAAC,CAAC,MAClE,KAAK,CAAC,CAAC,OAAO,UAAmB;CAC/B,QAAQ,MAAM,iBAAiB,QAAQ,MAAM,UAAU,KAAK;CAC5D,QAAQ,WAAW;AACrB,CAAC"}