feat: add support for options.dereference.onDereference

docs/options.md

@@ -31,7 +31,9 @@ $RefParser.dereference("my-schema.yaml", {
  dereference: {
  circular: false, // Don't allow circular $refs
  excludedPathMatcher: (path) => // Skip dereferencing content under any 'example' key
- path.includes("/example/")
+ path.includes("/example/"),
+ onDereference: (path, value) => // Callback invoked during dereferencing
+ console.log(path, value)
  }
 });
 ```
@@ -77,4 +79,5 @@ The `dereference` options control how JSON Schema $Ref Parser will dereference `
 |Option(s) |Type |Description
 |:---------------------|:-------------------|:------------
 |`circular`|`boolean` or `"ignore"`|Determines whether [circular `$ref` pointers](README.md#circular-refs) are handled.<br><br>If set to `false`, then a `ReferenceError` will be thrown if the schema contains any circular references.<br><br> If set to `"ignore"`, then circular references will simply be ignored. No error will be thrown, but the [`$Refs.circular`](refs.md#circular) property will still be set to `true`.
-|`excludedPathMatcher`|`(string) => boolean`|A function, called for each path, which can return true to stop this path and all subpaths from being dereferenced further. This is useful in schemas where some subpaths contain literal $ref keys that should not be dereferenced.
+|`excludedPathMatcher`|`(string) => boolean`|A function, called for each path, which can return true to stop this path and all subpaths from being dereferenced further. This is useful in schemas where some subpaths contain literal `$ref` keys that should not be dereferenced.
+|`onDereference`|`(string, JSONSchemaObjectType) => void`|A function, called immediately after dereferencing, with the resolved JSON Schema value and the `$ref` being dereferenced.

lib/dereference.js

@@ -71,6 +71,9 @@ function crawl (obj, path, pathFromRoot, parents, processedObjects, dereferenced
  // Avoid pointless mutations; breaks frozen objects to no profit
  if (obj[key] !== dereferenced.value) {
  obj[key] = dereferenced.value;
+ if (options.dereference.onDereference) {
+ options.dereference.onDereference(value.$ref, obj[key])
+ }
  }
  }
  else {

lib/index.d.ts

@@ -1,4 +1,4 @@
-import { JSONSchema4, JSONSchema4Type, JSONSchema6, JSONSchema6Type, JSONSchema7, JSONSchema7Type } from "json-schema";
+import { JSONSchema4, JSONSchema4Object, JSONSchema4Type, JSONSchema6, JSONSchema6Object, JSONSchema6Type, JSONSchema7, JSONSchema7Object, JSONSchema7Type } from "json-schema";
 
 export = $RefParser;
 
@@ -174,6 +174,7 @@ declare class $RefParser {
 declare namespace $RefParser {
 
  export type JSONSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
+ export type JSONSchemaObject = JSONSchema4Object | JSONSchema6Object | JSONSchema7Object;
  export type SchemaCallback = (err: Error | null, schema?: JSONSchema) => any;
  export type $RefsCallback = (err: Error | null, $refs?: $Refs) => any;
 
@@ -238,6 +239,14 @@ declare namespace $RefParser {
  * subpaths contain literal $ref keys that should not be dereferenced.
  */
  excludedPathMatcher?(path: string): boolean;
+
+ /**
+ * Callback invoked during dereferencing.
+ *
+ * @argument {string} path The path being dereferenced (ie. the `$ref` string).
+ * @argument {JSONSchemaObject} object The JSON-Schema that the `$ref` resolved to.
+ */
+ onDereference(path: string, value: JSONSchemaObject): void;
  };
  }
 

test/specs/dereference-callback/dereference-callback.spec.js

@@ -0,0 +1,26 @@
+"use strict";
+
+const { expect } = require("chai");
+const $RefParser = require("../../..");
+const path = require("../../utils/path");
+
+describe("Schema with a $ref", () => {
+ it("should call onDereference", async () => {
+ let parser = new $RefParser();
+ const calls = [];
+ const schema = await parser.dereference(
+ path.rel("specs/dereference-callback/dereference-callback.yaml"),
+ {
+ dereference: {
+ onDereference(path, object) {
+ calls.push({ path, object });
+ },
+ },
+ }
+ );
+ expect(calls).to.deep.equal([
+ { path: "#/definitions/b", object: { $ref: "#/definitions/a" } },
+ { path: "#/definitions/a", object: { $ref: "#/definitions/a" } },
+ ]);
+ });
+});

test/specs/dereference-callback/dereference-callback.yaml

@@ -0,0 +1,12 @@
+title: test
+type: object
+definitions:
+ a:
+ $ref: "#/definitions/b"
+ b:
+ $ref: "#/definitions/a"
+properties:
+ c:
+ type: string
+ d:
+ $ref: "#/definitions/a"