@speclynx/apidom-reference 3.0.0 → 3.2.0

package/src/errors/DereferenceError.cjs

@@ -6,5 +6,5 @@ var _apidomError = require("@speclynx/apidom-error");
 /**
  * @public
  */
-class DereferenceError extends _apidomError.ApiDOMError {}
+class DereferenceError extends _apidomError.ApiDOMStructuredError {}
 var _default = exports.default = DereferenceError;

package/src/errors/DereferenceError.mjs

@@ -1,7 +1,7 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 
 /**
  * @public
  */
-class DereferenceError extends ApiDOMError {}
+class DereferenceError extends ApiDOMStructuredError {}
 export default DereferenceError;

package/src/errors/ResolveError.cjs

@@ -6,5 +6,5 @@ var _apidomError = require("@speclynx/apidom-error");
 /**
  * @public
  */
-class ResolveError extends _apidomError.ApiDOMError {}
+class ResolveError extends _apidomError.ApiDOMStructuredError {}
 var _default = exports.default = ResolveError;

package/src/errors/ResolveError.mjs

@@ -1,7 +1,7 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 
 /**
  * @public
  */
-class ResolveError extends ApiDOMError {}
+class ResolveError extends ApiDOMStructuredError {}
 export default ResolveError;

package/src/errors/UnresolvableReferenceError.cjs

@@ -0,0 +1,11 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+exports.__esModule = true;
+exports.default = void 0;
+var _DereferenceError = _interopRequireDefault(require("./DereferenceError.cjs"));
+/**
+ * @public
+ */
+class UnresolvableReferenceError extends _DereferenceError.default {}
+var _default = exports.default = UnresolvableReferenceError;

package/src/errors/UnresolvableReferenceError.mjs

@@ -0,0 +1,6 @@
+import DereferenceError from "./DereferenceError.mjs";
+/**
+ * @public
+ */
+class UnresolvableReferenceError extends DereferenceError {}
+export default UnresolvableReferenceError;

package/src/index.cjs

@@ -3,7 +3,7 @@
 var _interopRequireWildcard = require("@babel/runtime-corejs3/helpers/interopRequireWildcard").default;
 var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
-exports.url = exports.resolveApiDOM = exports.resolve = exports.readFile = exports.parse = exports.options = exports.mergeOptions = exports.dereferenceApiDOM = exports.dereference = exports.bundle = exports.UnmatchedResolverError = exports.UnmatchedResolveStrategyError = exports.UnmatchedParserError = exports.UnmatchedDereferenceStrategyError = exports.UnmatchedBundleStrategyError = exports.ResolverError = exports.Resolver = exports.ResolveStrategy = exports.ResolveError = exports.Reference = exports.PluginError = exports.ParserError = exports.Parser = exports.ParseError = exports.MaximumResolveDepthError = exports.MaximumDereferenceDepthError = exports.MaximumBundleDepthError = exports.JsonSchemaURIError = exports.JsonSchema$anchorError = exports.InvalidJsonSchema$anchorError = exports.HTTPResolver = exports.EvaluationJsonSchemaUriError = exports.EvaluationJsonSchema$anchorError = exports.EvaluationElementIdError = exports.DereferenceStrategy = exports.DereferenceError = exports.DereferenceAncestorLineage = exports.BundleStrategy = exports.BundleError = void 0;
+exports.url = exports.resolveApiDOM = exports.resolve = exports.readFile = exports.parse = exports.options = exports.mergeOptions = exports.dereferenceApiDOM = exports.dereference = exports.bundle = exports.UnresolvableReferenceError = exports.UnmatchedResolverError = exports.UnmatchedResolveStrategyError = exports.UnmatchedParserError = exports.UnmatchedDereferenceStrategyError = exports.UnmatchedBundleStrategyError = exports.ResolverError = exports.Resolver = exports.ResolveStrategy = exports.ResolveError = exports.Reference = exports.PluginError = exports.ParserError = exports.Parser = exports.ParseError = exports.MaximumResolveDepthError = exports.MaximumDereferenceDepthError = exports.MaximumBundleDepthError = exports.JsonSchemaURIError = exports.JsonSchema$anchorError = exports.InvalidJsonSchema$anchorError = exports.HTTPResolver = exports.EvaluationJsonSchemaUriError = exports.EvaluationJsonSchema$anchorError = exports.EvaluationElementIdError = exports.DereferenceStrategy = exports.DereferenceError = exports.DereferenceAncestorLineage = exports.BundleStrategy = exports.BundleError = void 0;
 var _File = _interopRequireDefault(require("./File.cjs"));
 exports.File = _File.default;
 var _ReferenceSet = _interopRequireDefault(require("./ReferenceSet.cjs"));
