@apidevtools/json-schema-ref-parser 11.7.3 → 11.8.2

package/cjs/util/plugins.js

@@ -0,0 +1,159 @@
+/**
+ * Returns the given plugins as an array, rather than an object map.
+ * All other methods in this module expect an array of plugins rather than an object map.
+ *
+ * @param  {object} plugins - A map of plugin objects
+ * @return {object[]}
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    all: function() {
+        return all;
+    },
+    filter: function() {
+        return filter;
+    },
+    sort: function() {
+        return sort;
+    },
+    run: function() {
+        return run;
+    }
+});
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function all(plugins) {
+    return Object.keys(plugins).filter(function(key) {
+        return typeof plugins[key] === "object";
+    }).map(function(key) {
+        plugins[key].name = key;
+        return plugins[key];
+    });
+}
+function filter(plugins, method, file) {
+    return plugins.filter(function(plugin) {
+        return !!getResult(plugin, method, file);
+    });
+}
+function sort(plugins) {
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = plugins[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var plugin = _step.value;
+            plugin.order = plugin.order || Number.MAX_SAFE_INTEGER;
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+    return plugins.sort(function(a, b) {
+        return a.order - b.order;
+    });
+}
+function run(plugins, method, file, $refs) {
+    var plugin, lastError, index = 0;
+    return new Promise(function(resolve, reject) {
+        var runNextPlugin = function runNextPlugin() {
+            plugin = plugins[index++];
+            if (!plugin) {
+                // There are no more functions, so re-throw the last error
+                return reject(lastError);
+            }
+            try {
+                // console.log('  %s', plugin.name);
+                var result = getResult(plugin, method, file, callback, $refs);
+                if (result && typeof result.then === "function") {
+                    // A promise was returned
+                    result.then(onSuccess, onError);
+                } else if (result !== undefined) {
+                    // A synchronous result was returned
+                    onSuccess(result);
+                } else if (index === plugins.length) {
+                    throw new Error("No promise has been returned or callback has been called.");
+                }
+            } catch (e) {
+                onError(e);
+            }
+        };
+        var callback = function callback(err, result) {
+            if (err) {
+                onError(err);
+            } else {
+                onSuccess(result);
+            }
+        };
+        var onSuccess = function onSuccess(result) {
+            // console.log('    success');
+            resolve({
+                plugin: plugin,
+                result: result
+            });
+        };
+        var onError = function onError(error) {
+            // console.log('    %s', err.message || err);
+            lastError = {
+                plugin: plugin,
+                error: error
+            };
+            runNextPlugin();
+        };
+        runNextPlugin();
+    });
+}
+/**
+ * Returns the value of the given property.
+ * If the property is a function, then the result of the function is returned.
+ * If the value is a RegExp, then it will be tested against the file URL.
+ * If the value is an aray, then it will be compared against the file extension.
+ *
+ * @param   {object}   obj        - The object whose property/method is called
+ * @param   {string}   prop       - The name of the property/method to invoke
+ * @param   {object}   file       - A file info object, which will be passed to the method
+ * @param   {function} [callback] - A callback function, which will be passed to the method
+ * @returns {*}
+ */ function getResult(obj, prop, file, callback, $refs) {
+    var value = obj[prop];
+    if (typeof value === "function") {
+        return value.apply(obj, [
+            file,
+            callback,
+            $refs
+        ]);
+    }
+    if (!callback) {
+        // The synchronous plugin functions (canParse and canRead)
+        // allow a "shorthand" syntax, where the user can match
+        // files by RegExp or by file extension.
+        if (_instanceof(value, RegExp)) {
+            return value.test(file.url);
+        } else if (typeof value === "string") {
+            return value === file.extension;
+        } else if (Array.isArray(value)) {
+            return value.indexOf(file.extension) !== -1;
+        }
+    }
+    return value;
+}

package/cjs/util/projectDir.cjs

@@ -0,0 +1,6 @@
+const nodePath = require("path");
+
+// Webpack 4 (used by browser tests) can't transpile import.meta.url
+// So export the project directory using __dirname from a .cjs module
+const projectDir = nodePath.resolve(__dirname, "..", "..");
+module.exports = projectDir

