kanagata 0.2.1 → 0.2.2
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 +10 -7
- package/dist/cli.js +15 -3
- package/dist/index.d.ts +9 -1
- package/dist/index.js +2 -2
- package/dist/pointer.d.ts +3 -1
- package/dist/pointer.js +4 -1
- package/dist/schema.js +12 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -44,11 +44,12 @@ kanagata generate - < openapi.yaml > src/api/schema.d.ts # stdin to stdout
|
|
|
44
44
|
kanagata init -o src/api/client.ts # copy the client into your project
|
|
45
45
|
```
|
|
46
46
|
|
|
47
|
-
| Option
|
|
48
|
-
|
|
|
49
|
-
| `-o <path>`
|
|
50
|
-
| `--check`
|
|
51
|
-
| `--
|
|
47
|
+
| Option | Meaning |
|
|
48
|
+
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
49
|
+
| `-o <path>` | output file (`generate`: stdout; `init`: `./client.ts`) |
|
|
50
|
+
| `--check` | `generate`: compare with the `-o` file instead of writing |
|
|
51
|
+
| `--strict-nullable-enum` | `generate`: in 3.0, keep `null` out of an `enum` or `const` that does not list it, even with `nullable: true`; see [`nullable`](#nullable-30) |
|
|
52
|
+
| `--force` | `init`: overwrite an existing file |
|
|
52
53
|
|
|
53
54
|
- **Exit codes:** 0 success, 1 `--check` found a difference, 2 an error (document, command line, or file I/O), 3 a bug in kanagata (stack on stderr).
|
|
54
55
|
- **Messages** go to stderr as `location: message` or `location: warning: message`. The location is `line:col` for JSON and YAML syntax, a JSON Pointer otherwise, and starts with the file's path relative to the document for other files (`schemas/User.yaml#/properties/id`, `common.json:3:5`).
|
|
@@ -183,7 +184,7 @@ try {
|
|
|
183
184
|
}
|
|
184
185
|
```
|
|
185
186
|
|
|
186
|
-
`generate(src, source?)` returns `{ code, warnings }` and throws `GenerateError` (`e.name` is `"GenerateError"` for every `kind`). `source` is the document's absolute URL and `read(url)`, which returns the text of a file a `$ref` points to; without it, `$ref`s to other files are errors.
|
|
187
|
+
`generate(src, source?, options?)` returns `{ code, warnings }` and throws `GenerateError` (`e.name` is `"GenerateError"` for every `kind`). `source` is the document's absolute URL and `read(url)`, which returns the text of a file a `$ref` points to; without it, `$ref`s to other files are errors. `options` is `{ strictNullableEnum?: boolean }`, as `--strict-nullable-enum`.
|
|
187
188
|
|
|
188
189
|
## Output
|
|
189
190
|
|
|
@@ -245,7 +246,9 @@ A sequential media type's `itemSchema` (3.2) is checked like a schema but types
|
|
|
245
246
|
|
|
246
247
|
### `nullable` (3.0)
|
|
247
248
|
|
|
248
|
-
`nullable: true` adds `null` even without `type` (`{ nullable: true, allOf: [{ $ref: … }] }`) and next to an `enum` that does not list `null`. OpenAPI 3.0.3 says neither takes effect, but documents use both to mean "this schema or null" (Stripe and GitHub among them) and their servers return `null`, so kanagata follows the intent.
|
|
249
|
+
`nullable: true` adds `null` even without `type` (`{ nullable: true, allOf: [{ $ref: … }] }`) and next to an `enum` (or `const`) that does not list `null`. OpenAPI 3.0.3 says neither takes effect, but documents use both to mean "this schema or null" (Stripe and GitHub among them) and their servers return `null`, so kanagata follows the intent.
|
|
250
|
+
|
|
251
|
+
`--strict-nullable-enum` (`generate(src, source, { strictNullableEnum: true })`) reads the `enum` case as OpenAPI 3.0.3 does: an `enum` or `const` that does not list `null` keeps it out, so `{ type: string, enum: [a, b], nullable: true }` is `"a" | "b"`. `nullable` without `type` still adds `null`.
|
|
249
252
|
|
|
250
253
|
## Not supported
|
|
251
254
|
|
package/dist/cli.js
CHANGED
|
@@ -11,6 +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
|
+
[--strict-nullable-enum]
|
|
14
15
|
kanagata init [-o <client.ts>] [--force]
|
|
15
16
|
|
|
16
17
|
Commands:
|
|
@@ -20,6 +21,9 @@ Commands:
|
|
|
20
21
|
Options:
|
|
21
22
|
-o <path> Output file (generate: stdout, init: ./client.ts)
|
|
22
23
|
--check Exit with 1 if the -o file differs from the generated output
|
|
24
|
+
--strict-nullable-enum
|
|
25
|
+
In 3.0, keep null out of an enum or const that does not
|
|
26
|
+
list it, even with nullable: true (as OpenAPI 3.0.3 says)
|
|
23
27
|
--force Let init overwrite an existing file
|
|
24
28
|
-h, --help Show this help
|
|
25
29
|
-V, --version Show the version
|
|
@@ -104,7 +108,13 @@ function attempt(label, f) {
|
|
|
104
108
|
}
|
|
105
109
|
}
|
|
106
110
|
function parseFlags(args, allowed) {
|
|
107
|
-
const f = {
|
|
111
|
+
const f = {
|
|
112
|
+
positional: [],
|
|
113
|
+
check: false,
|
|
114
|
+
force: false,
|
|
115
|
+
strictNullableEnum: false,
|
|
116
|
+
help: false,
|
|
117
|
+
};
|
|
108
118
|
const rest = args[Symbol.iterator]();
|
|
109
119
|
for (const a of rest) {
|
|
110
120
|
const isOption = a.startsWith("-") && a !== "-";
|
|
@@ -121,6 +131,8 @@ function parseFlags(args, allowed) {
|
|
|
121
131
|
f.check = true;
|
|
122
132
|
else if (a === "--force")
|
|
123
133
|
f.force = true;
|
|
134
|
+
else if (a === "--strict-nullable-enum")
|
|
135
|
+
f.strictNullableEnum = true;
|
|
124
136
|
else if (isHelp)
|
|
125
137
|
f.help = true;
|
|
126
138
|
else
|
|
@@ -129,7 +141,7 @@ function parseFlags(args, allowed) {
|
|
|
129
141
|
return f;
|
|
130
142
|
}
|
|
131
143
|
function generateCommand(args, io, out, err) {
|
|
132
|
-
const f = parseFlags(args, ["-o", "--check"]);
|
|
144
|
+
const f = parseFlags(args, ["-o", "--check", "--strict-nullable-enum"]);
|
|
133
145
|
if (f.help) {
|
|
134
146
|
out(HELP);
|
|
135
147
|
return 0;
|
|
@@ -144,7 +156,7 @@ function generateCommand(args, io, out, err) {
|
|
|
144
156
|
const label = input === "-" ? "stdin" : input;
|
|
145
157
|
const src = decode(label, attempt(label, () => io.read(input === "-" ? 0 : input)));
|
|
146
158
|
// A file has a location, so its $refs to other files can be followed; stdin has none.
|
|
147
|
-
const generated = generate(src, input === "-" ? undefined : fileSource(input, io));
|
|
159
|
+
const generated = generate(src, input === "-" ? undefined : fileSource(input, io), { strictNullableEnum: f.strictNullableEnum });
|
|
148
160
|
for (const w of generated.warnings)
|
|
149
161
|
err(`${w.at}: warning: ${w.msg}`);
|
|
150
162
|
const target = f.output;
|
package/dist/index.d.ts
CHANGED
|
@@ -13,8 +13,16 @@ 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. */
|
|
17
|
+
export interface Options {
|
|
18
|
+
/**
|
|
19
|
+
* In 3.0, keep `null` out of an `enum` or `const` that does not list it, even with
|
|
20
|
+
* `nullable: true`, as OpenAPI 3.0.3 says. Off by default: documents mean "or null".
|
|
21
|
+
*/
|
|
22
|
+
strictNullableEnum?: boolean;
|
|
23
|
+
}
|
|
16
24
|
/**
|
|
17
25
|
* Converts an OpenAPI document (JSON or YAML) to a `.d.ts` file. With a `source`,
|
|
18
26
|
* `$ref`s to other files are read through it. Throws GenerateError.
|
|
19
27
|
*/
|
|
20
|
-
export declare function generate(src: string, source?: Source): Generated;
|
|
28
|
+
export declare function generate(src: string, source?: Source, options?: Options): Generated;
|
package/dist/index.js
CHANGED
|
@@ -17,7 +17,7 @@ function parseText(src, warnings) {
|
|
|
17
17
|
* Converts an OpenAPI document (JSON or YAML) to a `.d.ts` file. With a `source`,
|
|
18
18
|
* `$ref`s to other files are read through it. Throws GenerateError.
|
|
19
19
|
*/
|
|
20
|
-
export function generate(src, source) {
|
|
20
|
+
export function generate(src, source, options = {}) {
|
|
21
21
|
const read = [];
|
|
22
22
|
const root = parseText(src, read);
|
|
23
23
|
if (!(root instanceof JsonObject))
|
|
@@ -33,7 +33,7 @@ export function generate(src, source) {
|
|
|
33
33
|
!root.get("openapi").startsWith("3.0."), source && {
|
|
34
34
|
url: source.url,
|
|
35
35
|
load: (url) => loadText(cx, url, source.read(url)),
|
|
36
|
-
});
|
|
36
|
+
}, options.strictNullableEnum === true);
|
|
37
37
|
const p = paths(cx, root);
|
|
38
38
|
// Every component schema, then every schema from another file that got a key (the
|
|
39
39
|
// list grows as they are converted), named, in both views; the write view gets its
|
package/dist/pointer.d.ts
CHANGED
|
@@ -51,6 +51,8 @@ export declare class Ctx {
|
|
|
51
51
|
mode: View;
|
|
52
52
|
/** Whether keywords next to `$ref` apply (OpenAPI 3.1) or are ignored (3.0). */
|
|
53
53
|
readonly refSiblings: boolean;
|
|
54
|
+
/** Whether an `enum` or `const` that does not list `null` keeps it out despite 3.0 `nullable: true`. */
|
|
55
|
+
readonly strictNullableEnum: boolean;
|
|
54
56
|
/** Schemas from other files that got a key, in the order they were first referred to. */
|
|
55
57
|
readonly hoisted: Hoisted[];
|
|
56
58
|
/**
|
|
@@ -63,7 +65,7 @@ export declare class Ctx {
|
|
|
63
65
|
uri: string;
|
|
64
66
|
where: string;
|
|
65
67
|
}): string;
|
|
66
|
-
constructor(root: Value, schemas?: ReadonlySet<string>, refSiblings?: boolean, location?: Location);
|
|
68
|
+
constructor(root: Value, schemas?: ReadonlySet<string>, refSiblings?: boolean, location?: Location, strictNullableEnum?: boolean);
|
|
67
69
|
warn(at: string, msg: string): void;
|
|
68
70
|
get warnings(): Diag[];
|
|
69
71
|
leftOutIn(v: Value): ReadonlySet<string>;
|
package/dist/pointer.js
CHANGED
|
@@ -92,6 +92,8 @@ export class Ctx {
|
|
|
92
92
|
mode = "read";
|
|
93
93
|
/** Whether keywords next to `$ref` apply (OpenAPI 3.1) or are ignored (3.0). */
|
|
94
94
|
refSiblings;
|
|
95
|
+
/** Whether an `enum` or `const` that does not list `null` keeps it out despite 3.0 `nullable: true`. */
|
|
96
|
+
strictNullableEnum;
|
|
95
97
|
/** Schemas from other files that got a key, in the order they were first referred to. */
|
|
96
98
|
hoisted = [];
|
|
97
99
|
/** Hoisted keys by the URI of the schema. */
|
|
@@ -123,10 +125,11 @@ export class Ctx {
|
|
|
123
125
|
this.hoisted.push({ key, value, base: target.base, where: target.where });
|
|
124
126
|
return key;
|
|
125
127
|
}
|
|
126
|
-
constructor(root, schemas = new Set(), refSiblings = false, location) {
|
|
128
|
+
constructor(root, schemas = new Set(), refSiblings = false, location, strictNullableEnum = false) {
|
|
127
129
|
this.root = root;
|
|
128
130
|
this.schemas = schemas;
|
|
129
131
|
this.refSiblings = refSiblings;
|
|
132
|
+
this.strictNullableEnum = strictNullableEnum;
|
|
130
133
|
this.documentUrl =
|
|
131
134
|
location === undefined
|
|
132
135
|
? DOCUMENT
|
package/dist/schema.js
CHANGED
|
@@ -63,7 +63,8 @@ export function doc(v) {
|
|
|
63
63
|
}
|
|
64
64
|
/**
|
|
65
65
|
* `nullable: true` (3.0 only; 3.1 has no such keyword) adds `null` to whatever the rest
|
|
66
|
-
* of the schema gives, as documents mean it (see README)
|
|
66
|
+
* of the schema gives, as documents mean it (see README); with `strictNullableEnum`,
|
|
67
|
+
* an `enum` or `const` that does not list `null` keeps it out, as OAS 3.0.3 says.
|
|
67
68
|
*/
|
|
68
69
|
function parts(cx, v, at) {
|
|
69
70
|
const nullable = !cx.refSiblings && v.get("nullable") === true;
|
|
@@ -108,7 +109,16 @@ function parts(cx, v, at) {
|
|
|
108
109
|
if (Array.isArray(members))
|
|
109
110
|
out.push(union(admitted(members, list(cx, members, child(at, key)))));
|
|
110
111
|
}
|
|
111
|
-
|
|
112
|
+
const addsNull = nullable && (!cx.strictNullableEnum || valuesAdmitNull(v));
|
|
113
|
+
return addsNull ? union([inter(out), NULL]) : inter(out);
|
|
114
|
+
}
|
|
115
|
+
/** Whether the schema's own `enum` and `const`, where present, admit `null`. */
|
|
116
|
+
function valuesAdmitNull(v) {
|
|
117
|
+
const e = v.get("enum");
|
|
118
|
+
if (Array.isArray(e) && !e.includes(null))
|
|
119
|
+
return false;
|
|
120
|
+
const c = v.get("const");
|
|
121
|
+
return c === undefined || c === null;
|
|
112
122
|
}
|
|
113
123
|
/**
|
|
114
124
|
* The keys a closed object admits (`additionalProperties: false`, no
|