kanagata 0.2.1 → 0.2.3

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
@@ -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 | Meaning |
48
- | ----------- | --------------------------------------------------------- |
49
- | `-o <path>` | output file (`generate`: stdout; `init`: `./client.ts`) |
50
- | `--check` | `generate`: compare with the `-o` file instead of writing |
51
- | `--force` | `init`: overwrite an existing file |
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`).
@@ -139,6 +140,21 @@ async function get<
139
140
 
140
141
  For `api.request`, the method takes the place of `"get"`: `ArgsOf<paths, "COPY", Path>`.
141
142
 
143
+ `OkResult<R>` and `NotOkResult<R>` are the results `if (res.ok)` leaves on each side. `default` is on both, since it covers an undocumented 2xx; `Extract<R, { ok: true }>` would drop it. A wrapper that throws the others returns `OkResult<…>["data"]`:
144
+
145
+ ```ts
146
+ import type { ArgsOf, OkResult, PathsOf, ResultOf } from "kanagata/client";
147
+
148
+ async function getOk<Path extends PathsOf<paths, "get">>(
149
+ path: Path,
150
+ ...args: ArgsOf<paths, "get", Path>
151
+ ): Promise<OkResult<ResultOf<paths, "get", Path>>["data"]> {
152
+ const res = await api.get(path, ...args);
153
+ if (!res.ok) throw res; // NotOkResult<ResultOf<paths, "get", Path>>
154
+ return res.data;
155
+ }
156
+ ```
157
+
142
158
  ### Details
143
159
 
144
160
  - **baseUrl:** a relative one resolves on every call as fetch resolves it: against the page's base URL, or the worker's location. Where there is neither (Node), it throws a TypeError. `""` is the origin of the page's base URL. Its own query is kept, before the call's. An operation that declares `servers` (or whose path item does) is served there, not by the document's servers, so its call names one of them as `baseUrl`; other operations take the config's and cannot be given one.
@@ -183,7 +199,7 @@ try {
183
199
  }
184
200
  ```
185
201
 
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.
202
+ `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
203
 
188
204
  ## Output
189
205
 
@@ -245,7 +261,9 @@ A sequential media type's `itemSchema` (3.2) is checked like a schema but types
245
261
 
246
262
  ### `nullable` (3.0)
247
263
 
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.
264
+ `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.
265
+
266
+ `--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
267
 
250
268
  ## Not supported
251
269
 
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 = { positional: [], check: false, force: false, help: false };
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/client.d.ts CHANGED
@@ -171,6 +171,22 @@ export type Result<O, A extends ParseAs | undefined = undefined, M extends strin
171
171
  * method given once (so HEAD has no body, as in the call).
172
172
  */
173
173
  export type ResultOf<P, M extends string, Path extends PathsOf<P, M>, A extends ParseAs | undefined = undefined> = Result<Op<P, Path, M>, A, M>;
174
+ /**
175
+ * The results of R that `if (res.ok)` leaves: the 2xx statuses, and `default`, which
176
+ * covers an undocumented 2xx (its `ok` is `boolean`). `OkResult<ResultOf<…>>["data"]`
177
+ * types what a wrapper returns when it throws the others.
178
+ */
179
+ export type OkResult<R> = R extends {
180
+ ok: infer K;
181
+ } ? true extends K ? R & {
182
+ ok: true;
183
+ } : never : never;
184
+ /** The results of R that `if (!res.ok)` leaves: the other statuses, and `default`. */
185
+ export type NotOkResult<R> = R extends {
186
+ ok: infer K;
187
+ } ? false extends K ? R & {
188
+ ok: false;
189
+ } : never : never;
174
190
  type MaybePromise<T> = T | Promise<T>;
175
191
  export interface ClientConfig extends FetchOptions {
176
192
  /** Absolute, or relative to the page (`/api`) as fetch resolves it, on every call. */
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
- return nullable ? union([inter(out), NULL]) : inter(out);
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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kanagata",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
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",
package/src/client.ts CHANGED
@@ -278,6 +278,24 @@ export type ResultOf<
278
278
  A extends ParseAs | undefined = undefined,
279
279
  > = Result<Op<P, Path, M>, A, M>;
280
280
 
281
+ /**
282
+ * The results of R that `if (res.ok)` leaves: the 2xx statuses, and `default`, which
283
+ * covers an undocumented 2xx (its `ok` is `boolean`). `OkResult<ResultOf<…>>["data"]`
284
+ * types what a wrapper returns when it throws the others.
285
+ */
286
+ export type OkResult<R> = R extends { ok: infer K }
287
+ ? true extends K
288
+ ? R & { ok: true }
289
+ : never
290
+ : never;
291
+
292
+ /** The results of R that `if (!res.ok)` leaves: the other statuses, and `default`. */
293
+ export type NotOkResult<R> = R extends { ok: infer K }
294
+ ? false extends K
295
+ ? R & { ok: false }
296
+ : never
297
+ : never;
298
+
281
299
  type MaybePromise<T> = T | Promise<T>;
282
300
 
283
301
  export interface ClientConfig extends FetchOptions {