package/cjs/util/url.js

@@ -0,0 +1,228 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    parse: function() {
+        return parse;
+    },
+    resolve: function() {
+        return resolve;
+    },
+    cwd: function() {
+        return cwd;
+    },
+    getProtocol: function() {
+        return getProtocol;
+    },
+    getExtension: function() {
+        return getExtension;
+    },
+    stripQuery: function() {
+        return stripQuery;
+    },
+    getHash: function() {
+        return getHash;
+    },
+    stripHash: function() {
+        return stripHash;
+    },
+    isHttp: function() {
+        return isHttp;
+    },
+    isFileSystemPath: function() {
+        return isFileSystemPath;
+    },
+    fromFileSystemPath: function() {
+        return fromFileSystemPath;
+    },
+    toFileSystemPath: function() {
+        return toFileSystemPath;
+    },
+    safePointerToPath: function() {
+        return safePointerToPath;
+    }
+});
+var _projectDirCjs = /*#__PURE__*/ _interopRequireDefault(require("./projectDir.cjs"));
+function _interopRequireDefault(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+var isWindows = /^win/.test(globalThis.process ? globalThis.process.platform : undefined), forwardSlashPattern = /\//g, protocolPattern = /^(\w{2,}):\/\//i, jsonPointerSlash = /~1/g, jsonPointerTilde = /~0/g;
+// RegExp patterns to URL-encode special characters in local filesystem paths
+var urlEncodePatterns = [
+    /\?/g,
+    "%3F",
+    /\#/g,
+    "%23"
+];
+// RegExp patterns to URL-decode special characters for local filesystem paths
+var urlDecodePatterns = [
+    /\%23/g,
+    "#",
+    /\%24/g,
+    "$",
+    /\%26/g,
+    "&",
+    /\%2C/g,
+    ",",
+    /\%40/g,
+    "@"
+];
+var parse = function(u) {
+    return new URL(u);
+};
+function resolve(from, to) {
+    var resolvedUrl = new URL(to, new URL(from, "resolve://"));
+    if (resolvedUrl.protocol === "resolve:") {
+        // `from` is a relative URL.
+        var pathname = resolvedUrl.pathname, search = resolvedUrl.search, hash = resolvedUrl.hash;
+        return pathname + search + hash;
+    }
+    return resolvedUrl.toString();
+}
+function cwd() {
+    if (typeof window !== "undefined") {
+        return location.href;
+    }
+    var path = process.cwd();
+    var lastChar = path.slice(-1);
+    if (lastChar === "/" || lastChar === "\\") {
+        return path;
+    } else {
+        return path + "/";
+    }
+}
+function getProtocol(path) {
+    var match = protocolPattern.exec(path);
+    if (match) {
+        return match[1].toLowerCase();
+    }
+}
+function getExtension(path) {
+    var lastDot = path.lastIndexOf(".");
+    if (lastDot >= 0) {
+        return stripQuery(path.substr(lastDot).toLowerCase());
+    }
+    return "";
+}
+function stripQuery(path) {
+    var queryIndex = path.indexOf("?");
+    if (queryIndex >= 0) {
+        path = path.substr(0, queryIndex);
+    }
+    return path;
+}
+function getHash(path) {
+    var hashIndex = path.indexOf("#");
+    if (hashIndex >= 0) {
+        return path.substr(hashIndex);
+    }
+    return "#";
+}
+function stripHash(path) {
+    var hashIndex = path.indexOf("#");
+    if (hashIndex >= 0) {
+        path = path.substr(0, hashIndex);
+    }
+    return path;
+}
+function isHttp(path) {
+    var protocol = getProtocol(path);
+    if (protocol === "http" || protocol === "https") {
+        return true;
+    } else if (protocol === undefined) {
+        // There is no protocol.  If we're running in a browser, then assume it's HTTP.
+        return typeof window !== "undefined";
+    } else {
+        // It's some other protocol, such as "ftp://", "mongodb://", etc.
+        return false;
+    }
+}
+function isFileSystemPath(path) {
+    if (process.browser) {
+        // We're running in a browser, so assume that all paths are URLs.
+        // This way, even relative paths will be treated as URLs rather than as filesystem paths
+        return false;
+    }
+    var protocol = getProtocol(path);
+    return protocol === undefined || protocol === "file";
+}
+function fromFileSystemPath(path) {
+    // Step 1: On Windows, replace backslashes with forward slashes,
+    // rather than encoding them as "%5C"
+    if (isWindows) {
+        var hasProjectDir = path.toUpperCase().includes(_projectDirCjs.default.replace(/\\/g, "\\").toUpperCase());
+        var hasProjectUri = path.toUpperCase().includes(_projectDirCjs.default.replace(/\\/g, "/").toUpperCase());
+        if (hasProjectDir || hasProjectUri) {
+            path = path.replace(/\\/g, "/");
+        } else {
+            path = "".concat(_projectDirCjs.default, "/").concat(path).replace(/\\/g, "/");
+        }
+    }
+    // Step 2: `encodeURI` will take care of MOST characters
+    path = encodeURI(path);
+    // Step 3: Manually encode characters that are not encoded by `encodeURI`.
+    // This includes characters such as "#" and "?", which have special meaning in URLs,
+    // but are just normal characters in a filesystem path.
+    for(var i = 0; i < urlEncodePatterns.length; i += 2){
+        path = path.replace(urlEncodePatterns[i], urlEncodePatterns[i + 1]);
+    }
+    return path;
+}
+function toFileSystemPath(path, keepFileProtocol) {
+    // Step 1: `decodeURI` will decode characters such as Cyrillic characters, spaces, etc.
+    path = decodeURI(path);
+    // Step 2: Manually decode characters that are not decoded by `decodeURI`.
+    // This includes characters such as "#" and "?", which have special meaning in URLs,
+    // but are just normal characters in a filesystem path.
+    for(var i = 0; i < urlDecodePatterns.length; i += 2){
+        path = path.replace(urlDecodePatterns[i], urlDecodePatterns[i + 1]);
+    }
+    // Step 3: If it's a "file://" URL, then format it consistently
+    // or convert it to a local filesystem path
+    var isFileUrl = path.substr(0, 7).toLowerCase() === "file://";
+    if (isFileUrl) {
+        // Strip-off the protocol, and the initial "/", if there is one
+        path = path[7] === "/" ? path.substr(8) : path.substr(7);
+        // insert a colon (":") after the drive letter on Windows
+        if (isWindows && path[1] === "/") {
+            path = path[0] + ":" + path.substr(1);
+        }
+        if (keepFileProtocol) {
+            // Return the consistently-formatted "file://" URL
+            path = "file:///" + path;
+        } else {
+            // Convert the "file://" URL to a local filesystem path.
+            // On Windows, it will start with something like "C:/".
+            // On Posix, it will start with "/"
+            isFileUrl = false;
+            path = isWindows ? path : "/" + path;
+        }
+    }
+    // Step 4: Normalize Windows paths (unless it's a "file://" URL)
+    if (isWindows && !isFileUrl) {
+        // Replace forward slashes with backslashes
+        path = path.replace(forwardSlashPattern, "\\");
+        // Capitalize the drive letter
+        if (path.substr(1, 2) === ":\\") {
+            path = path[0].toUpperCase() + path.substr(1);
+        }
+    }
+    return path;
+}
+function safePointerToPath(pointer) {
+    if (pointer.length <= 1 || pointer[0] !== "#" || pointer[1] !== "/") {
+        return [];
+    }
+    return pointer.slice(2).split("/").map(function(value) {
+        return decodeURIComponent(value).replace(jsonPointerSlash, "/").replace(jsonPointerTilde, "~");
+    });
+}

package/dist/lib/dereference.js

@@ -210,7 +210,8 @@ function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, de
 }
 /**
  * Called when a circular reference is found.
- * It sets the {@link $Refs#circular} flag, and throws an error if options.dereference.circular is false.
+ * It sets the {@link $Refs#circular} flag, executes the options.dereference.onCircular callback,
+ * and throws an error if options.dereference.circular is false.
  *
  * @param keyPath - The JSON Reference path of the circular reference
  * @param $refs
@@ -219,6 +220,7 @@ function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, de
  */
 function foundCircularReference(keyPath, $refs, options) {
     $refs.circular = true;
+    options?.dereference?.onCircular?.(keyPath);
     if (!options.dereference.circular) {
         throw ono_1.ono.reference(`Circular $ref pointer found at ${keyPath}`);
     }

package/dist/lib/index.d.ts

@@ -44,8 +44,8 @@ export declare class $RefParser<S extends object = JSONSchema, O extends ParserO
     parse(schema: S | string | unknown, options: O, callback: SchemaCallback<S>): Promise<void>;
     parse(baseUrl: string, schema: S | string | unknown, options: O): Promise<S>;
     parse(baseUrl: string, schema: S | string | unknown, options: O, callback: SchemaCallback<S>): Promise<void>;
-    static parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown): Promise<S>;
-    static parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
+    static parse<S extends object = JSONSchema>(schema: S | string | unknown): Promise<S>;
+    static parse<S extends object = JSONSchema>(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
     static parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, options: O): Promise<S>;
     static parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, options: O, callback: SchemaCallback<S>): Promise<void>;
     static parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(baseUrl: string, schema: S | string | unknown, options: O): Promise<S>;
