@speclynx/apidom-reference 6.2.0 → 7.0.0

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

@@ -1,65 +1,69 @@
 import { Element } from '@speclynx/apidom-datamodel';
 import { type Path } from '@speclynx/apidom-traverse';
 import { type Schema$idIndex } from './selectors/uri.ts';
+import DereferenceVisitor from '../DereferenceVisitor.ts';
 import Reference from '../../../Reference.ts';
-import { AncestorLineage } from '../../util.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
+/**
+ * Context of a source being dereferenced: the `$id`s of the Schema Objects enclosing it.
+ */
+interface OpenAPI3_1DereferenceContext {
+    readonly ancestorSchema$ids: string[];
+}
 /**
  * @public
  */
 export interface OpenAPI3_1DereferenceVisitorOptions {
     readonly reference: Reference;
     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[];
 }
 /**
+ * Dereferences an OpenAPI 3.1 document. Reference Objects expect the type of their
+ * `referenced-element` meta, Path Item `$ref`s a Path Item, Schema Object `$ref`s a Schema Object.
+ * Link Objects get the Operation Object they point at attached, Example Objects
+ * the external value.
+ *
  * @public
  */
-declare class OpenAPI3_1DereferenceVisitor {
-    protected readonly indirections: Element[];
-    protected readonly reference: Reference;
-    protected readonly options: ReferenceOptions;
-    protected readonly refractCache: WeakMap<Element, Element>;
+declare class OpenAPI3_1DereferenceVisitor extends DereferenceVisitor<OpenAPI3_1DereferenceContext> {
     /**
-     * Index of `$id`-bearing schemas per document, shared across nested visitors
-     * of a single dereference run so it never outlives mutations of the documents.
+     * Index of `$id`-bearing schemas per document, shared across the visitors
+     * of a single dereference run.
      */
     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.
+     * 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[];
+    constructor({ reference, options, schema$idIndex, ancestorSchema$ids, }: OpenAPI3_1DereferenceVisitorOptions);
+    protected get strategyName(): string;
+    protected createVisitor(reference: Reference, { ancestorSchema$ids }: OpenAPI3_1DereferenceContext): OpenAPI3_1DereferenceVisitor;
+    /**
+     * A Reference Object stands for the type its reference expects: it's dereferenced as that type.
+     */
+    protected isOfType(element: Element, type: string): boolean;
+    /**
+     * A generic structure holding a `$ref` is a Reference Object to the expected type,
+     * unless the type has its own `$ref` field (Path Item Object, Schema Object).
+     */
+    protected refractTo(element: Element, type: string): Element;
     /**
-     * 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.
+     * A document as Schema Object for locating schemas within it: a generic document is
+     * refracted to Schema Object once per dereference run, a semantic one is used as it is.
      */
-    protected readonly ancestors: AncestorLineage<Element>;
-    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>;
+    protected toSchemaDocument(document: Element): Element;
     /**
-     * Handles an error according to the continueOnError option.
-     *
-     * For new errors: wraps in UnresolvableReferenceError with structured context
-     * (type, uri, location, codeFrame, refFieldName, refFieldValue, trace).
-     * For errors already wrapped by a nested visitor: prepends the current hop to the trace.
-     *
-     * Inner/intermediate visitors always throw to let the trace accumulate.
-     * Only the entry document visitor respects continueOnError (callback/swallow/throw).
+     * Indexes the `$id`-bearing schemas of an element for the run. Transcluded elements aren't
+     * indexed: they're copies of structures indexed where they're defined,
+     * and in a document dereferenced in place their shared structure would be walked once per path.
      */
-    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
+    protected index$ids(element: Element): void;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     LinkElement(path: Path<Element>): Promise<void>;

package/types/index.d.ts

@@ -13,7 +13,6 @@ export type { ResolverOptions } from './resolve/resolvers/Resolver.ts';
 export type { ResolveStrategyOptions } from './resolve/strategies/ResolveStrategy.ts';
 export { default as DereferenceStrategy } from './dereference/strategies/DereferenceStrategy.ts';
 export type { DereferenceStrategyOptions } from './dereference/strategies/DereferenceStrategy.ts';
-export { AncestorLineage as DereferenceAncestorLineage } from './dereference/util.ts';
 export { default as BundleStrategy } from './bundle/strategies/BundleStrategy.ts';
 export type { BundleStrategyOptions } from './bundle/strategies/BundleStrategy.ts';
 export type { ComponentNamesStrategy, ComponentNameResolver, ComponentNameResolverArgs, ComponentNameCollisionSeverity, } from './options/index.ts';

package/src/dereference/util.cjs

@@ -1,33 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.AncestorLineage = void 0;
-var _apidomDatamodel = require("@speclynx/apidom-datamodel");
-/**
- * @public
- */
-
-class AncestorLineage extends Array {
-  includesCycle(element) {
-    return this.filter(ancestors => ancestors.has(element)).length > 1;
-  }
-  includes(searchElement, fromIndex) {
-    if (searchElement instanceof Set) {
-      return super.includes(searchElement, fromIndex);
-    }
-    return this.some(ancestors => ancestors.has(searchElement));
-  }
-  findItem(predicate) {
-    for (const set of this) {
-      for (const item of set) {
-        if ((0, _apidomDatamodel.isElement)(item) && predicate(item)) {
-          return item;
-        }
-      }
-    }
-    return undefined;
-  }
-}
-exports.AncestorLineage = AncestorLineage;

package/src/dereference/util.mjs

@@ -1,27 +0,0 @@
-import { isElement } from '@speclynx/apidom-datamodel';
-
-/**
- * @public
- */
-
-export class AncestorLineage extends Array {
-  includesCycle(element) {
-    return this.filter(ancestors => ancestors.has(element)).length > 1;
-  }
-  includes(searchElement, fromIndex) {
-    if (searchElement instanceof Set) {
-      return super.includes(searchElement, fromIndex);
-    }
-    return this.some(ancestors => ancestors.has(searchElement));
-  }
-  findItem(predicate) {
-    for (const set of this) {
-      for (const item of set) {
-        if (isElement(item) && predicate(item)) {
-          return item;
-        }
-      }
-    }
-    return undefined;
-  }
-}

package/types/dereference/util.d.ts

@@ -1,9 +0,0 @@
-import { Element } from '@speclynx/apidom-datamodel';
-/**
- * @public
- */
-export declare class AncestorLineage<T extends Element> extends Array<Set<T>> {
-    includesCycle(element: T): boolean;
-    includes(searchElement: Set<T> | T, fromIndex?: number): boolean;
-    findItem(predicate: (item: T) => boolean): T | undefined;
-}