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 +12 -1
- package/dist/cli.js +18 -3
- package/dist/emit.d.ts +1 -2
- package/dist/emit.js +7 -3
- package/dist/index.d.ts +6 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# kanagata
|
|
2
2
|
|
|
3
|
+

|
|
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, [
|
|
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),
|
|
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
|
-
|
|
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 +=
|
|
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`). */
|