@@ -95,8 +95,8 @@ export declare class $RefParser<S extends object = JSONSchema, O extends ParserO
      * @param options (optional)
      * @param callback (optional) A callback that will receive the bundled schema object
      */
-    static bundle<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown): Promise<S>;
-    static bundle<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
+    static bundle<S extends object = JSONSchema>(schema: S | string | unknown): Promise<S>;
+    static bundle<S extends object = JSONSchema>(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
     static bundle<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, options: O): Promise<S>;
     static bundle<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, options: O, callback: SchemaCallback<S>): Promise<void>;
     static bundle<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(baseUrl: string, schema: S | string | unknown, options: O): Promise<S>;
@@ -129,8 +129,8 @@ export declare class $RefParser<S extends object = JSONSchema, O extends ParserO
      * @param options (optional)
      * @param callback (optional) A callback that will receive the dereferenced schema object
      */
-    static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown): Promise<S>;
-    static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
+    static dereference<S extends object = JSONSchema>(schema: S | string | unknown): Promise<S>;
+    static dereference<S extends object = JSONSchema>(schema: S | string | unknown, callback: SchemaCallback<S>): Promise<void>;
     static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, options: O): Promise<S>;
     static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(schema: S | string | unknown, options: O, callback: SchemaCallback<S>): Promise<void>;
     static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(baseUrl: string, schema: S | string | unknown, options: O): Promise<S>;

