@speclynx/apidom-reference 5.2.4 → 5.2.5

package/types/dereference/strategies/arazzo-1/visitor.d.ts

@@ -1,5 +1,6 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
+import { type Schema$idIndex } from './selectors/uri.ts';
 import Reference from '../../../Reference.ts';
 import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
@@ -10,8 +11,10 @@ export interface Arazzo1DereferenceVisitorOptions {
     readonly reference: Reference;
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
+    readonly schema$idIndex?: Schema$idIndex;
     readonly ancestors?: AncestorLineage<Element>;
     readonly visited?: WeakSet<Element>;
+    readonly ancestorSchema$ids?: string[];
 }
 /**
  * @public
@@ -26,14 +29,27 @@ declare class Arazzo1DereferenceVisitor {
      */
     protected readonly baseURI: string;
     protected readonly options: ReferenceOptions;
+    /**
+     * Index of `$id`-bearing schemas per document, shared across nested visitors
+     * of a single dereference run so it never outlives mutations of the documents.
+     */
+    protected readonly schema$idIndex: Schema$idIndex;
     protected readonly visited: WeakSet<Element>;
+    /**
+     * `$id`s of the JSON Schema elements enclosing the traversal root within its
+     * document (outermost first). Empty when the root is the document itself; a
+     * nested visitor traversing a fragment is seeded with the `$id`s of the
+     * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
+     * against the same base as they would from the document root.
+     */
+    protected readonly ancestorSchema$ids: string[];
     /**
      * Tracks element ancestors across dive-deep traversal boundaries.
      * Used for cycle detection: if a referenced element is found in
      * the ancestor lineage, a circular reference is detected.
      */
     protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, ancestors, visited, }: Arazzo1DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, schema$idIndex, ancestors, visited, ancestorSchema$ids, }: Arazzo1DereferenceVisitorOptions);
     protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;

package/types/dereference/strategies/openapi-3-1/selectors/$anchor.d.ts

@@ -1,4 +1,5 @@
 import { Element } from '@speclynx/apidom-datamodel';
+import { type SchemaLocation } from '../util.ts';
 import EvaluationJsonSchema$anchorError from '../../../../errors/EvaluationJsonSchema$anchorError.ts';
 import InvalidJsonSchema$anchorError from '../../../../errors/InvalidJsonSchema$anchorError.ts';
 /**
@@ -13,10 +14,17 @@ export declare const uriToAnchor: (uri: string) => string;
  * @public
  */
 export declare const parse: (anchor: string) => string;
+/**
+ * Locates the schema identified by JSON Schema $anchor within ApiDOM fragment,
+ * along with the `$id`s of the schemas enclosing it, the search root included.
+ * @public
+ */
+export declare const locate: <T extends Element>(anchor: string, element: T) => SchemaLocation;
 /**
  * Evaluates JSON Schema $anchor against ApiDOM fragment.
  * @public
  */
 export declare const evaluate: <T extends Element>(anchor: string, element: T) => Element | undefined;
+export type { SchemaLocation } from '../util.ts';
 export { EvaluationJsonSchema$anchorError, InvalidJsonSchema$anchorError };
 export { default as JsonSchema$anchorError } from '../../../../errors/JsonSchema$anchorError.ts';

package/types/dereference/strategies/openapi-3-1/selectors/json-pointer.d.ts

@@ -0,0 +1,9 @@
+import { Element } from '@speclynx/apidom-datamodel';
+import { type JSONPointer } from '@speclynx/apidom-json-pointer';
+import { type SchemaLocation } from '../util.ts';
+/**
+ * Locates the element addressed by JSON Pointer within ApiDOM fragment, along
+ * with the `$id`s of the schemas enclosing it: the elements the pointer walks
+ * through on its way to the target, the search root included.
+ */
+export declare const locate: <T extends Element>(element: T, jsonPointer: JSONPointer) => SchemaLocation;

package/types/dereference/strategies/openapi-3-1/selectors/uri.d.ts

@@ -1,12 +1,45 @@
 import { Element } from '@speclynx/apidom-datamodel';
