kanagata 0.3.2 → 0.5.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 +17 -5
- package/dist/cli.js +18 -3
- package/dist/client.d.ts +63 -35
- package/dist/emit.d.ts +18 -4
- package/dist/emit.js +171 -28
- package/dist/index.d.ts +6 -1
- package/dist/index.js +8 -3
- package/dist/operation.d.ts +17 -2
- package/dist/operation.js +214 -71
- package/dist/pointer.d.ts +51 -8
- package/dist/pointer.js +136 -5
- package/dist/schema.d.ts +11 -3
- package/dist/schema.js +1528 -138
- package/dist/template.d.ts +12 -0
- package/dist/template.js +349 -0
- package/dist/ty.d.ts +28 -4
- package/dist/ty.js +367 -60
- package/package.json +1 -1
- package/src/client.ts +82 -54
package/dist/operation.js
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
// Paths, webhooks and operations → `Ty`.
|
|
2
2
|
import { isBinaryMedia, isFormMedia, isTextMedia, METHODS } from "./client.js";
|
|
3
|
-
import { JsonObject } from "./json.js";
|
|
3
|
+
import { get, JsonObject, str } from "./json.js";
|
|
4
4
|
import { child, DiagError } from "./pointer.js";
|
|
5
5
|
import { doc, schema } from "./schema.js";
|
|
6
|
-
import { BLOB,
|
|
6
|
+
import { BLOB, lit, object, opRef, prop, STRING, tuple, UNKNOWN, } from "./ty.js";
|
|
7
7
|
const LOCATIONS = ["path", "query", "querystring", "header", "cookie"];
|
|
8
8
|
/** Header parameters OpenAPI says to ignore, in lower case. */
|
|
9
9
|
const RESERVED_HEADERS = ["accept", "content-type", "authorization"];
|
|
@@ -19,68 +19,121 @@ export function paths(cx, root) {
|
|
|
19
19
|
const out = {
|
|
20
20
|
paths: pathItems(cx, root, "paths", operations),
|
|
21
21
|
operations: [],
|
|
22
|
+
again: [],
|
|
22
23
|
};
|
|
23
|
-
|
|
24
|
+
// `webhooks` is an OpenAPI 3.1 field, no field of a 3.0 document.
|
|
25
|
+
const v30 = root.get("openapi").startsWith("3.0.");
|
|
26
|
+
if (!v30 && root.get("webhooks") !== undefined)
|
|
24
27
|
out.webhooks = pathItems(cx, root, "webhooks", operations);
|
|
25
28
|
out.operations = [...operations.values()].map((o) => o.prop);
|
|
29
|
+
out.again = [...operations].flatMap(([id, o]) => o.again.map((a) => ({ id, ...a, first: { ty: o.prop.ty, at: o.at } })));
|
|
26
30
|
return out;
|
|
27
31
|
}
|
|
28
32
|
/**
|
|
29
33
|
* Adds an operation with an operationId. A Path Item shared by `$ref` (or a YAML alias)
|
|
30
34
|
* gives the same Operation Object again, which is declared once; another Operation
|
|
31
35
|
* Object with the same operationId, which OpenAPI requires to be unique, is an error.
|
|
32
|
-
* The same operation as a path's and a webhook's
|
|
33
|
-
* webhook's request
|
|
36
|
+
* The same operation reached again can have another type (as a path's and a webhook's,
|
|
37
|
+
* since the API sends a webhook's request; under paths with other path-level parameters)
|
|
38
|
+
* but one `operations[id]`, so its type there is kept for `generate` to compare once the
|
|
39
|
+
* components' second types are known.
|
|
34
40
|
*/
|
|
35
41
|
function addOperation(operations, id, op, prop, at) {
|
|
36
42
|
const known = operations.get(id);
|
|
37
43
|
if (known === undefined)
|
|
38
|
-
operations.set(id, { op, prop, at });
|
|
44
|
+
operations.set(id, { op, prop, at, again: [] });
|
|
39
45
|
else if (known.op !== op)
|
|
40
46
|
throw new DiagError(at, `operationId ${JSON.stringify(id)} is also ${known.at}'s; OpenAPI requires it to be unique`);
|
|
41
|
-
else
|
|
42
|
-
|
|
47
|
+
else
|
|
48
|
+
known.again.push({ ty: prop.ty, at });
|
|
43
49
|
}
|
|
44
50
|
function pathItems(cx, root, key, operations) {
|
|
45
|
-
const out = [];
|
|
46
51
|
const entries = root.get(key);
|
|
47
52
|
if (entries === undefined)
|
|
48
|
-
return
|
|
53
|
+
return [];
|
|
49
54
|
if (!(entries instanceof JsonObject))
|
|
50
55
|
throw new DiagError(`#/${key}`, `${key} must be an object`);
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
56
|
+
// Paths may have specification extensions; webhooks is a plain map of names.
|
|
57
|
+
return pathItemsIn(cx, entries.entries.filter(([k]) => key === "webhooks" || !k.startsWith("x-")), `#/${key}`, key === "webhooks", operations);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Path Items by name (a path, a webhook's name, a callback's expression). Those the API
|
|
61
|
+
* calls (`byApi`: webhooks, callbacks) are the other way round: the API sends the
|
|
62
|
+
* request and reads the response.
|
|
63
|
+
*/
|
|
64
|
+
function pathItemsIn(cx, entries, at, byApi, operations) {
|
|
65
|
+
const out = [];
|
|
66
|
+
for (const [path, rawItem] of entries) {
|
|
67
|
+
const itemAt = child(at, path);
|
|
68
|
+
const layers = itemLayers(cx, rawItem, itemAt);
|
|
69
|
+
const ops = layers.flatMap((l) => itemOperations(cx, l.item, itemAt).map(([m, o, a]) => [m, o, a, l.base]));
|
|
70
|
+
ops.sort(([a], [b]) => methodOrder(a) - methodOrder(b));
|
|
71
|
+
const methods = [];
|
|
72
|
+
for (const [method, op, opAt, base] of ops) {
|
|
73
|
+
// A webhook is called by the API: it sends the request and reads the response.
|
|
74
|
+
const sent = byApi ? "read" : "write";
|
|
75
|
+
// fetch cannot send a body with GET or HEAD (OpenAPI 3.0 has consumers ignore
|
|
76
|
+
// one); a webhook's request is sent by the API, so it keeps its body.
|
|
77
|
+
const body = byApi || (method !== "get" && method !== "head");
|
|
78
|
+
const ty = cx.withBase(base, () => operation(cx, operations, {
|
|
79
|
+
layers,
|
|
80
|
+
itemAt,
|
|
81
|
+
op,
|
|
82
|
+
at: opAt,
|
|
83
|
+
sent,
|
|
84
|
+
body,
|
|
85
|
+
}));
|
|
86
|
+
const opDoc = doc(op);
|
|
87
|
+
const id = op.get("operationId");
|
|
88
|
+
if (id !== undefined && typeof id !== "string")
|
|
89
|
+
throw new DiagError(child(opAt, "operationId"), "operationId must be a string");
|
|
90
|
+
if (id !== undefined && id !== "") {
|
|
91
|
+
addOperation(operations, id, op, documented(id, ty, false, opDoc), opAt);
|
|
92
|
+
methods.push(prop(method, opRef(id)));
|
|
77
93
|
}
|
|
78
|
-
|
|
79
|
-
|
|
94
|
+
else {
|
|
95
|
+
methods.push(documented(method, ty, false, opDoc));
|
|
96
|
+
}
|
|
97
|
+
}
|
|
80
98
|
out.push(prop(path, object(methods)));
|
|
81
99
|
}
|
|
82
100
|
return out;
|
|
83
101
|
}
|
|
102
|
+
/** Path Item fields that only describe it; kanagata reads neither. */
|
|
103
|
+
const DESCRIPTIVE = new Set(["$ref", "summary", "description"]);
|
|
104
|
+
/**
|
|
105
|
+
* A Path Item and the Path Items its `$ref`s refer to, in turn: their fields are read
|
|
106
|
+
* together, each under the base URI of its document. A field in two of them, whose
|
|
107
|
+
* behaviour OpenAPI leaves undefined, is an error (descriptions and extensions aside).
|
|
108
|
+
*/
|
|
109
|
+
function itemLayers(cx, raw, itemAt) {
|
|
110
|
+
const layers = [];
|
|
111
|
+
const seen = new Set();
|
|
112
|
+
let cur = raw;
|
|
113
|
+
let base = cx.base;
|
|
114
|
+
for (;;) {
|
|
115
|
+
const item = objectAt(cur, itemAt, "a path item");
|
|
116
|
+
for (const [k] of item.entries) {
|
|
117
|
+
if (DESCRIPTIVE.has(k) || k.startsWith("x-"))
|
|
118
|
+
continue;
|
|
119
|
+
if (seen.has(k))
|
|
120
|
+
throw new DiagError(child(itemAt, k), `${k} is both next to $ref and in the Path Item it refers to; OpenAPI leaves which one applies undefined`);
|
|
121
|
+
seen.add(k);
|
|
122
|
+
}
|
|
123
|
+
layers.push({ item, base });
|
|
124
|
+
const r = item.str("$ref");
|
|
125
|
+
if (r === undefined)
|
|
126
|
+
return layers;
|
|
127
|
+
const target = cx.withBase(base, () => cx.locate(r, itemAt));
|
|
128
|
+
cur = target.value;
|
|
129
|
+
base = target.base;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
/** Fixed methods in OpenAPI's order, then `additionalOperations` as written (a stable sort keeps them). */
|
|
133
|
+
function methodOrder(method) {
|
|
134
|
+
const i = METHODS.indexOf(method);
|
|
135
|
+
return i < 0 ? METHODS.length : i;
|
|
136
|
+
}
|
|
84
137
|
/**
|
|
85
138
|
* A Path Item's operations, keyed by method: its fixed fields in OpenAPI's order, then its
|
|
86
139
|
* `additionalOperations`, whose keys are methods as they are sent (`COPY`). `query` and
|
|
@@ -112,19 +165,33 @@ function itemOperations(cx, item, itemAt) {
|
|
|
112
165
|
}
|
|
113
166
|
return out;
|
|
114
167
|
}
|
|
115
|
-
|
|
168
|
+
/**
|
|
169
|
+
* The `description` next to a `$ref` to a parameter, request body or header, which
|
|
170
|
+
* replaces the referenced one's in 3.1 and 3.2; 3.0 ignores a Reference Object's other fields.
|
|
171
|
+
*/
|
|
172
|
+
function refDescription(cx, raw) {
|
|
173
|
+
if (!cx.refSiblings || !(raw instanceof JsonObject))
|
|
174
|
+
return undefined;
|
|
175
|
+
return raw.get("$ref") === undefined ? undefined : raw.str("description");
|
|
176
|
+
}
|
|
177
|
+
function operation(cx, operations, { layers, itemAt, op: o, at, sent, body: hasBody }) {
|
|
116
178
|
const fields = [];
|
|
117
179
|
const received = sent === "write" ? "read" : "write";
|
|
118
180
|
// The servers that serve this operation, in place of the document's: its own, or its
|
|
119
|
-
// path item's. A webhook's request is sent by the API,
|
|
181
|
+
// path item's (at most one layer has them). A webhook's request is sent by the API,
|
|
182
|
+
// so it has none to choose.
|
|
120
183
|
const servers = sent === "write"
|
|
121
|
-
? (serverUrls(o, at) ??
|
|
184
|
+
? (serverUrls(o, at) ??
|
|
185
|
+
layers
|
|
186
|
+
.map((l) => serverUrls(l.item, itemAt))
|
|
187
|
+
.find((s) => s !== undefined))
|
|
122
188
|
: undefined;
|
|
123
189
|
if (servers !== undefined)
|
|
124
190
|
fields.push(prop("servers", tuple(servers)));
|
|
125
191
|
// Path-level parameters first; an operation parameter with the same in + name replaces it.
|
|
126
192
|
const params = [];
|
|
127
|
-
|
|
193
|
+
for (const l of layers)
|
|
194
|
+
cx.withBase(l.base, () => collectParams(cx, params, l.item, itemAt));
|
|
128
195
|
collectParams(cx, params, o, at);
|
|
129
196
|
const groups = [];
|
|
130
197
|
for (const loc of LOCATIONS) {
|
|
@@ -132,17 +199,19 @@ function operation(cx, { item, itemAt, op: o, at, sent, body: hasBody }) {
|
|
|
132
199
|
if (loc === "querystring" && !cx.v32)
|
|
133
200
|
continue;
|
|
134
201
|
const props = [];
|
|
135
|
-
for (const [p, pAt, base] of params) {
|
|
202
|
+
for (const [p, pAt, base, pDoc] of params) {
|
|
136
203
|
if (p.str("in") !== loc)
|
|
137
204
|
continue;
|
|
138
|
-
|
|
205
|
+
// OpenAPI requires a path parameter's required to be true: the path needs it.
|
|
206
|
+
const required = booleanAt(p, pAt, "required");
|
|
207
|
+
const optional = loc !== "path" && !required;
|
|
139
208
|
const whole = loc === "querystring";
|
|
140
209
|
const ty = cx.inMode(sent, () => cx.withBase(base, () => paramType(cx, p, pAt, "parameter")));
|
|
141
210
|
// The whole query string (3.2) is one value; its name is not sent.
|
|
142
211
|
if (whole)
|
|
143
|
-
groups.push(documented(loc, ty, optional,
|
|
212
|
+
groups.push(documented(loc, ty, optional, pDoc));
|
|
144
213
|
else
|
|
145
|
-
props.push(documented(p.str("name"), ty, optional,
|
|
214
|
+
props.push(documented(p.str("name"), ty, optional, pDoc));
|
|
146
215
|
}
|
|
147
216
|
if (props.length === 0)
|
|
148
217
|
continue;
|
|
@@ -157,15 +226,27 @@ function operation(cx, { item, itemAt, op: o, at, sent, body: hasBody }) {
|
|
|
157
226
|
const rawBody = o.get("requestBody");
|
|
158
227
|
if (rawBody !== undefined && hasBody) {
|
|
159
228
|
const bodyAt = child(at, "requestBody");
|
|
229
|
+
const described = refDescription(cx, rawBody);
|
|
160
230
|
cx.derefIn(rawBody, bodyAt, (value) => {
|
|
161
231
|
const body = objectAt(value, bodyAt, "a request body");
|
|
162
232
|
if (body.get("content") === undefined)
|
|
163
233
|
throw new DiagError(bodyAt, "a request body must have content");
|
|
164
234
|
// An empty content describes no representation: no body can be passed.
|
|
165
|
-
const c = cx.inMode(sent, () => content(cx, body, bodyAt))
|
|
166
|
-
fields.push(documented("requestBody", object([
|
|
235
|
+
const c = cx.inMode(sent, () => content(cx, body, bodyAt, false));
|
|
236
|
+
fields.push(documented("requestBody", object([
|
|
237
|
+
prop("content", c.content ?? object([])),
|
|
238
|
+
...(c.items === undefined ? [] : [prop("itemContent", c.items)]),
|
|
239
|
+
]), !booleanAt(body, bodyAt, "required"), doc(body, described)));
|
|
167
240
|
});
|
|
168
241
|
}
|
|
242
|
+
else if (rawBody !== undefined) {
|
|
243
|
+
// fetch sends no body with GET or HEAD, so the call cannot be the request a
|
|
244
|
+
// required body asks for.
|
|
245
|
+
const r = str(rawBody, "$ref");
|
|
246
|
+
const body = r === undefined ? rawBody : cx.tryLocate(r)?.value;
|
|
247
|
+
if (get(body, "required") === true)
|
|
248
|
+
cx.warn(child(at, "requestBody"), "a required request body on GET or HEAD is left out: fetch cannot send one");
|
|
249
|
+
}
|
|
169
250
|
const responses = [];
|
|
170
251
|
const rs = o.get("responses");
|
|
171
252
|
const base = child(at, "responses");
|
|
@@ -180,19 +261,38 @@ function operation(cx, { item, itemAt, op: o, at, sent, body: hasBody }) {
|
|
|
180
261
|
const h = cx.inMode(received, () => headers(cx, r, rAt));
|
|
181
262
|
if (h !== undefined)
|
|
182
263
|
parts.push(prop("headers", h));
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
264
|
+
// The client reads a path's responses; a webhook's are the receiver's.
|
|
265
|
+
const c = cx.inMode(received, () => content(cx, r, rAt, received === "read"));
|
|
266
|
+
if (c.content !== undefined)
|
|
267
|
+
parts.push(prop("content", c.content));
|
|
268
|
+
if (c.items !== undefined)
|
|
269
|
+
parts.push(prop("itemContent", c.items));
|
|
186
270
|
return parts;
|
|
187
271
|
});
|
|
188
272
|
responses.push(prop(status, object(parts)));
|
|
189
273
|
}
|
|
190
274
|
fields.push(prop("responses", object(responses)));
|
|
275
|
+
// Callbacks: requests the API sends to an expression's URL, typed as webhooks are.
|
|
276
|
+
const callbacks = o.get("callbacks");
|
|
277
|
+
if (callbacks !== undefined) {
|
|
278
|
+
const cbAt = child(at, "callbacks");
|
|
279
|
+
const named = [];
|
|
280
|
+
for (const [name, raw] of objectAt(callbacks, cbAt, "callbacks").entries) {
|
|
281
|
+
const nameAt = child(cbAt, name);
|
|
282
|
+
const items = cx.derefIn(raw, nameAt, (value) => pathItemsIn(cx,
|
|
283
|
+
// A Callback Object may have specification extensions.
|
|
284
|
+
objectAt(value, nameAt, "a callback").entries.filter(([k]) => !k.startsWith("x-")), nameAt, true, operations));
|
|
285
|
+
named.push(prop(name, object(items)));
|
|
286
|
+
}
|
|
287
|
+
fields.push(prop("callbacks", object(named)));
|
|
288
|
+
}
|
|
191
289
|
return object(fields);
|
|
192
290
|
}
|
|
193
291
|
/**
|
|
194
|
-
* The URLs of a non-empty `servers
|
|
195
|
-
* any string
|
|
292
|
+
* The URLs of a non-empty `servers`: a literal, or a template where a variable is the
|
|
293
|
+
* values its `enum` lists (any string without one). A relative URL resolves against
|
|
294
|
+
* where the document is served, which the types do not know: it is any URL that ends
|
|
295
|
+
* the way it does (`/v2` is `` `${string}/v2` ``).
|
|
196
296
|
*/
|
|
197
297
|
function serverUrls(owner, ownerAt) {
|
|
198
298
|
const at = child(ownerAt, "servers");
|
|
@@ -203,18 +303,47 @@ function serverUrls(owner, ownerAt) {
|
|
|
203
303
|
const url = s instanceof JsonObject ? s.str("url") : undefined;
|
|
204
304
|
if (url === undefined)
|
|
205
305
|
throw new DiagError(child(at, String(i)), "a server must have a url");
|
|
206
|
-
return url
|
|
306
|
+
return serverUrl(url, get(s, "variables"));
|
|
207
307
|
});
|
|
208
308
|
}
|
|
309
|
+
function serverUrl(url, variables) {
|
|
310
|
+
// A URL with a scheme is absolute; otherwise what is left past ./ and ../ ends it.
|
|
311
|
+
const absolute = /^[a-z][a-z0-9+.-]*:/i.test(url);
|
|
312
|
+
const end = absolute
|
|
313
|
+
? url
|
|
314
|
+
: url.replace(/^(\.{1,2}\/)+/, "").replace(/^\//, "");
|
|
315
|
+
if (!absolute && end === "")
|
|
316
|
+
return STRING;
|
|
317
|
+
const parts = end.split(/\{([^}]*)\}/);
|
|
318
|
+
if (absolute && parts.length === 1)
|
|
319
|
+
return lit(JSON.stringify(url));
|
|
320
|
+
const text = (s) => s.replaceAll("\\", "\\\\").replaceAll("`", "\\`").replaceAll("${", "\\${");
|
|
321
|
+
const hole = (name) => {
|
|
322
|
+
const e = get(get(variables, name), "enum");
|
|
323
|
+
const values = Array.isArray(e)
|
|
324
|
+
? e.filter((x) => typeof x === "string")
|
|
325
|
+
: [];
|
|
326
|
+
return values.length === 0
|
|
327
|
+
? "string"
|
|
328
|
+
: values.map((x) => JSON.stringify(x)).join(" | ");
|
|
329
|
+
};
|
|
330
|
+
const body = parts
|
|
331
|
+
.map((p, j) => (j % 2 === 0 ? text(p) : `\${${hole(p)}}`))
|
|
332
|
+
.join("");
|
|
333
|
+
// A relative URL starts with whatever leads to where it ends.
|
|
334
|
+
const lead = absolute ? "" : `\${${"string"}}/`;
|
|
335
|
+
return { kind: "template", text: `\`${lead}${body}\`` };
|
|
336
|
+
}
|
|
209
337
|
function collectParams(cx, out, owner, ownerAt) {
|
|
210
338
|
const base = child(ownerAt, "parameters");
|
|
211
339
|
arrayAt(owner.get("parameters"), base, "parameters").forEach((raw, i) => {
|
|
212
340
|
const pAt = child(base, String(i));
|
|
213
|
-
|
|
341
|
+
const described = refDescription(cx, raw);
|
|
342
|
+
cx.derefIn(raw, pAt, (p) => collectParam(cx, out, p, pAt, described));
|
|
214
343
|
});
|
|
215
344
|
}
|
|
216
345
|
/** Adds one parameter; header parameters OpenAPI reserves are left out, as it requires. */
|
|
217
|
-
function collectParam(cx, out, value, pAt) {
|
|
346
|
+
function collectParam(cx, out, value, pAt, described) {
|
|
218
347
|
const p = objectAt(value, pAt, "a parameter");
|
|
219
348
|
const name = p.str("name");
|
|
220
349
|
const loc = p.str("in");
|
|
@@ -229,7 +358,7 @@ function collectParam(cx, out, value, pAt) {
|
|
|
229
358
|
// Collected parameters all have a name.
|
|
230
359
|
const slot = out.findIndex(([q]) => q.str("in") === loc && same(q.str("name")));
|
|
231
360
|
// Its schema is converted later, against the document the parameter is in.
|
|
232
|
-
const param = [p, pAt, cx.base];
|
|
361
|
+
const param = [p, pAt, cx.base, doc(p, described)];
|
|
233
362
|
if (slot >= 0)
|
|
234
363
|
out[slot] = param;
|
|
235
364
|
else
|
|
@@ -312,9 +441,10 @@ function headers(cx, response, at) {
|
|
|
312
441
|
if (name.toLowerCase() === "content-type")
|
|
313
442
|
continue;
|
|
314
443
|
const hAt = child(base, name);
|
|
444
|
+
const described = refDescription(cx, raw);
|
|
315
445
|
cx.derefIn(raw, hAt, (value) => {
|
|
316
446
|
const h = objectAt(value, hAt, "a header");
|
|
317
|
-
props.push(documented(name, paramType(cx, h, hAt, "header"), !booleanAt(h, hAt, "required"), doc(h)));
|
|
447
|
+
props.push(documented(name, paramType(cx, h, hAt, "header"), !booleanAt(h, hAt, "required"), doc(h, described)));
|
|
318
448
|
});
|
|
319
449
|
}
|
|
320
450
|
return props.length === 0 ? undefined : object(props);
|
|
@@ -322,29 +452,42 @@ function headers(cx, response, at) {
|
|
|
322
452
|
/**
|
|
323
453
|
* `{ "<media type>": T }` for a non-empty `content`, keeping every media type.
|
|
324
454
|
* A binary media type is `Blob` and a text one `string` whatever its schema says, as is
|
|
325
|
-
* a form
|
|
326
|
-
* is still converted so its errors are reported
|
|
455
|
+
* a form the client reads (`clientReads`, a path's response): that is what the client
|
|
456
|
+
* reads and sends. The schema is still converted so its errors are reported. The client
|
|
327
457
|
* reads a sequential media type (`application/jsonl`, `text/event-stream`) whole, as these
|
|
328
|
-
* rules say
|
|
458
|
+
* rules say; its `itemSchema` (3.2) types each item, `{ "<media type>": Item }` in `items`.
|
|
329
459
|
*/
|
|
330
|
-
function content(cx, owner, at) {
|
|
460
|
+
function content(cx, owner, at, clientReads) {
|
|
331
461
|
const declared = owner.get("content");
|
|
332
462
|
if (declared === undefined)
|
|
333
|
-
return
|
|
463
|
+
return {};
|
|
334
464
|
const base = child(at, "content");
|
|
335
465
|
const media = objectAt(declared, base, "content");
|
|
336
466
|
if (media.entries.length === 0)
|
|
337
|
-
return
|
|
338
|
-
|
|
467
|
+
return {};
|
|
468
|
+
const items = [];
|
|
469
|
+
const props = media.entries.map(([mt, raw]) => {
|
|
339
470
|
const mAt = child(base, mt);
|
|
471
|
+
// Bytes are bytes in a body a wildcard names, which is sent as it is, and in
|
|
472
|
+
// a multipart body's parts; elsewhere they are text in JSON or a form.
|
|
473
|
+
const pos = mt.startsWith("multipart/")
|
|
474
|
+
? "parts"
|
|
475
|
+
: mt.includes("*")
|
|
476
|
+
? "body"
|
|
477
|
+
: undefined;
|
|
340
478
|
const ty = mediaType(cx, raw, mAt, (m) => {
|
|
341
|
-
const
|
|
342
|
-
if (
|
|
343
|
-
schema(cx,
|
|
479
|
+
const item = cx.v32 ? m.get("itemSchema") : undefined;
|
|
480
|
+
if (item !== undefined)
|
|
481
|
+
items.push(prop(mt, schema(cx, item, child(mAt, "itemSchema"))));
|
|
344
482
|
const s = m.get("schema");
|
|
345
|
-
return s === undefined
|
|
483
|
+
return s === undefined
|
|
484
|
+
? UNKNOWN
|
|
485
|
+
: cx.withRaw(pos, () => schema(cx, s, child(mAt, "schema")));
|
|
346
486
|
});
|
|
347
|
-
const text = isTextMedia(mt) || (
|
|
487
|
+
const text = isTextMedia(mt) || (clientReads && isFormMedia(mt));
|
|
348
488
|
return prop(mt, isBinaryMedia(mt) ? BLOB : text ? STRING : ty);
|
|
349
|
-
})
|
|
489
|
+
});
|
|
490
|
+
return items.length === 0
|
|
491
|
+
? { content: object(props) }
|
|
492
|
+
: { content: object(props), items: object(items) };
|
|
350
493
|
}
|
package/dist/pointer.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { GenerateError } from "./error.ts";
|
|
2
|
-
import { type Value } from "./json.ts";
|
|
2
|
+
import { JsonObject, type Value } from "./json.ts";
|
|
3
3
|
import type { View } from "./ty.ts";
|
|
4
4
|
/**
|
|
5
5
|
* A problem at a location in the input: a JSON Pointer (`#/paths/~1users/get`), after
|
|
@@ -23,6 +23,15 @@ export interface Location {
|
|
|
23
23
|
/** The parsed document at an absolute URL (no fragment). Throws GenerateError for a document that does not parse, any other error when it cannot be read. */
|
|
24
24
|
load: (url: string) => Value;
|
|
25
25
|
}
|
|
26
|
+
/** What a `$ref` reaches: the value, the base URI it lives under, and where it is, for messages. */
|
|
27
|
+
interface Located {
|
|
28
|
+
value: Value;
|
|
29
|
+
base: string;
|
|
30
|
+
uri: string;
|
|
31
|
+
where: string;
|
|
32
|
+
}
|
|
33
|
+
/** Where bytes are bytes: a raw body, a multipart body (whose properties are its parts), a part. */
|
|
34
|
+
export type RawPosition = "body" | "parts" | "part";
|
|
26
35
|
/** A schema in another file that no component names, given a key of its own as if it were one. */
|
|
27
36
|
export interface Hoisted {
|
|
28
37
|
key: string;
|
|
@@ -68,6 +77,26 @@ export declare class Ctx {
|
|
|
68
77
|
constructor(root: Value, schemas?: ReadonlySet<string>, refSiblings?: boolean, location?: Location, looseNullable?: boolean);
|
|
69
78
|
warn(at: string, msg: string): void;
|
|
70
79
|
get warnings(): Diag[];
|
|
80
|
+
/**
|
|
81
|
+
* Where the schema converted next is: a raw body (a wildcard media type), a multipart
|
|
82
|
+
* body's parts, or one part. A binary string is a `Blob` there, and text elsewhere
|
|
83
|
+
* (inside JSON, a form, a parameter).
|
|
84
|
+
*/
|
|
85
|
+
raw: RawPosition | undefined;
|
|
86
|
+
/** Where the schema being converted is: `raw` when its conversion began. */
|
|
87
|
+
here: RawPosition | undefined;
|
|
88
|
+
/** Converts with `raw` as the position of the next schema, then restores it. */
|
|
89
|
+
withRaw<T>(pos: RawPosition | undefined, f: () => T): T;
|
|
90
|
+
/**
|
|
91
|
+
* The schemas around the one being converted whose keywords apply to the same value:
|
|
92
|
+
* it is their member (`allOf`, `if`, …) or `$ref` target, innermost last. A property's
|
|
93
|
+
* or item's schema is another value, with none around it.
|
|
94
|
+
*/
|
|
95
|
+
around: readonly JsonObject[];
|
|
96
|
+
/** Converts with `parent` around the schema converted next, then restores. */
|
|
97
|
+
withAround<T>(parent: JsonObject, f: () => T): T;
|
|
98
|
+
/** Converts a schema with what `withAround` gave it, or nothing, around it. */
|
|
99
|
+
inSchema<T>(f: () => T): T;
|
|
71
100
|
leftOutIn(v: Value): ReadonlySet<string>;
|
|
72
101
|
/** Converts `allOf` members knowing the properties the group leaves out. */
|
|
73
102
|
withLeftOut<T>(members: readonly Value[], keys: ReadonlySet<string>, f: () => T): T;
|
|
@@ -87,6 +116,22 @@ export declare class Ctx {
|
|
|
87
116
|
where(resource: string, fragment?: string): string;
|
|
88
117
|
/** Converts with `base` as the base URI, then restores the previous one. */
|
|
89
118
|
withBase<T>(base: string, f: () => T): T;
|
|
119
|
+
/**
|
|
120
|
+
* The schema resources a value was reached through, outermost first, after the
|
|
121
|
+
* document's own (JSON Schema 2020-12's dynamic scope): `$dynamicRef` reads it.
|
|
122
|
+
*/
|
|
123
|
+
scope: readonly string[];
|
|
124
|
+
/** Converts in a schema resource: with its base URI, and in the dynamic scope. */
|
|
125
|
+
inResource<T>(base: string, f: () => T): T;
|
|
126
|
+
/**
|
|
127
|
+
* The `$dynamicAnchor` of this name a `$dynamicRef` reaches in a dynamic scope: the
|
|
128
|
+
* outermost resource's, the document's first; undefined where none has one.
|
|
129
|
+
*/
|
|
130
|
+
dynamicTarget(name: string, scope?: readonly string[]): string | undefined;
|
|
131
|
+
/** Whether the document has `$dynamicAnchor`s and a value is reached through a resource of its own. */
|
|
132
|
+
get dynamicScope(): boolean;
|
|
133
|
+
/** Whether a URI names a `$dynamicAnchor`. */
|
|
134
|
+
isDynamicAnchor(uri: string): boolean;
|
|
90
135
|
/** The base URI inside a schema with `$id`, resolved against the current one. */
|
|
91
136
|
baseOf(id: string): string;
|
|
92
137
|
/**
|
|
@@ -95,16 +140,13 @@ export declare class Ctx {
|
|
|
95
140
|
* optionally followed by a pointer into it (`defs/a.yaml#/b`). Returns the value,
|
|
96
141
|
* the base URI it lives under, and where it is, for messages.
|
|
97
142
|
*/
|
|
98
|
-
locate(r: string, at: string):
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
uri: string;
|
|
102
|
-
where: string;
|
|
103
|
-
};
|
|
143
|
+
locate(r: string, at: string): Located;
|
|
144
|
+
/** Whether a schema is hoisted, by its URI. */
|
|
145
|
+
isHoisted(uri: string): boolean;
|
|
104
146
|
/** Whether a base URI is another file (not the document, nor an `$id` resource). */
|
|
105
147
|
isFile(base: string): boolean;
|
|
106
148
|
/** `locate`, or undefined where it would fail (the conversion reports the failure). */
|
|
107
|
-
tryLocate(r: string):
|
|
149
|
+
tryLocate(r: string): Located | undefined;
|
|
108
150
|
/**
|
|
109
151
|
* The key in `components.schemas` of a schema object, so references to it stay
|
|
110
152
|
* named: the component itself, or the target of a component that is only a `$ref`
|
|
@@ -122,3 +164,4 @@ export declare class Ctx {
|
|
|
122
164
|
enter(r: string): boolean;
|
|
123
165
|
leave(): void;
|
|
124
166
|
}
|
|
167
|
+
export {};
|