kanagata 0.3.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # kanagata
2
2
 
3
+ ![kanagata: types, not generated clients](docs/header.svg)
4
+
3
5
  TypeScript types from an OpenAPI 3.0 / 3.1 / 3.2 document (JSON or YAML), and a typed `fetch` client for them.
4
6
 
5
7
  - `kanagata generate` writes one `.d.ts` file.
@@ -28,6 +30,15 @@ if (res.status === 200) {
28
30
 
29
31
  Run `generate` again after upgrading kanagata: the types and the client come from the same version.
30
32
 
33
+ ## Types, not generated clients
34
+
35
+ kanagata generates no code per operation. It translates the OpenAPI schema into accurate TypeScript types, then lets TypeScript do the rest. Rather than generating a collection of abstractions, it provides the foundation for building a type-safe API environment:
36
+
37
+ - Each call is checked against its operation, and the editor autocompletes its path, parameters and request body.
38
+ - Responses form a discriminated union, so checking `status` narrows `data` to the corresponding response type.
39
+ - When the document changes, regenerate types: TypeScript flags affected calls that no longer match the updated contract, and `--check` fails CI if generated files are stale.
40
+ - Your own wrappers, query functions, hooks and validators are typed by the same `paths` and `operations` ([Wrapping a call](docs/client.md#wrapping-a-call)), without generating parallel runtime implementations.
41
+
31
42
  ## Install
32
43
 
33
44
  - The CLI needs Node 24 or later (`engines`). Its one dependency is [`yaml`](https://github.com/eemeli/yaml), which has none.
@@ -44,7 +55,7 @@ kanagata generate - < openapi.yaml > src/api/schema.d.ts # stdin to stdout
44
55
  kanagata init -o src/api/client.ts # copy the client into your project
45
56
  ```
46
57
 
47
- `--loose-nullable` reads 3.0 `nullable: true` as "this schema or null" (see [Generated types](#generated-types)). Every option, the exit codes and messages, and `generate` as a library: [docs/cli.md](docs/cli.md).
58
+ `--loose-nullable` reads 3.0 `nullable: true` as "this schema or null" (see [Generated types](#generated-types)). The file's first line names the kanagata version that wrote it (`--omit-version` leaves it out): after upgrading, a regenerated file that differs only in that line has the same types. Every option, the exit codes and messages, and `generate` as a library: [docs/cli.md](docs/cli.md).
48
59
 
49
60
  ## Client
50
61
 
package/dist/cli.js CHANGED
@@ -11,7 +11,7 @@ const HELP = `kanagata - TypeScript types from OpenAPI 3.0 / 3.1 / 3.2 (JSON or
11
11
 
12
12
  Usage:
13
13
  kanagata generate <openapi.json|yaml> [-o <out.d.ts>] [--check]
14
- [--loose-nullable]
14
+ [--loose-nullable] [--omit-version]
15
15
  kanagata init [-o <client.ts>] [--force]
16
16
 
17
17
  Commands:
@@ -25,6 +25,7 @@ Options:
25
25
  In 3.0, read nullable: true as "this schema or null", even
26
26
  where OpenAPI 3.0.3 gives it no effect (no type, next to
27
27
  $ref, an enum without null)
28
+ --omit-version Leave the kanagata version out of the first line
28
29
  --force Let init overwrite an existing file
29
30
  -h, --help Show this help
30
31
  -V, --version Show the version
@@ -114,6 +115,7 @@ function parseFlags(args, allowed) {
114
115
  check: false,
115
116
  force: false,
116
117
  looseNullable: false,
118
+ omitVersion: false,
117
119
  help: false,
118
120
  };
119
121
  const rest = args[Symbol.iterator]();
@@ -134,6 +136,8 @@ function parseFlags(args, allowed) {
134
136
  f.force = true;
135
137
  else if (a === "--loose-nullable")
136
138
  f.looseNullable = true;
139
+ else if (a === "--omit-version")
140
+ f.omitVersion = true;
137
141
  else if (isHelp)
138
142
  f.help = true;
139
143
  else
@@ -142,7 +146,12 @@ function parseFlags(args, allowed) {
142
146
  return f;
143
147
  }
144
148
  function generateCommand(args, io, out, err) {
145
- const f = parseFlags(args, ["-o", "--check", "--loose-nullable"]);
149
+ const f = parseFlags(args, [
150
+ "-o",
151
+ "--check",
152
+ "--loose-nullable",
153
+ "--omit-version",
154
+ ]);
146
155
  if (f.help) {
147
156
  out(HELP);
148
157
  return 0;
@@ -157,7 +166,13 @@ function generateCommand(args, io, out, err) {
157
166
  const label = input === "-" ? "stdin" : input;
158
167
  const src = decode(label, attempt(label, () => io.read(input === "-" ? 0 : input)));
159
168
  // A file has a location, so its $refs to other files can be followed; stdin has none.
160
- const generated = generate(src, input === "-" ? undefined : fileSource(input, io), { looseNullable: f.looseNullable });
169
+ const generated = generate(src, input === "-" ? undefined : fileSource(input, io),
170
+ // The version tells which kanagata's rules the file follows: after an upgrade, a
171
+ // regenerated file that differs only in its first line has the same types.
172
+ {
173
+ looseNullable: f.looseNullable,
174
+ ...(f.omitVersion ? {} : { version: version(io) }),
175
+ });
161
176
  for (const w of generated.warnings)
162
177
  err(`${w.at}: warning: ${w.msg}`);
163
178
  const target = f.output;
package/dist/emit.d.ts CHANGED
@@ -1,5 +1,4 @@
1
1
  import type { Prop, Ty, View } from "./ty.ts";
2
- export declare const HEADER = "// Generated by kanagata. Do not edit.\n";
3
2
  /** Context precedence. A type binding looser than its context is parenthesized. */
4
3
  export declare const Prec: {
5
4
  readonly Union: 0;
@@ -39,4 +38,4 @@ export interface Document {
39
38
  schemas: Prop[];
40
39
  decls: Decl[];
41
40
  }
42
- export declare function render(doc: Document, name: Namer): string;
41
+ export declare function render(doc: Document, name: Namer, version: string | undefined): string;
package/dist/emit.js CHANGED
@@ -1,6 +1,10 @@
1
1
  // Turns `Ty` into TypeScript source text.
2
2
  import { isIdent, isNumericKey } from "./ident.js";
3
- export const HEADER = "// Generated by kanagata. Do not edit.\n";
3
+ /** The first line, naming the kanagata version when one is given. */
4
+ function header(version) {
5
+ const by = version === undefined ? "kanagata" : `kanagata ${version}`;
6
+ return `// Generated by ${by}. Do not edit.\n`;
7
+ }
4
8
  /** Context precedence. A type binding looser than its context is parenthesized. */
5
9
  export const Prec = { Union: 0, Inter: 1, Postfix: 2 };
6
10
  export class Out {
@@ -149,9 +153,9 @@ export class Out {
149
153
  this.buf += " */\n";
150
154
  }
151
155
  }
152
- export function render(doc, name) {
156
+ export function render(doc, name, version) {
153
157
  const out = new Out(name);
154
- out.buf += HEADER;
158
+ out.buf += header(version);
155
159
  const interfaces = [["paths", doc.paths]];
156
160
  if (doc.webhooks !== undefined)
157
161
  interfaces.push(["webhooks", doc.webhooks]);
package/dist/index.d.ts CHANGED
@@ -13,7 +13,7 @@ export interface Source {
13
13
  /** The text of the document at an absolute URL; throws, with a message saying why, when it cannot be read. */
14
14
  read: (url: string) => string;
15
15
  }
16
- /** How the document is read. */
16
+ /** How the document is read, and what the output's first line says. */
17
17
  export interface Options {
18
18
  /**
19
19
  * In 3.0, read `nullable: true` as "this schema or null": `null` even without `type`,
@@ -21,6 +21,11 @@ export interface Options {
21
21
  * Off by default: `nullable` adds `null` to `type` only, as OpenAPI 3.0.3 says.
22
22
  */
23
23
  looseNullable?: boolean;
24
+ /**
25
+ * The kanagata version the first line names (`// Generated by kanagata 0.4.0. Do not edit.`),
26
+ * as the CLI writes it. Without it, the line names no version.
27
+ */
28
+ version?: string;
24
29
  }
25
30
  /**
26
31
  * Converts an OpenAPI document (JSON or YAML) to a `.d.ts` file. With a `source`,
package/dist/index.js CHANGED
@@ -93,7 +93,7 @@ export function generate(src, source, options = {}) {
93
93
  operations: props(p.operations),
94
94
  ...(p.webhooks === undefined ? {} : { webhooks: props(p.webhooks) }),
95
95
  };
96
- const code = render({ ...ops, schemas: index, decls }, name);
96
+ const code = render({ ...ops, schemas: index, decls }, name, options.version);
97
97
  return { code, warnings: [...read, ...cx.warnings] };
98
98
  }
99
99
  /** Parses another document; its problems are located in that file (`defs/a.yaml:3:1`, `defs/a.yaml#/b`). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kanagata",
3
- "version": "0.3.2",
3
+ "version": "0.4.0",
4
4
  "description": "TypeScript types from OpenAPI 3.0 / 3.1 / 3.2 (JSON or YAML), and a typed fetch client",
5
5
  "keywords": [
6
6
  "openapi",