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/dist/pointer.js CHANGED
@@ -51,9 +51,15 @@ function indexIds(index, doc, base) {
51
51
  if (!index.ids.has(here))
52
52
  index.ids.set(here, v);
53
53
  }
54
- const anchor = v.str("$anchor");
55
- if (anchor !== undefined && !index.anchors.has(`${here}#${anchor}`))
56
- index.anchors.set(`${here}#${anchor}`, v);
54
+ // A $dynamicAnchor is a plain-name fragment too (JSON Schema 2020-12, 8.2.2).
55
+ for (const key of ["$anchor", "$dynamicAnchor"]) {
56
+ const anchor = v.str(key);
57
+ if (anchor !== undefined && !index.anchors.has(`${here}#${anchor}`))
58
+ index.anchors.set(`${here}#${anchor}`, v);
59
+ }
60
+ const dynamic = v.str("$dynamicAnchor");
61
+ if (dynamic !== undefined)
62
+ index.dynamic.add(`${here}#${dynamic}`);
57
63
  for (const [k, x] of v.entries) {
58
64
  if (!names && DATA.has(k))
59
65
  continue;
@@ -154,6 +160,56 @@ export class Ctx {
154
160
  get warnings() {
155
161
  return [...this.#warnings.values()];
156
162
  }
163
+ /**
164
+ * Where the schema converted next is: a raw body (a wildcard media type), a multipart
165
+ * body's parts, or one part. A binary string is a `Blob` there, and text elsewhere
166
+ * (inside JSON, a form, a parameter).
167
+ */
168
+ raw = undefined;
169
+ /** Where the schema being converted is: `raw` when its conversion began. */
170
+ here = undefined;
171
+ /** Converts with `raw` as the position of the next schema, then restores it. */
172
+ withRaw(pos, f) {
173
+ const saved = this.raw;
174
+ this.raw = pos;
175
+ try {
176
+ return f();
177
+ }
178
+ finally {
179
+ this.raw = saved;
180
+ }
181
+ }
182
+ /**
183
+ * The schemas around the one being converted whose keywords apply to the same value:
184
+ * it is their member (`allOf`, `if`, …) or `$ref` target, innermost last. A property's
185
+ * or item's schema is another value, with none around it.
186
+ */
187
+ around = [];
188
+ /** What `around` is for the schema converted next. */
189
+ #nextAround;
190
+ /** Converts with `parent` around the schema converted next, then restores. */
191
+ withAround(parent, f) {
192
+ const saved = this.#nextAround;
193
+ this.#nextAround = [...this.around, parent];
194
+ try {
195
+ return f();
196
+ }
197
+ finally {
198
+ this.#nextAround = saved;
199
+ }
200
+ }
201
+ /** Converts a schema with what `withAround` gave it, or nothing, around it. */
202
+ inSchema(f) {
203
+ const saved = this.around;
204
+ this.around = this.#nextAround ?? [];
205
+ this.#nextAround = undefined;
206
+ try {
207
+ return f();
208
+ }
209
+ finally {
210
+ this.around = saved;
211
+ }
212
+ }
157
213
  /** Properties left out of the current view by the other members of the `allOf` a schema is in. */
158
214
  #leftOut = new Map();
159
215
  leftOutIn(v) {
@@ -222,6 +278,41 @@ export class Ctx {
222
278
  this.base = saved;
223
279
  }
224
280
  }
281
+ /**
282
+ * The schema resources a value was reached through, outermost first, after the
283
+ * document's own (JSON Schema 2020-12's dynamic scope): `$dynamicRef` reads it.
284
+ */
285
+ scope = [];
286
+ /** Converts in a schema resource: with its base URI, and in the dynamic scope. */
287
+ inResource(base, f) {
288
+ const saved = this.scope;
289
+ if (base !== (this.scope[this.scope.length - 1] ?? this.documentBase))
290
+ this.scope = [...this.scope, base];
291
+ try {
292
+ return this.withBase(base, f);
293
+ }
294
+ finally {
295
+ this.scope = saved;
296
+ }
297
+ }
298
+ /**
299
+ * The `$dynamicAnchor` of this name a `$dynamicRef` reaches in a dynamic scope: the
300
+ * outermost resource's, the document's first; undefined where none has one.
301
+ */
302
+ dynamicTarget(name, scope = this.scope) {
303
+ const dynamic = this.#ids().dynamic;
304
+ return [this.documentBase, ...scope]
305
+ .map((r) => `${r}#${name}`)
306
+ .find((uri) => dynamic.has(uri));
307
+ }
308
+ /** Whether the document has `$dynamicAnchor`s and a value is reached through a resource of its own. */
309
+ get dynamicScope() {
310
+ return this.#ids().dynamic.size > 0 && this.scope.length > 0;
311
+ }
312
+ /** Whether a URI names a `$dynamicAnchor`. */
313
+ isDynamicAnchor(uri) {
314
+ return this.#ids().dynamic.has(uri);
315
+ }
225
316
  /** The base URI inside a schema with `$id`, resolved against the current one. */
226
317
  baseOf(id) {
227
318
  return withoutFragment(new URL(id, this.base));
@@ -233,6 +324,17 @@ export class Ctx {
233
324
  * the base URI it lives under, and where it is, for messages.
234
325
  */
235
326
  locate(r, at) {
327
+ // What a $ref reaches from a base never changes: it is found once.
328
+ const key = `${this.base} ${r}`;
329
+ let found = this.#located.get(key);
330
+ if (found === undefined) {
331
+ found = this.#find(r, at);
332
+ this.#located.set(key, found);
333
+ }
334
+ return found;
335
+ }
336
+ #located = new Map();
337
+ #find(r, at) {
236
338
  const url = new URL(r, this.base);
237
339
  const fragment = url.hash.slice(1);
238
340
  // A reference by the URL the document was read from still means the document.
@@ -249,11 +351,36 @@ export class Ctx {
249
351
  throw new DiagError(at, `$ref target not found: ${r}`);
250
352
  return {
251
353
  value,
252
- base: resource,
354
+ base: fragment.startsWith("/")
355
+ ? this.#within(doc, fragment, resource)
356
+ : resource,
253
357
  uri: `${resource}#${fragment}`,
254
358
  where: this.where(resource, fragment),
255
359
  };
256
360
  }
361
+ /**
362
+ * The base URI at a JSON Pointer into a document: the nearest `$id` on the way
363
+ * (3.1, 3.2), whose relative `$ref`s resolve against it, or the document's.
364
+ */
365
+ #within(doc, fragment, resource) {
366
+ if (!this.refSiblings)
367
+ return resource;
368
+ let base = resource;
369
+ let cur = doc;
370
+ // The pointer resolved, so every token names a member or an index.
371
+ for (const raw of fragment.slice(1).split("/")) {
372
+ const id = str(cur, "$id");
373
+ if (id !== undefined && URL.canParse(id, base))
374
+ base = withoutFragment(new URL(id, base));
375
+ const token = unescapeToken(raw);
376
+ cur = Array.isArray(cur) ? cur[Number(token)] : get(cur, token);
377
+ }
378
+ return base;
379
+ }
380
+ /** Whether a schema is hoisted, by its URI. */
381
+ isHoisted(uri) {
382
+ return this.#hoistedKeys.has(uri);
383
+ }
257
384
  /**
258
385
  * Loads another document, once, and indexes its `$id`s and `$anchor`s. It is known by
259
386
  * the URL it is read from: kanagata reads files, so another document's `$self` is not read.
@@ -295,7 +422,11 @@ export class Ctx {
295
422
  #ids() {
296
423
  if (this.#index !== undefined)
297
424
  return this.#index;
298
- const index = { ids: new Map(), anchors: new Map() };
425
+ const index = {
426
+ ids: new Map(),
427
+ anchors: new Map(),
428
+ dynamic: new Set(),
429
+ };
299
430
  indexIds(index, this.root, this.documentBase);
300
431
  this.#index = index;
301
432
  return index;
package/dist/schema.d.ts CHANGED
@@ -1,7 +1,15 @@
1
- import { type Value } from "./json.ts";
1
+ import { JsonObject, type Value } from "./json.ts";
2
2
  import { type Ctx } from "./pointer.ts";
3
3
  import { type Ty } from "./ty.ts";
4
4
  /** Converts a schema. */
5
5
  export declare function schema(cx: Ctx, v: Value, at: string): Ty;
6
- /** JSDoc text from `description` and `deprecated`. */
7
- export declare function doc(v: Value): string | undefined;
6
+ /**
7
+ * JSDoc text from an object's `description` and `deprecated`; `description` may be one
8
+ * that replaces the object's (next to the `$ref` that reached it, in 3.1 and 3.2).
9
+ */
10
+ export declare function doc(v: JsonObject, description?: string | undefined): string | undefined;
11
+ /**
12
+ * A schema's JSDoc: in 3.0 the keywords next to `$ref` are ignored, `deprecated` among
13
+ * them; `description` is read there too (docs/types.md).
14
+ */
15
+ export declare function schemaDoc(cx: Ctx, v: Value): string | undefined;