@@ -43,6 +43,8 @@ var _UnmatchedBundleStrategyError = _interopRequireDefault(require("./errors/Unm
 exports.UnmatchedBundleStrategyError = _UnmatchedBundleStrategyError.default;
 var _DereferenceError = _interopRequireDefault(require("./errors/DereferenceError.cjs"));
 exports.DereferenceError = _DereferenceError.default;
+var _UnresolvableReferenceError = _interopRequireDefault(require("./errors/UnresolvableReferenceError.cjs"));
+exports.UnresolvableReferenceError = _UnresolvableReferenceError.default;
 var _EvaluationElementIdError = _interopRequireDefault(require("./errors/EvaluationElementIdError.cjs"));
 exports.EvaluationElementIdError = _EvaluationElementIdError.default;
 var _EvaluationJsonSchema$anchorError = _interopRequireDefault(require("./errors/EvaluationJsonSchema$anchorError.cjs"));

package/src/index.mjs

@@ -25,6 +25,7 @@ export { default as BundleError } from "./errors/BundleError.mjs";
 export { default as MaximumBundleDepthError } from "./errors/MaximumBundleDepthError.mjs";
 export { default as UnmatchedBundleStrategyError } from "./errors/UnmatchedBundleStrategyError.mjs";
 export { default as DereferenceError } from "./errors/DereferenceError.mjs";
+export { default as UnresolvableReferenceError } from "./errors/UnresolvableReferenceError.mjs";
 export { default as EvaluationElementIdError } from "./errors/EvaluationElementIdError.mjs";
 export { default as EvaluationJsonSchema$anchorError } from "./errors/EvaluationJsonSchema$anchorError.mjs";
 export { default as EvaluationJsonSchemaUriError } from "./errors/EvaluationJsonSchemaUriError.mjs";

package/src/options/index.cjs

@@ -150,7 +150,16 @@ const defaultOptions = {
      * true - the dereferencing process will be immutable (deep cloning of ApiDOM is involved)
      * false - the dereferencing process will be mutable
      */
-    immutable: true
+    immutable: true,
+    /**
+     * Controls error handling during dereferencing.
+     *
+     * false - fail fast, throw on first error (default)
+     * true - skip unresolvable references silently, continue dereferencing
+     * (error) => void - callback invoked for each error; if the callback
+     *   itself throws, dereferencing stops with that error
+     */
+    continueOnError: false
   },
   bundle: {
     /**

package/src/options/index.mjs

@@ -147,7 +147,16 @@ const defaultOptions = {
      * true - the dereferencing process will be immutable (deep cloning of ApiDOM is involved)
      * false - the dereferencing process will be mutable
      */
-    immutable: true
+    immutable: true,
+    /**
+     * Controls error handling during dereferencing.
+     *
+     * false - fail fast, throw on first error (default)
+     * true - skip unresolvable references silently, continue dereferencing
+     * (error) => void - callback invoked for each error; if the callback
+     *   itself throws, dereferencing stops with that error
+     */
+    continueOnError: false
   },
   bundle: {
     /**

package/src/util/plugins.cjs

@@ -1,10 +1,8 @@
 "use strict";
 
-var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
 exports.__esModule = true;
 exports.run = exports.filter = void 0;
 var _ramdaAdjunct = require("ramda-adjunct");
-var _PluginError = _interopRequireDefault(require("../errors/PluginError.cjs"));
 /**
  * Filters the given plugins, returning only the ones return `true` for the given method.
  */
@@ -33,10 +31,7 @@ const run = async (method, parameters, plugins) => {
         result
       };
     } catch (error) {
-      lastError = new _PluginError.default('Error while running plugin', {
-        cause: error,
-        plugin
-      });
+      lastError = error;
     }
   }
   return Promise.reject(lastError);

package/src/util/plugins.mjs

@@ -1,5 +1,5 @@
 import { invokeArgs } from 'ramda-adjunct';
-import PluginError from "../errors/PluginError.mjs";
+
 /**
  * Filters the given plugins, returning only the ones return `true` for the given method.
  */
@@ -27,10 +27,7 @@ export const run = async (method, parameters, plugins) => {
         result
       };
     } catch (error) {
-      lastError = new PluginError('Error while running plugin', {
-        cause: error,
-        plugin
-      });
+      lastError = error;
     }
   }
   return Promise.reject(lastError);

