feat: surfacing circular $refs in a new circularRefs property on the parser (#58)

* feat: surfacing circular $refs in a new `circularRefs` property on the parser

* fix: broken tests in chrome

Author: erunion

README.md

@@ -97,6 +97,7 @@ import $RefParser from "@readme/json-schema-ref-parser";
 
 * Forces YAML to conform to JSON-compatible types. https://github.com/APIDevTools/json-schema-ref-parser/pull/247
 * Improved support for OpenAPI 3.1 definitions where `$ref` pointers may live alongside a `description` property. https://github.com/readmeio/json-schema-ref-parser/pull/2
+* Exposes a new `$refs.circularRefs` property containing an array of any circular `$ref` pointers that may exist within the schema definition.
 
 ## Browser support
 JSON Schema $Ref Parser supports recent versions of every major web browser.  Older browsers may require [Babel](https://babeljs.io/) and/or [polyfills](https://babeljs.io/docs/en/next/babel-polyfill).

docs/refs.md

@@ -8,6 +8,7 @@ This object is a map of JSON References and their resolved values.  It also has
 
 ##### Properties
 - [`circular`](#circular)
+- [`circularRefs`](#circularRefs)
 
 ##### Methods
 - [`paths()`](#pathstypes)
@@ -33,6 +34,22 @@ if (parser.$refs.circular) {
 ```
 
 
+### `circularRefs`
+
+- **Type:** `array`
+
+This property contains an array of any [circular references](README.md#circular-refs) that may the schema contains.
+
+```javascript
+let parser = new $RefParser();
+await parser.dereference("my-schema.json");
+
+if (parser.$refs.circular) {
+  console.log(parser.$refs.circularRefs);
+}
+```
+
+
 ### `paths([types])`
 
 - **types** (_optional_) - `string` (one or more)<br>

lib/dereference.js

@@ -254,8 +254,11 @@ function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, de
  */
 function foundCircularReference(keyPath, $refs, options) {
   $refs.circular = true;
+  $refs.circularRefs.push(keyPath);
+
   if (!options.dereference.circular) {
     throw ono.reference(`Circular $ref pointer found at ${keyPath}`);
   }
+
   return true;
 }

lib/index.d.ts

@@ -361,6 +361,11 @@ declare namespace $RefParser {
      */
     public circular: boolean;
 
+    /**
+     * This property contains any circular references that may be within the schema.
+     */
+    public circularRefs: string[];
+
     /**
      * Returns the paths/URLs of all the files in your schema (including the main schema file).
      *

lib/refs.js

@@ -16,6 +16,13 @@ function $Refs() {
    */
   this.circular = false;
 
+  /**
+   * Contains any circular references that may be present within the schema.
+   *
+   * @type {array}
+   */
+  this.circularRefs = [];
+
   /**
    * A map of paths/urls to {@link $Ref} objects
    *