package/dist/lib/options.d.ts

@@ -17,6 +17,12 @@ export interface DereferenceOptions {
      * subpaths contain literal $ref keys that should not be dereferenced.
      */
     excludedPathMatcher?(path: string): boolean;
+    /**
+     * Callback invoked during circular reference detection.
+     *
+     * @argument {string} path - The path that is circular (ie. the `$ref` string)
+     */
+    onCircular?(path: string): void;
     /**
      * Callback invoked during dereferencing.
      *
@@ -376,6 +382,7 @@ export declare const getNewOptions: <S extends object = JSONSchema, O extends Pa
     dereference?: {
         circular?: boolean | "ignore" | undefined;
         excludedPathMatcher?: {} | undefined;
+        onCircular?: {} | undefined;
         onDereference?: {} | undefined;
         externalReferenceResolution?: "relative" | "root" | undefined;
     } | undefined;

package/dist/lib/pointer.js

@@ -83,6 +83,7 @@ class Pointer {
      */
     resolve(obj, options, pathFromRoot) {
         const tokens = Pointer.parse(this.path, this.originalPath);
+        const found = [];
         // Crawl the object, one token at a time
         this.value = unwrapOrThrow(obj);
         for (let i = 0; i < tokens.length; i++) {
@@ -110,11 +111,16 @@ class Pointer {
                     continue;
                 }
                 this.value = null;
-                throw new errors_js_1.MissingPointerError(token, decodeURI(this.originalPath));
+                const path = this.$ref.path || "";
+                const targetRef = this.path.replace(path, "");
+                const targetFound = Pointer.join("", found);
+                const parentPath = pathFromRoot?.replace(path, "");
+                throw new errors_js_1.MissingPointerError(token, decodeURI(this.originalPath), targetRef, targetFound, parentPath);
             }
             else {
                 this.value = this.value[token];
             }
+            found.push(token);
         }
         // Resolve the final value
         if (!this.value || (this.value.$ref && url.resolve(this.path, this.value.$ref) !== pathFromRoot)) {

package/dist/lib/util/errors.d.ts

@@ -41,7 +41,11 @@ export declare class UnmatchedResolverError extends JSONParserError {
 export declare class MissingPointerError extends JSONParserError {
     code: JSONParserErrorType;
     name: string;
-    constructor(token: string, path: string);
+    targetToken: any;
+    targetRef: string;
+    targetFound: string;
+    parentPath: string;
+    constructor(token: any, path: any, targetRef: any, targetFound: any, parentPath: any);
 }
 export declare class TimeoutError extends JSONParserError {
     code: JSONParserErrorType;

package/dist/lib/util/errors.js

@@ -78,10 +78,14 @@ class UnmatchedResolverError extends JSONParserError {
 }
 exports.UnmatchedResolverError = UnmatchedResolverError;
 class MissingPointerError extends JSONParserError {
-    constructor(token, path) {
+    constructor(token, path, targetRef, targetFound, parentPath) {
         super(`Missing $ref pointer "${(0, url_js_1.getHash)(path)}". Token "${token}" does not exist.`, (0, url_js_1.stripHash)(path));
         this.code = "EMISSINGPOINTER";
         this.name = "MissingPointerError";
+        this.targetToken = token;
+        this.targetRef = targetRef;
+        this.targetFound = targetFound;
+        this.parentPath = parentPath;
     }
 }
 exports.MissingPointerError = MissingPointerError;

package/dist/lib/util/plugins.d.ts

@@ -18,7 +18,7 @@ export declare function filter(plugins: Plugin[], method: any, file: any): Plugi
  * Sorts the given plugins, in place, by their `order` property.
  */
 export declare function sort(plugins: Plugin[]): Plugin[];
-export interface PluginResult<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>> {
+export interface PluginResult<S extends object = JSONSchema> {
     plugin: Plugin;
     result?: string | Buffer | S;
     error?: any;
@@ -31,4 +31,4 @@ export interface PluginResult<S extends object = JSONSchema, O extends ParserOpt
  * If the promise rejects, or the callback is called with an error, then the next plugin is called.
  * If ALL plugins fail, then the last error is thrown.
  */
-export declare function run<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(plugins: Plugin[], method: keyof Plugin | keyof ResolverOptions<S>, file: FileInfo, $refs: $Refs<S, O>): Promise<PluginResult<S, O>>;
+export declare function run<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(plugins: Plugin[], method: keyof Plugin | keyof ResolverOptions<S>, file: FileInfo, $refs: $Refs<S, O>): Promise<PluginResult<S>>;

package/dist/lib/util/url.js

@@ -73,10 +73,11 @@ exports.parse = parse;
  * @returns
  */
 function resolve(from, to) {
-    const fromUrl = new URL((0, convert_path_to_posix_1.default)(from), "resolve://");
+    // we use a non-existent URL to check if its a relative URL
+    const fromUrl = new URL((0, convert_path_to_posix_1.default)(from), "https://aaa.nonexistanturl.com");
     const resolvedUrl = new URL((0, convert_path_to_posix_1.default)(to), fromUrl);
     const endSpaces = to.match(/(\s*)$/)?.[1] || "";
-    if (resolvedUrl.protocol === "resolve:") {
+    if (resolvedUrl.hostname === "aaa.nonexistanturl.com") {
         // `from` is a relative URL.
         const { pathname, search, hash } = resolvedUrl;
         return pathname + search + hash + endSpaces;

package/lib/dereference.ts

@@ -272,7 +272,8 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
 
 /**
  * Called when a circular reference is found.
- * It sets the {@link $Refs#circular} flag, and throws an error if options.dereference.circular is false.
+ * It sets the {@link $Refs#circular} flag, executes the options.dereference.onCircular callback,
+ * and throws an error if options.dereference.circular is false.
  *
  * @param keyPath - The JSON Reference path of the circular reference
  * @param $refs
@@ -281,6 +282,8 @@ function dereference$Ref<S extends object = JSONSchema, O extends ParserOptions<
  */
 function foundCircularReference(keyPath: any, $refs: any, options: any) {
   $refs.circular = true;
+  options?.dereference?.onCircular?.(keyPath);
+
   if (!options.dereference.circular) {
     throw ono.reference(`Circular $ref pointer found at ${keyPath}`);
   }

package/lib/index.ts

@@ -144,10 +144,8 @@ export class $RefParser<S extends object = JSONSchema, O extends ParserOptions<S
     }
   }
 
-  public static parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
-    schema: S | string | unknown,
-  ): Promise<S>;
-  public static parse<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  public static parse<S extends object = JSONSchema>(schema: S | string | unknown): Promise<S>;
+  public static parse<S extends object = JSONSchema>(
     schema: S | string | unknown,
     callback: SchemaCallback<S>,
   ): Promise<void>;
@@ -269,10 +267,8 @@ export class $RefParser<S extends object = JSONSchema, O extends ParserOptions<S
    * @param options (optional)
    * @param callback (optional) A callback that will receive the bundled schema object
    */
-  public static bundle<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
-    schema: S | string | unknown,
-  ): Promise<S>;
-  public static bundle<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  public static bundle<S extends object = JSONSchema>(schema: S | string | unknown): Promise<S>;
+  public static bundle<S extends object = JSONSchema>(
     schema: S | string | unknown,
     callback: SchemaCallback<S>,
   ): Promise<void>;
@@ -343,10 +339,8 @@ export class $RefParser<S extends object = JSONSchema, O extends ParserOptions<S
    * @param options (optional)
    * @param callback (optional) A callback that will receive the dereferenced schema object
    */
-  public static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
-    schema: S | string | unknown,
-  ): Promise<S>;
-  public static dereference<S extends object = JSONSchema, O extends ParserOptions<S> = ParserOptions<S>>(
+  public static dereference<S extends object = JSONSchema>(schema: S | string | unknown): Promise<S>;
+  public static dereference<S extends object = JSONSchema>(
     schema: S | string | unknown,
     callback: SchemaCallback<S>,
   ): Promise<void>;

package/lib/options.ts

@@ -29,6 +29,13 @@ export interface DereferenceOptions {
    */
   excludedPathMatcher?(path: string): boolean;
 
+  /**
+   * Callback invoked during circular reference detection.
+   *
+   * @argument {string} path - The path that is circular (ie. the `$ref` string)
+   */
+  onCircular?(path: string): void;
+
   /**
    * Callback invoked during dereferencing.
    *

package/lib/pointer.ts

@@ -88,6 +88,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
    */
   resolve(obj: S, options?: O, pathFromRoot?: string) {
     const tokens = Pointer.parse(this.path, this.originalPath);
+    const found: any = [];
 
     // Crawl the object, one token at a time
     this.value = unwrapOrThrow(obj);
@@ -103,6 +104,7 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
       }
 
       const token = tokens[i];
+
       if (this.value[token] === undefined || (this.value[token] === null && i === tokens.length - 1)) {
         // one final case is if the entry itself includes slashes, and was parsed out as a token - we can join the remaining tokens and try again
         let didFindSubstringSlashMatch = false;
@@ -120,10 +122,19 @@ class Pointer<S extends object = JSONSchema, O extends ParserOptions<S> = Parser
         }
 
         this.value = null;
-        throw new MissingPointerError(token, decodeURI(this.originalPath));
+
+        const path = this.$ref.path || "";
+
+        const targetRef = this.path.replace(path, "");
+        const targetFound = Pointer.join("", found);
+        const parentPath = pathFromRoot?.replace(path, "");
+
+        throw new MissingPointerError(token, decodeURI(this.originalPath), targetRef, targetFound, parentPath);
       } else {
         this.value = this.value[token];
       }
+
+      found.push(token);
     }
 
     // Resolve the final value