@apidevtools/json-schema-ref-parser 10.0.0 → 10.1.0

package/lib/{bundle.js → bundle.ts}

@@ -1,6 +1,8 @@
 import $Ref from "./ref.js";
 import Pointer from "./pointer.js";
 import * as url from "./util/url.js";
+import type $RefParserOptions from "./options.js";
+import type $Refs from "./refs.js";
 
 export default bundle;
 
@@ -9,14 +11,14 @@ export default bundle;
  * only has *internal* references, not any *external* references.
  * This method mutates the JSON schema object, adding new references and re-mapping existing ones.
  *
- * @param {$RefParser} parser
- * @param {$RefParserOptions} options
+ * @param parser
+ * @param options
  */
-function bundle (parser, options) {
+function bundle(parser: any, options: any) {
   // console.log('Bundling $ref pointers in %s', parser.$refs._root$Ref.path);
 
   // Build an inventory of all $ref pointers in the JSON Schema
-  let inventory = [];
+  const inventory: any = [];
   crawl(parser, "schema", parser.$refs._root$Ref.path + "#", "#", 0, inventory, parser.$refs, options);
 
   // Remap all $ref pointers
@@ -26,52 +28,58 @@ function bundle (parser, options) {
 /**
  * Recursively crawls the given value, and inventories all JSON references.
  *
- * @param {object} parent - The object containing the value to crawl. If the value is not an object or array, it will be ignored.
- * @param {string} key - The property key of `parent` to be crawled
- * @param {string} path - The full path of the property being crawled, possibly with a JSON Pointer in the hash
- * @param {string} pathFromRoot - The path of the property being crawled, from the schema root
- * @param {object[]} inventory - An array of already-inventoried $ref pointers
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
+ * @param parent - The object containing the value to crawl. If the value is not an object or array, it will be ignored.
+ * @param key - The property key of `parent` to be crawled
+ * @param path - The full path of the property being crawled, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of the property being crawled, from the schema root
+ * @param inventory - An array of already-inventoried $ref pointers
+ * @param $refs
+ * @param options
  */
-function crawl (parent, key, path, pathFromRoot, indirections, inventory, $refs, options) {
-  let obj = key === null ? parent : parent[key];
+function crawl(
+  parent: any,
+  key: any,
+  path: any,
+  pathFromRoot: any,
+  indirections: any,
+  inventory: any,
+  $refs: any,
+  options: any,
+) {
+  const obj = key === null ? parent : parent[key];
 
   if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+    // @ts-expect-error TS(2554): Expected 2 arguments, but got 1.
     if ($Ref.isAllowed$Ref(obj)) {
       inventory$Ref(parent, key, path, pathFromRoot, indirections, inventory, $refs, options);
-    }
-    else {
+    } else {
       // Crawl the object in a specific order that's optimized for bundling.
       // This is important because it determines how `pathFromRoot` gets built,
       // which later determines which keys get dereferenced and which ones get remapped
-      let keys = Object.keys(obj)
-        .sort((a, b) => {
-          // Most people will expect references to be bundled into the the "definitions" property,
-          // so we always crawl that property first, if it exists.
-          if (a === "definitions") {
-            return -1;
-          }
-          else if (b === "definitions") {
-            return 1;
-          }
-          else {
-            // Otherwise, crawl the keys based on their length.
-            // This produces the shortest possible bundled references
-            return a.length - b.length;
-          }
-        });
+      const keys = Object.keys(obj).sort((a, b) => {
+        // Most people will expect references to be bundled into the the "definitions" property,
+        // so we always crawl that property first, if it exists.
+        if (a === "definitions") {
+          return -1;
+        } else if (b === "definitions") {
+          return 1;
+        } else {
+          // Otherwise, crawl the keys based on their length.
+          // This produces the shortest possible bundled references
+          return a.length - b.length;
+        }
+      });
 
       // eslint-disable-next-line no-shadow
-      for (let key of keys) {
-        let keyPath = Pointer.join(path, key);
-        let keyPathFromRoot = Pointer.join(pathFromRoot, key);
-        let value = obj[key];
+      for (const key of keys) {
+        const keyPath = Pointer.join(path, key);
+        const keyPathFromRoot = Pointer.join(pathFromRoot, key);
+        const value = obj[key];
 
+        // @ts-expect-error TS(2554): Expected 2 arguments, but got 1.
         if ($Ref.isAllowed$Ref(value)) {
           inventory$Ref(obj, key, path, keyPathFromRoot, indirections, inventory, $refs, options);
-        }
-        else {
+        } else {
           crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
         }
       }
@@ -83,53 +91,60 @@ function crawl (parent, key, path, pathFromRoot, indirections, inventory, $refs,
  * Inventories the given JSON Reference (i.e. records detailed information about it so we can
  * optimize all $refs in the schema), and then crawls the resolved value.
  *
- * @param {object} $refParent - The object that contains a JSON Reference as one of its keys
- * @param {string} $refKey - The key in `$refParent` that is a JSON Reference
- * @param {string} path - The full path of the JSON Reference at `$refKey`, possibly with a JSON Pointer in the hash
- * @param {string} pathFromRoot - The path of the JSON Reference at `$refKey`, from the schema root
- * @param {object[]} inventory - An array of already-inventoried $ref pointers
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
+ * @param $refParent - The object that contains a JSON Reference as one of its keys
+ * @param $refKey - The key in `$refParent` that is a JSON Reference
+ * @param path - The full path of the JSON Reference at `$refKey`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of the JSON Reference at `$refKey`, from the schema root
+ * @param inventory - An array of already-inventoried $ref pointers
+ * @param $refs
+ * @param options
  */
-function inventory$Ref ($refParent, $refKey, path, pathFromRoot, indirections, inventory, $refs, options) {
-  let $ref = $refKey === null ? $refParent : $refParent[$refKey];
-  let $refPath = url.resolve(path, $ref.$ref);
-  let pointer = $refs._resolve($refPath, pathFromRoot, options);
+function inventory$Ref(
+  $refParent: any,
+  $refKey: any,
+  path: string,
+  pathFromRoot: any,
+  indirections: any,
+  inventory: any,
+  $refs: $Refs,
+  options: $RefParserOptions,
+) {
+  const $ref = $refKey === null ? $refParent : $refParent[$refKey];
+  const $refPath = url.resolve(path, $ref.$ref);
+  const pointer = $refs._resolve($refPath, pathFromRoot, options);
   if (pointer === null) {
     return;
   }
-
-  let depth = Pointer.parse(pathFromRoot).length;
-  let file = url.stripHash(pointer.path);
-  let hash = url.getHash(pointer.path);
-  let external = file !== $refs._root$Ref.path;
-  let extended = $Ref.isExtended$Ref($ref);
+  const depth = Pointer.parse(pathFromRoot).length;
+  const file = url.stripHash(pointer.path);
+  const hash = url.getHash(pointer.path);
+  const external = file !== $refs._root$Ref.path;
+  const extended = $Ref.isExtended$Ref($ref);
   indirections += pointer.indirections;
 
-  let existingEntry = findInInventory(inventory, $refParent, $refKey);
+  const existingEntry = findInInventory(inventory, $refParent, $refKey);
   if (existingEntry) {
     // This $Ref has already been inventoried, so we don't need to process it again
     if (depth < existingEntry.depth || indirections < existingEntry.indirections) {
       removeFromInventory(inventory, existingEntry);
-    }
-    else {
+    } else {
       return;
     }
   }
 
   inventory.push({
-    $ref,                   // The JSON Reference (e.g. {$ref: string})
-    parent: $refParent,           // The object that contains this $ref pointer
-    key: $refKey,                 // The key in `parent` that is the $ref pointer
-    pathFromRoot,   // The path to the $ref pointer, from the JSON Schema root
-    depth,                 // How far from the JSON Schema root is this $ref pointer?
-    file,                   // The file that the $ref pointer resolves to
-    hash,                   // The hash within `file` that the $ref pointer resolves to
-    value: pointer.value,         // The resolved value of the $ref pointer
-    circular: pointer.circular,   // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
-    extended,           // Does this $ref extend its resolved value? (i.e. it has extra properties, in addition to "$ref")
-    external,           // Does this $ref pointer point to a file other than the main JSON Schema file?
-    indirections,   // The number of indirect references that were traversed to resolve the value
+    $ref, // The JSON Reference (e.g. {$ref: string})
+    parent: $refParent, // The object that contains this $ref pointer
+    key: $refKey, // The key in `parent` that is the $ref pointer
+    pathFromRoot, // The path to the $ref pointer, from the JSON Schema root
+    depth, // How far from the JSON Schema root is this $ref pointer?
+    file, // The file that the $ref pointer resolves to
+    hash, // The hash within `file` that the $ref pointer resolves to
+    value: pointer.value, // The resolved value of the $ref pointer
+    circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
+    extended, // Does this $ref extend its resolved value? (i.e. it has extra properties, in addition to "$ref")
+    external, // Does this $ref pointer point to a file other than the main JSON Schema file?
+    indirections, // The number of indirect references that were traversed to resolve the value
   });
 
   // Recursively crawl the resolved value
@@ -143,8 +158,7 @@ function inventory$Ref ($refParent, $refKey, path, pathFromRoot, indirections, i
  * Each referenced value is dereferenced EXACTLY ONCE.  All subsequent references to the same
  * value are re-mapped to point to the first reference.
  *
- * @example:
- *  {
+ * @example: {
  *    first: { $ref: somefile.json#/some/part },
  *    second: { $ref: somefile.json#/another/part },
  *    third: { $ref: somefile.json },
@@ -159,46 +173,39 @@ function inventory$Ref ($refParent, $refKey, path, pathFromRoot, indirections, i
  * to be dereferenced, since they point to different parts of the file. The fourth reference does NOT
  * need to be dereferenced, because it can be remapped to point inside the first one.
  *
- * @param {object[]} inventory
+ * @param inventory
  */
-function remap (inventory) {
+function remap(inventory: any) {
   // Group & sort all the $ref pointers, so they're in the order that we need to dereference/remap them
-  inventory.sort((a, b) => {
+  inventory.sort((a: any, b: any) => {
     if (a.file !== b.file) {
       // Group all the $refs that point to the same file
       return a.file < b.file ? -1 : +1;
-    }
-    else if (a.hash !== b.hash) {
+    } else if (a.hash !== b.hash) {
       // Group all the $refs that point to the same part of the file
       return a.hash < b.hash ? -1 : +1;
-    }
-    else if (a.circular !== b.circular) {
+    } else if (a.circular !== b.circular) {
       // If the $ref points to itself, then sort it higher than other $refs that point to this $ref
       return a.circular ? -1 : +1;
-    }
-    else if (a.extended !== b.extended) {
+    } else if (a.extended !== b.extended) {
       // If the $ref extends the resolved value, then sort it lower than other $refs that don't extend the value
       return a.extended ? +1 : -1;
-    }
-    else if (a.indirections !== b.indirections) {
+    } else if (a.indirections !== b.indirections) {
       // Sort direct references higher than indirect references
       return a.indirections - b.indirections;
-    }
-    else if (a.depth !== b.depth) {
+    } else if (a.depth !== b.depth) {
       // Sort $refs by how close they are to the JSON Schema root
       return a.depth - b.depth;
-    }
-    else {
+    } else {
       // Determine how far each $ref is from the "definitions" property.
       // Most people will expect references to be bundled into the the "definitions" property if possible.
-      let aDefinitionsIndex = a.pathFromRoot.lastIndexOf("/definitions");
-      let bDefinitionsIndex = b.pathFromRoot.lastIndexOf("/definitions");
+      const aDefinitionsIndex = a.pathFromRoot.lastIndexOf("/definitions");
+      const bDefinitionsIndex = b.pathFromRoot.lastIndexOf("/definitions");
 
       if (aDefinitionsIndex !== bDefinitionsIndex) {
         // Give higher priority to the $ref that's closer to the "definitions" property
         return bDefinitionsIndex - aDefinitionsIndex;
-      }
-      else {
+      } else {
         // All else is equal, so use the shorter path, which will produce the shortest possible reference
         return a.pathFromRoot.length - b.pathFromRoot.length;
       }
@@ -206,22 +213,19 @@ function remap (inventory) {
   });
 
   let file, hash, pathFromRoot;
-  for (let entry of inventory) {
+  for (const entry of inventory) {
     // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
 
     if (!entry.external) {
       // This $ref already resolves to the main JSON Schema file
       entry.$ref.$ref = entry.hash;
-    }
-    else if (entry.file === file && entry.hash === hash) {
+    } else if (entry.file === file && entry.hash === hash) {
       // This $ref points to the same value as the prevous $ref, so remap it to the same path
       entry.$ref.$ref = pathFromRoot;
-    }
-    else if (entry.file === file && entry.hash.indexOf(hash + "/") === 0) {
+    } else if (entry.file === file && entry.hash.indexOf(hash + "/") === 0) {
       // This $ref points to a sub-value of the prevous $ref, so remap it beneath that path
       entry.$ref.$ref = Pointer.join(pathFromRoot, Pointer.parse(entry.hash.replace(hash, "#")));
-    }
-    else {
+    } else {
       // We've moved to a new file or new hash
       file = entry.file;
       hash = entry.hash;
@@ -244,16 +248,16 @@ function remap (inventory) {
 /**
  * TODO
  */
-function findInInventory (inventory, $refParent, $refKey) {
+function findInInventory(inventory: any, $refParent: any, $refKey: any) {
   for (let i = 0; i < inventory.length; i++) {
-    let existingEntry = inventory[i];
+    const existingEntry = inventory[i];
     if (existingEntry.parent === $refParent && existingEntry.key === $refKey) {
       return existingEntry;
     }
   }
 }
 
-function removeFromInventory (inventory, entry) {
-  let index = inventory.indexOf(entry);
+function removeFromInventory(inventory: any, entry: any) {
+  const index = inventory.indexOf(entry);
   inventory.splice(index, 1);
 }

package/lib/{dereference.js → dereference.ts}

@@ -2,6 +2,8 @@ import $Ref from "./ref.js";
 import Pointer from "./pointer.js";
 import { ono } from "@jsdevtools/ono";
 import * as url from "./util/url.js";
+import type $Refs from "./refs.js";
+import type $RefParserOptions from "./options.js";
 
 export default dereference;
 
@@ -9,12 +11,21 @@ export default dereference;
  * Crawls the JSON schema, finds all JSON references, and dereferences them.
  * This method mutates the JSON schema object, replacing JSON references with their resolved value.
  *
- * @param {$RefParser} parser
- * @param {$RefParserOptions} options
+ * @param parser
+ * @param options
  */
-function dereference (parser, options) {
+function dereference(parser: any, options: any) {
   // console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
-  let dereferenced = crawl(parser.schema, parser.$refs._root$Ref.path, "#", new Set(), new Set(), new Map(), parser.$refs, options);
+  const dereferenced = crawl(
+    parser.schema,
+    parser.$refs._root$Ref.path,
+    "#",
+    new Set(),
+    new Set(),
+    new Map(),
+    parser.$refs,
+    options,
+  );
   parser.$refs.circular = dereferenced.circular;
   parser.schema = dereferenced.value;
 }
@@ -22,24 +33,33 @@ function dereference (parser, options) {
 /**
  * Recursively crawls the given value, and dereferences any JSON references.
  *
- * @param {*} obj - The value to crawl. If it's not an object or array, it will be ignored.
- * @param {string} path - The full path of `obj`, possibly with a JSON Pointer in the hash
- * @param {string} pathFromRoot - The path of `obj` from the schema root
- * @param {Set<object>} parents - An array of the parent objects that have already been dereferenced
- * @param {Set<object>} processedObjects - An array of all the objects that have already been processed
- * @param {Map<string,object>} dereferencedCache - An map of all the dereferenced objects
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
- * @returns {{value: object, circular: boolean}}
+ * @param obj - The value to crawl. If it's not an object or array, it will be ignored.
+ * @param path - The full path of `obj`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of `obj` from the schema root
+ * @param parents - An array of the parent objects that have already been dereferenced
+ * @param processedObjects - An array of all the objects that have already been processed
+ * @param dereferencedCache - An map of all the dereferenced objects
+ * @param $refs
+ * @param options
+ * @returns
  */
-function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options) {
+function crawl(
+  obj: any,
+  path: string,
+  pathFromRoot: string,
+  parents: Set<any>,
+  processedObjects: Set<any>,
+  dereferencedCache: any,
+  $refs: $Refs,
+  options: $RefParserOptions,
+) {
   let dereferenced;
-  let result = {
+  const result = {
     value: obj,
-    circular: false
+    circular: false,
   };
 
-  let isExcludedPath = options.dereference.excludedPathMatcher;
+  const isExcludedPath = options.dereference.excludedPathMatcher || (() => false);
 
   if (options.dereference.circular === "ignore" || !processedObjects.has(obj)) {
     if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
@@ -47,24 +67,41 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
       processedObjects.add(obj);
 
       if ($Ref.isAllowed$Ref(obj, options)) {
-        dereferenced = dereference$Ref(obj, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+        dereferenced = dereference$Ref(
+          obj,
+          path,
+          pathFromRoot,
+          parents,
+          processedObjects,
+          dereferencedCache,
+          $refs,
+          options,
+        );
         result.circular = dereferenced.circular;
         result.value = dereferenced.value;
-      }
-      else {
+      } else {
         for (const key of Object.keys(obj)) {
-          let keyPath = Pointer.join(path, key);
-          let keyPathFromRoot = Pointer.join(pathFromRoot, key);
+          const keyPath = Pointer.join(path, key);
+          const keyPathFromRoot = Pointer.join(pathFromRoot, key);
 
           if (isExcludedPath(keyPathFromRoot)) {
             continue;
           }
 
-          let value = obj[key];
+          const value = obj[key];
           let circular = false;
 
           if ($Ref.isAllowed$Ref(value, options)) {
-            dereferenced = dereference$Ref(value, keyPath, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+            dereferenced = dereference$Ref(
+              value,
+              keyPath,
+              keyPathFromRoot,
+              parents,
+              processedObjects,
+              dereferencedCache,
+              $refs,
+              options,
+            );
             circular = dereferenced.circular;
             // Avoid pointless mutations; breaks frozen objects to no profit
             if (obj[key] !== dereferenced.value) {
@@ -73,17 +110,24 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
                 options.dereference.onDereference(value.$ref, obj[key]);
               }
             }
-          }
-          else {
+          } else {
             if (!parents.has(value)) {
-              dereferenced = crawl(value, keyPath, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+              dereferenced = crawl(
+                value,
+                keyPath,
+                keyPathFromRoot,
+                parents,
+                processedObjects,
+                dereferencedCache,
+                $refs,
+                options,
+              );
               circular = dereferenced.circular;
               // Avoid pointless mutations; breaks frozen objects to no profit
               if (obj[key] !== dereferenced.value) {
                 obj[key] = dereferenced.value;
               }
-            }
-            else {
+            } else {
               circular = foundCircularReference(keyPath, $refs, options);
             }
           }
@@ -103,28 +147,38 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
 /**
  * Dereferences the given JSON Reference, and then crawls the resulting value.
  *
- * @param {{$ref: string}} $ref - The JSON Reference to resolve
- * @param {string} path - The full path of `$ref`, possibly with a JSON Pointer in the hash
- * @param {string} pathFromRoot - The path of `$ref` from the schema root
- * @param {Set<object>} parents - An array of the parent objects that have already been dereferenced
- * @param {Set<object>} processedObjects - An array of all the objects that have already been dereferenced
- * @param {Map<string,object>} dereferencedCache - An map of all the dereferenced objects
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
- * @returns {{value: object, circular: boolean}}
+ * @param $ref - The JSON Reference to resolve
+ * @param path - The full path of `$ref`, possibly with a JSON Pointer in the hash
+ * @param pathFromRoot - The path of `$ref` from the schema root
+ * @param parents - An array of the parent objects that have already been dereferenced
+ * @param processedObjects - An array of all the objects that have already been dereferenced
+ * @param dereferencedCache - An map of all the dereferenced objects
+ * @param $refs
+ * @param options
+ * @returns
  */
-function dereference$Ref ($ref, path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options) {
+function dereference$Ref(
+  $ref: any,
+  path: any,
+  pathFromRoot: any,
+  parents: any,
+  processedObjects: any,
+  dereferencedCache: any,
+  $refs: any,
+  options: any,
+) {
   // console.log('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
 
-  let $refPath = url.resolve(path, $ref.$ref);
+  const $refPath = url.resolve(path, $ref.$ref);
 
   const cache = dereferencedCache.get($refPath);
   if (cache) {
     const refKeys = Object.keys($ref);
     if (refKeys.length > 1) {
       const extraKeys = {};
-      for (let key of refKeys) {
+      for (const key of refKeys) {
         if (key !== "$ref" && !(key in cache.value)) {
+          // @ts-expect-error TS(7053): Element implicitly has an 'any' type because expre... Remove this comment to see the full error message
           extraKeys[key] = $ref[key];
         }
       }
@@ -137,8 +191,7 @@ function dereference$Ref ($ref, path, pathFromRoot, parents, processedObjects, d
     return cache;
   }
 
-
-  let pointer = $refs._resolve($refPath, path, options);
+  const pointer = $refs._resolve($refPath, path, options);
 
   if (pointer === null) {
     return {
@@ -148,7 +201,7 @@ function dereference$Ref ($ref, path, pathFromRoot, parents, processedObjects, d
   }
 
   // Check for circular references
-  let directCircular = pointer.circular;
+  const directCircular = pointer.circular;
   let circular = directCircular || parents.has(pointer.value);
   circular && foundCircularReference(path, $refs, options);
 
@@ -158,7 +211,16 @@ function dereference$Ref ($ref, path, pathFromRoot, parents, processedObjects, d
   // Crawl the dereferenced value (unless it's circular)
   if (!circular) {
     // Determine if the dereferenced value is circular
-    let dereferenced = crawl(dereferencedValue, pointer.path, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options);
+    const dereferenced = crawl(
+      dereferencedValue,
+      pointer.path,
+      pathFromRoot,
+      parents,
+      processedObjects,
+      dereferencedCache,
+      $refs,
+      options,
+    );
     circular = dereferenced.circular;
     dereferencedValue = dereferenced.value;
   }
@@ -174,10 +236,9 @@ function dereference$Ref ($ref, path, pathFromRoot, parents, processedObjects, d
     dereferencedValue.$ref = pathFromRoot;
   }
 
-
   const dereferencedObject = {
     circular,
-    value: dereferencedValue
+    value: dereferencedValue,
   };
 
   // only cache if no extra properties than $ref
@@ -192,12 +253,12 @@ function dereference$Ref ($ref, path, pathFromRoot, parents, processedObjects, d
  * Called when a circular reference is found.
  * It sets the {@link $Refs#circular} flag, and throws an error if options.dereference.circular is false.
  *
- * @param {string} keyPath - The JSON Reference path of the circular reference
- * @param {$Refs} $refs
- * @param {$RefParserOptions} options
- * @returns {boolean} - always returns true, to indicate that a circular reference was found
+ * @param keyPath - The JSON Reference path of the circular reference
+ * @param $refs
+ * @param options
+ * @returns - always returns true, to indicate that a circular reference was found
  */
-function foundCircularReference (keyPath, $refs, options) {
+function foundCircularReference(keyPath: any, $refs: any, options: any) {
   $refs.circular = true;
   if (!options.dereference.circular) {
     throw ono.reference(`Circular $ref pointer found at ${keyPath}`);