kanagata 0.4.0 → 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/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, equal, lit, object, opRef, prop, STRING, tuple, UNKNOWN, } from "./ty.js";
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
- if (root.get("webhooks") !== undefined)
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 has two types (the API sends a
33
- * webhook's request) but one `operations[id]`, which TypeScript cannot declare twice.
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 if (!equal(known.prop.ty, prop.ty))
42
- throw new DiagError(at, `operation ${JSON.stringify(id)} is also ${known.at}, as a path's and a webhook's, whose types differ; operations[${JSON.stringify(id)}] has one type`);
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 out;
53
+ return [];
49
54
  if (!(entries instanceof JsonObject))
50
55
  throw new DiagError(`#/${key}`, `${key} must be an object`);
51
- for (const [path, rawItem] of entries.entries) {
52
- // Paths may have specification extensions; webhooks is a plain map of names.
53
- if (key === "paths" && path.startsWith("x-"))
54
- continue;
55
- const itemAt = child(`#/${key}`, path);
56
- const methods = cx.derefIn(rawItem, itemAt, (value) => {
57
- const item = objectAt(value, itemAt, "a path item");
58
- const methods = [];
59
- for (const [method, op, opAt] of itemOperations(cx, item, itemAt)) {
60
- // A webhook is called by the API: it sends the request and reads the response.
61
- const sent = key === "webhooks" ? "read" : "write";
62
- // fetch cannot send a body with GET or HEAD (OpenAPI 3.0 has consumers ignore
63
- // one); a webhook's request is sent by the API, so it keeps its body.
64
- const body = key === "webhooks" || (method !== "get" && method !== "head");
65
- const ty = operation(cx, { item, itemAt, op, at: opAt, sent, body });
66
- const opDoc = doc(op);
67
- const id = op.get("operationId");
68
- if (id !== undefined && typeof id !== "string")
69
- throw new DiagError(child(opAt, "operationId"), "operationId must be a string");
70
- if (id !== undefined && id !== "") {
71
- addOperation(operations, id, op, documented(id, ty, false, opDoc), opAt);
72
- methods.push(prop(method, opRef(id)));
73
- }
74
- else {
75
- methods.push(documented(method, ty, false, opDoc));
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
- return methods;
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
- function operation(cx, { item, itemAt, op: o, at, sent, body: hasBody }) {
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, so it has none to choose.
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) ?? serverUrls(item, itemAt))
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
- collectParams(cx, params, item, itemAt);
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
- const optional = loc !== "path" && !booleanAt(p, pAt, "required");
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, doc(p)));
212
+ groups.push(documented(loc, ty, optional, pDoc));
144
213
  else
145
- props.push(documented(p.str("name"), ty, optional, doc(p)));
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)) ?? object([]);
166
- fields.push(documented("requestBody", object([prop("content", c)]), !booleanAt(body, bodyAt, "required"), doc(body)));
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
- const c = cx.inMode(received, () => content(cx, r, rAt));
184
- if (c !== undefined)
185
- parts.push(prop("content", c));
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`, as literals; a URL with variables (`{region}`) is
195
- * any string, since TypeScript cannot check the template.
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.includes("{") ? STRING : lit(JSON.stringify(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
- cx.derefIn(raw, pAt, (p) => collectParam(cx, out, p, pAt));
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 in a response (read view): that is what the client reads and sends. The schema
326
- * is still converted so its errors are reported, and so is `itemSchema` (3.2): the client
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, not item by item.
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 undefined;
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 undefined;
338
- return object(media.entries.map(([mt, raw]) => {
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 items = cx.v32 ? m.get("itemSchema") : undefined;
342
- if (items !== undefined)
343
- schema(cx, items, child(mAt, "itemSchema"));
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 ? UNKNOWN : schema(cx, s, child(mAt, "schema"));
483
+ return s === undefined
484
+ ? UNKNOWN
485
+ : cx.withRaw(pos, () => schema(cx, s, child(mAt, "schema")));
346
486
  });
347
- const text = isTextMedia(mt) || (cx.mode === "read" && isFormMedia(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
- value: Value;
100
- base: string;
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): ReturnType<Ctx["locate"]> | undefined;
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 {};