package/types/apidom-reference.d.ts

@@ -1,4 +1,5 @@
 import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 import { Element as Element_2 } from '@speclynx/apidom-datamodel';
 import { ParseResultElement } from '@speclynx/apidom-datamodel';
 import type { RefElement } from '@speclynx/apidom-datamodel';
@@ -23,6 +24,7 @@ export declare interface ApiDOMReferenceDereferenceOptions {
     circular: 'ignore' | 'replace' | 'error';
     circularReplacer: (ref: RefElement) => unknown;
     immutable: boolean;
+    continueOnError: boolean | ((error: UnresolvableReferenceError) => void);
 }
 
 /**
@@ -122,7 +124,7 @@ export declare const dereferenceApiDOM: <T extends Element_2>(element: T, option
 /**
  * @public
  */
-export declare class DereferenceError extends ApiDOMError {
+export declare class DereferenceError extends ApiDOMStructuredError {
 }
 
 /**
@@ -463,7 +465,7 @@ export declare const resolveApiDOM: <T extends Element_2>(element: T, options?:
 /**
  * @public
  */
-export declare class ResolveError extends ApiDOMError {
+export declare class ResolveError extends ApiDOMStructuredError {
 }
 
 /**
@@ -566,6 +568,12 @@ export declare class UnmatchedResolverError extends ResolverError {
 export declare class UnmatchedResolveStrategyError extends ResolveError {
 }
 
+/**
+ * @public
+ */
+export declare class UnresolvableReferenceError extends DereferenceError {
+}
+
 /**
  * Unsanitizes/Decodes URI to it's url encoded form.
  * This function already assumes that hash part of the URI

package/types/dereference/strategies/apidom/visitor.d.ts

@@ -28,6 +28,16 @@ declare class ApiDOMDereferenceVisitor {
     constructor({ reference, options }: ApiDOMDereferenceVisitorOptions);
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
+    /**
+     * Handles an error according to the continueOnError option.
+     *
+     * For new errors: wraps in UnresolvableReferenceError with structured context.
+     * 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).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string | null, refFieldValue: string, visitorPath: Path<Element>): void;
     RefElement(path: Path<Element>): Promise<void>;
 }
 export default ApiDOMDereferenceVisitor;

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

@@ -1,4 +1,4 @@
-import { Element, Namespace } from '@speclynx/apidom-datamodel';
+import { Element } from '@speclynx/apidom-datamodel';
 import { Path } from '@speclynx/apidom-traverse';
 import Reference from '../../../Reference.ts';
 import { AncestorLineage } from '../../util.ts';
@@ -7,7 +7,6 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * @public
  */
 export interface Arazzo1DereferenceVisitorOptions {
-    readonly namespace: Namespace;
     readonly reference: Reference;
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
@@ -18,14 +17,29 @@ export interface Arazzo1DereferenceVisitorOptions {
  */
 declare class Arazzo1DereferenceVisitor {
     protected readonly indirections: Element[];
-    protected readonly namespace: Namespace;
     protected readonly reference: Reference;
     protected readonly options: ReferenceOptions;
+    /**
+     * 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, namespace, options, indirections, ancestors, }: Arazzo1DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, ancestors, }: Arazzo1DereferenceVisitorOptions);
+    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<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).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
     ReusableElement(path: Path<Element>): void;
     JSONSchemaElement(path: Path<Element>): Promise<void>;
 }

package/types/dereference/strategies/asyncapi-2/visitor.d.ts

@@ -1,4 +1,4 @@
-import { Namespace, Element } from '@speclynx/apidom-datamodel';
+import { Element } from '@speclynx/apidom-datamodel';
 import { Path } from '@speclynx/apidom-traverse';
 import { AncestorLineage } from '../../util.ts';
 import Reference from '../../../Reference.ts';
@@ -7,27 +7,41 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * @public
  */
 export interface AsyncAPI2DereferenceVisitorOptions {
-    readonly namespace: Namespace;
     readonly reference: Reference;
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
+    readonly refractCache?: WeakMap<Element, Element>;
     readonly ancestors?: AncestorLineage<Element>;
-    readonly refractCache?: Map<string, Element>;
 }
 /**
  * @public
  */
 declare class AsyncAPI2DereferenceVisitor {
     protected readonly indirections: Element[];
-    protected readonly namespace: Namespace;
     protected readonly reference: Reference;
     protected readonly options: ReferenceOptions;
+    protected readonly refractCache: WeakMap<Element, 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.
+     */
     protected readonly ancestors: AncestorLineage<Element>;
-    protected readonly refractCache: Map<string, Element>;
-    constructor({ reference, namespace, options, indirections, ancestors, refractCache, }: AsyncAPI2DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, ancestors, refractCache, }: AsyncAPI2DereferenceVisitorOptions);
+    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<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).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
     ReferenceElement(path: Path<Element>): Promise<void>;
     ChannelItemElement(path: Path<Element>): Promise<void>;
 }

package/types/dereference/strategies/openapi-2/visitor.d.ts

@@ -1,34 +1,47 @@
-import { Element, Namespace } from '@speclynx/apidom-datamodel';
+import { Element } from '@speclynx/apidom-datamodel';
 import { Path } from '@speclynx/apidom-traverse';
 import { AncestorLineage } from '../../util.ts';
 import Reference from '../../../Reference.ts';
 import type { ReferenceOptions } from '../../../options/index.ts';
-import { AsyncAPI2DereferenceVisitorOptions } from '../asyncapi-2/visitor.ts';
 /**
  * @public
  */
 export interface OpenAPI2DereferenceVisitorOptions {
-    readonly namespace: Namespace;
     readonly reference: Reference;
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
+    readonly refractCache?: WeakMap<Element, Element>;
     readonly ancestors?: AncestorLineage<Element>;
-    readonly refractCache?: Map<string, Element>;
 }
 /**
  * @public
  */
 declare class OpenAPI2DereferenceVisitor {
     protected readonly indirections: Element[];
-    protected readonly namespace: Namespace;
     protected readonly reference: Reference;
     protected readonly options: ReferenceOptions;
+    protected readonly refractCache: WeakMap<Element, 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.
+     */
     protected readonly ancestors: AncestorLineage<Element>;
-    protected readonly refractCache: Map<string, Element>;
-    constructor({ reference, namespace, options, indirections, ancestors, refractCache, }: AsyncAPI2DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, ancestors, refractCache, }: OpenAPI2DereferenceVisitorOptions);
+    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<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).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     JSONReferenceElement(path: Path<Element>): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { Element, Namespace } from '@speclynx/apidom-datamodel';
+import { Element } from '@speclynx/apidom-datamodel';
 import { Path } from '@speclynx/apidom-traverse';
 import Reference from '../../../Reference.ts';
 import { AncestorLineage } from '../../util.ts';
@@ -7,27 +7,41 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * @public
  */
 export interface OpenAPI3_0DereferenceVisitorOptions {
-    readonly namespace: Namespace;
     readonly reference: Reference;
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
+    readonly refractCache?: WeakMap<Element, Element>;
     readonly ancestors?: AncestorLineage<Element>;
-    readonly refractCache?: Map<string, Element>;
 }
 /**
  * @public
  */
 declare class OpenAPI3_0DereferenceVisitor {
     protected readonly indirections: Element[];
-    protected readonly namespace: Namespace;
     protected readonly reference: Reference;
     protected readonly options: ReferenceOptions;
+    protected readonly refractCache: WeakMap<Element, 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.
+     */
     protected readonly ancestors: AncestorLineage<Element>;
-    protected readonly refractCache: Map<string, Element>;
-    constructor({ reference, namespace, options, indirections, ancestors, refractCache, }: OpenAPI3_0DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, ancestors, refractCache, }: OpenAPI3_0DereferenceVisitorOptions);
+    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<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).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     LinkElement(path: Path<Element>): Promise<void>;

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

@@ -1,4 +1,4 @@
-import { Element, Namespace } from '@speclynx/apidom-datamodel';
+import { Element } from '@speclynx/apidom-datamodel';
 import { Path } from '@speclynx/apidom-traverse';
 import Reference from '../../../Reference.ts';
 import { AncestorLineage } from '../../util.ts';
@@ -7,27 +7,41 @@ import type { ReferenceOptions } from '../../../options/index.ts';
  * @public
  */
 export interface OpenAPI3_1DereferenceVisitorOptions {
-    readonly namespace: Namespace;
     readonly reference: Reference;
     readonly options: ReferenceOptions;
     readonly indirections?: Element[];
+    readonly refractCache?: WeakMap<Element, Element>;
     readonly ancestors?: AncestorLineage<Element>;
-    readonly refractCache?: Map<string, Element>;
 }
 /**
  * @public
  */
 declare class OpenAPI3_1DereferenceVisitor {
     protected readonly indirections: Element[];
-    protected readonly namespace: Namespace;
     protected readonly reference: Reference;
     protected readonly options: ReferenceOptions;
+    protected readonly refractCache: WeakMap<Element, 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.
+     */
     protected readonly ancestors: AncestorLineage<Element>;
-    protected readonly refractCache: Map<string, Element>;
-    constructor({ reference, namespace, options, indirections, ancestors, refractCache, }: OpenAPI3_1DereferenceVisitorOptions);
+    constructor({ reference, options, indirections, refractCache, ancestors, }: OpenAPI3_1DereferenceVisitorOptions);
+    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<Element>];
     protected toBaseURI(uri: string): string;
     protected toReference(uri: string): Promise<Reference>;
-    protected toAncestorLineage(path: Path<Element>): [AncestorLineage<Element>, Set<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).
+     */
+    protected handleError(message: string, error: Error, referencingElement: Element, refFieldName: string, refFieldValue: string, visitorPath: Path<Element>): void;
     ReferenceElement(path: Path<Element>): Promise<void>;
     PathItemElement(path: Path<Element>): Promise<void>;
     LinkElement(path: Path<Element>): Promise<void>;

package/types/errors/DereferenceError.d.ts

@@ -1,7 +1,7 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 /**
  * @public
  */
-declare class DereferenceError extends ApiDOMError {
+declare class DereferenceError extends ApiDOMStructuredError {
 }
 export default DereferenceError;

package/types/errors/ResolveError.d.ts

@@ -1,7 +1,7 @@
-import { ApiDOMError } from '@speclynx/apidom-error';
+import { ApiDOMStructuredError } from '@speclynx/apidom-error';
 /**
  * @public
  */
-declare class ResolveError extends ApiDOMError {
+declare class ResolveError extends ApiDOMStructuredError {
 }
 export default ResolveError;

package/types/errors/UnresolvableReferenceError.d.ts

@@ -0,0 +1,7 @@
+import DereferenceError from './DereferenceError.ts';
+/**
+ * @public
+ */
+declare class UnresolvableReferenceError extends DereferenceError {
+}
+export default UnresolvableReferenceError;

package/types/index.d.ts

@@ -29,6 +29,7 @@ export { default as BundleError } from './errors/BundleError.ts';
 export { default as MaximumBundleDepthError } from './errors/MaximumBundleDepthError.ts';
 export { default as UnmatchedBundleStrategyError } from './errors/UnmatchedBundleStrategyError.ts';
 export { default as DereferenceError } from './errors/DereferenceError.ts';
+export { default as UnresolvableReferenceError } from './errors/UnresolvableReferenceError.ts';
 export { default as EvaluationElementIdError } from './errors/EvaluationElementIdError.ts';
 export { default as EvaluationJsonSchema$anchorError } from './errors/EvaluationJsonSchema$anchorError.ts';
 export { default as EvaluationJsonSchemaUriError } from './errors/EvaluationJsonSchemaUriError.ts';

package/types/options/index.d.ts

@@ -5,6 +5,7 @@ import type ResolveStrategy from '../resolve/strategies/ResolveStrategy.ts';
 import type DereferenceStrategy from '../dereference/strategies/DereferenceStrategy.ts';
 import type ReferenceSet from '../ReferenceSet.ts';
 import type BundleStrategy from '../bundle/strategies/BundleStrategy.ts';
+import type UnresolvableReferenceError from '../errors/UnresolvableReferenceError.ts';
 /**
  * @public
  */
@@ -37,6 +38,7 @@ export interface ReferenceDereferenceOptions {
     circular: 'ignore' | 'replace' | 'error';
     circularReplacer: (ref: RefElement) => unknown;
     immutable: boolean;
+    continueOnError: boolean | ((error: UnresolvableReferenceError) => void);
 }
 /**
  * @public