+import { JSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
 import EvaluationJsonSchemaUriError from '../../../../errors/EvaluationJsonSchemaUriError.ts';
+import { type SchemaLocation } from '../util.ts';
+/**
+ * Index of `$id`-bearing schemas per indexed element (a document root, or the
+ * fragment a visitor traverses). Each entry pairs a schema with the `$id`s of its
+ * enclosing schema resources (outermost first, including its own). The index is
+ * populated once per element and never refreshed, so callers scope it
+ * to a single dereference/bundle run instead of sharing it globally. Within a run the
+ * `$id` graph of an indexed document is stable: the bundle strategies mutate deep
+ * clones and place components only after the entry traversal ends, and the
+ * dereference strategies only replace `$ref`-bearing schemas.
+ * @public
+ */
+export type Schema$idIndex = WeakMap<Element, {
+    schema: JSONSchemaElement;
+    $ids: string[];
+}[]>;
+/**
+ * @public
+ */
+export interface EvaluateOptions {
+    /**
+     * URI the `$id`s of the document resolve against (its retrieval URI or `$self`).
+     * Defaults to the evaluated URI itself, which only matches schemas identified by an
+     * absolute `$id`; pass the document's base URI to match relative `$id`s correctly.
+     */
+    readonly baseURI?: string;
+    readonly index?: Schema$idIndex;
+}
+/**
+ * Locates the schema addressed by JSON Schema $ref containing unknown URI within
+ * ApiDOM fragment, along with the `$id`s of the schemas enclosing it.
+ * @public
+ */
+export declare const locate: <T extends Element>(uri: string, element: T, options?: EvaluateOptions) => SchemaLocation;
 /**
  * Evaluates JSON Schema $ref containing unknown URI against ApiDOM fragment.
  * @public
  */
-export declare const evaluate: {
-    <T extends Element>(uri: string, element: T): Element | undefined;
-    cache: WeakMap<WeakKey, any>;
-};
+export declare const evaluate: <T extends Element>(uri: string, element: T, options?: EvaluateOptions) => Element | undefined;
+export type { SchemaLocation } from '../util.ts';
 export { EvaluationJsonSchemaUriError };
 export { default as JsonSchemaUriError } from '../../../../errors/JsonSchemaUriError.ts';

package/types/dereference/strategies/openapi-3-1/util.d.ts

@@ -1,13 +1,64 @@
 import { Element } from '@speclynx/apidom-datamodel';
+import type { Path } from '@speclynx/apidom-traverse';
 import { JSONSchemaElement } from '@speclynx/apidom-ns-json-schema-2020-12';
 /**
+ * A schema located within a document, together with the `$id`s of the JSON Schema
+ * elements enclosing it (outermost first; the located schema's own `$id` excluded).
  * @public
  */
-export declare const resolveSchema$refField: (retrievalURI: string, schemaElement: JSONSchemaElement) => string | undefined;
+export interface SchemaLocation {
+    readonly element: Element;
+    readonly ancestorSchema$ids: string[];
+}
 /**
+ * Whether the element is a JSON Schema element declaring a `$id`.
+ */
+export declare const isJSONSchemaElementWith$id: (element: unknown) => element is JSONSchemaElement;
+/**
+ * `$id`s declared by the JSON Schema elements among `nodes`, in order.
+ */
+export declare const schema$idsOf: (nodes: readonly unknown[]) => string[];
+/**
+ * `$id`s of the JSON Schema elements on `path` (outermost first, the node itself
+ * included). The `$id`s are read from the elements themselves rather than from
+ * refraction-time metadata, so a `$id` assigned after refraction (e.g. by the
+ * bundler) is honored.
+ */
+export declare const collectSchema$ids: (path: Path<Element>) => string[];
+/**
+ * `$id`s of the schemas enclosing a traversal root that is a fragment detached
+ * from its document, read from the `ancestorsSchemaIdentifiers` meta the JSON
+ * Schema refractors record. The meta also carries the root's own `$id`, which
+ * the ancestor walk contributes itself, so it is dropped. A detached fragment
+ * has no live ancestors, so the meta is the only carrier of its lexical
+ * context; this is the one reader of it the refractors must keep serving.
+ */
+export declare const detachedRootSchema$ids: (root: Element | undefined) => string[];
+/**
+ * Resolves a chain of `$id`s (outermost first) against `baseURI`, each `$id`
+ * refining the base the next one resolves against.
+ */
+export declare const resolveSchema$ids: (baseURI: string, $ids: readonly string[]) => string;
+/**
+ * Resolves the base URI of the schema at `path`: `baseURI` (the base URI in
+ * effect at the traversal root) refined by each `$id` on the schema's ancestor
+ * chain in turn, the schema's own `$id` included.
+ */
+export declare const resolveSchemaBaseURI: (baseURI: string, path: Path<Element>) => string;
+/**
+ * Resolves the `$ref` of the schema against its base URI (see
+ * `resolveSchemaBaseURI`), or returns `undefined` when the schema has no string `$ref`.
+ *
+ * @public
+ */
+export declare const resolveSchema$refField: (schemaBaseURI: string, schemaElement: JSONSchemaElement) => string | undefined;
+/**
+ * Resolves the `$id` of the schema against `baseURI`, the base URI in effect
+ * where the schema sits, or returns `undefined` when the schema declares no string `$id`.
+ *
  * @public
  */
-export declare const resolveSchema$idField: (retrievalURI: string, schemaElement: JSONSchemaElement) => string | undefined;
+export declare const resolveSchema$idField: (baseURI: string, schemaElement: JSONSchemaElement) => string | undefined;
 /**
  * Cached version of SchemaElement.refract.
  */

package/types/dereference/strategies/openapi-3-1/visitor.d.ts

@@ -1,5 +1,6 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
+import { type Schema$idIndex } from './selectors/uri.ts';
 import Reference from '../../../Reference.ts';
 import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
@@ -11,8 +12,10 @@ export interface OpenAPI3_1DereferenceVisitorOptions {
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
     readonly refractCache?: WeakMap<Element, Element>;
+    readonly schema$idIndex?: Schema$idIndex;
     readonly ancestors?: AncestorLineage<Element>;
     readonly visited?: WeakSet<Element>;
+    readonly ancestorSchema$ids?: string[];
 }
 /**
  * @public
@@ -22,14 +25,27 @@ declare class OpenAPI3_1DereferenceVisitor {
     protected readonly reference: Reference;
     protected readonly options: ReferenceOptions;
     protected readonly refractCache: WeakMap<Element, Element>;
+    /**
+     * Index of `$id`-bearing schemas per document, shared across nested visitors
+     * of a single dereference run so it never outlives mutations of the documents.
+     */
+    protected readonly schema$idIndex: Schema$idIndex;
     protected readonly visited: WeakSet<Element>;
+    /**
+     * `$id`s of the JSON Schema elements enclosing the traversal root within its
+     * document (outermost first). Empty when the root is the document itself; a
+     * nested visitor traversing a fragment is seeded with the `$id`s of the
+     * schemas the fragment sits under, so the `$ref`s and `$id`s within resolve
+     * against the same base as they would from the document root.
+     */
+    protected readonly ancestorSchema$ids: string[];
     /**
      * Tracks element ancestors across dive-deep traversal boundaries.
      * Used for cycle detection: if a referenced element is found in
      * the ancestor lineage, a circular reference is detected.
      */
     protected readonly ancestors: AncestorLineage<Element>;
-    constructor({ reference, options, indirections, refractCache, ancestors, visited, }: OpenAPI3_1DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, refractCache, schema$idIndex, ancestors, visited, ancestorSchema$ids, }: OpenAPI3_1DereferenceVisitorOptions);
     protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;

package/types/util/url.d.ts

@@ -96,6 +96,16 @@ export declare const cwd: () => string;
  * @public
  */
 export declare const resolve: (from: string, to: string) => string;
+/**
+ * Computes the URI reference that resolves to `to` against `from` — the inverse
+ * of `resolve`: `resolve(from, relative(from, to)) === to`. The reference is
+ * relative to the directory of `from` (its last path segment is the document,
+ * not a directory). When the two URIs differ in scheme or authority, or either
+ * has no hierarchical path (e.g. a URN), no relative form exists and `to` is
+ * returned unchanged.
+ * @public
+ */
+export declare const relative: (from: string, to: string) => string;
 /**
  * Sanitizes/Encodes URI to it's url encoded form.
  *