@apidevtools/json-schema-ref-parser 14.0.3 → 14.1.1

package/dist/lib/bundle.js

@@ -69,7 +69,9 @@ function bundle(parser, options) {
  */
 function crawl(parent, key, path, pathFromRoot, indirections, inventory, $refs, options) {
     const obj = key === null ? parent : parent[key];
-    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+    const bundleOptions = (options.bundle || {});
+    const isExcludedPath = bundleOptions.excludedPathMatcher || (() => false);
+    if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
         if (ref_js_1.default.isAllowed$Ref(obj)) {
             inventory$Ref(parent, key, path, pathFromRoot, indirections, inventory, $refs, options);
         }
@@ -102,6 +104,13 @@ function crawl(parent, key, path, pathFromRoot, indirections, inventory, $refs,
                 else {
                     crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
                 }
+                // We need to ensure that we have an object to work with here because we may be crawling
+                // an `examples` schema and `value` may be nullish.
+                if (value && typeof value === "object" && !Array.isArray(value)) {
+                    if ("$ref" in value) {
+                        bundleOptions?.onBundle?.(value["$ref"], obj[key], obj, key);
+                    }
+                }
             }
         }
     }

package/dist/lib/options.d.ts

@@ -2,6 +2,23 @@ import type { HTTPResolverOptions, JSONSchema, JSONSchemaObject, Plugin, Resolve
 export type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+export interface BundleOptions {
+    /**
+     * A function, called for each path, which can return true to stop this path and all
+     * subpaths from being processed further. This is useful in schemas where some
+     * subpaths contain literal $ref keys that should not be changed.
+     */
+    excludedPathMatcher?(path: string): boolean;
+    /**
+     * Callback invoked during bundling.
+     *
+     * @argument {string} path - The path being processed (ie. the `$ref` string)
+     * @argument {JSONSchemaObject} value - The JSON-Schema that the `$ref` resolved to
+     * @argument {JSONSchemaObject} parent - The parent of the processed object
+     * @argument {string} parentPropName - The prop name of the parent object whose value was processed
+     */
+    onBundle?(path: string, value: JSONSchemaObject, parent?: JSONSchemaObject, parentPropName?: string): void;
+}
 export interface DereferenceOptions {
     /**
      * Determines whether circular `$ref` pointers are handled.
@@ -88,6 +105,10 @@ export interface $RefParserOptions<S extends object = JSONSchema> {
      * that were encountered.
      */
     continueOnError: boolean;
+    /**
+     * The `bundle` options control how JSON Schema `$Ref` Parser will process `$ref` pointers within the JSON schema.
+     */
+    bundle: BundleOptions;
     /**
      * The `dereference` options control how JSON Schema `$Ref` Parser will dereference `$ref` pointers within the JSON schema.
      */

package/dist/lib/options.js

@@ -48,6 +48,19 @@ const getJsonSchemaRefParserDefaultOptions = () => {
          * that were encountered.
          */
         continueOnError: false,
+        /**
+         * Determines the types of JSON references that are allowed.
+         */
+        bundle: {
+            /**
+             * A function, called for each path, which can return true to stop this path and all
+             * subpaths from being processed further. This is useful in schemas where some
+             * subpaths contain literal $ref keys that should not be changed.
+             *
+             * @type {function}
+             */
+            excludedPathMatcher: () => false,
+        },
         /**
          * Determines the types of JSON references that are allowed.
          */

package/lib/bundle.ts

@@ -5,6 +5,7 @@ import type $Refs from "./refs.js";
 import type $RefParser from "./index";
 import type { ParserOptions } from "./index";
 import type { JSONSchema } from "./index";
+import type { BundleOptions } from "./options";
 
 export interface InventoryEntry {
   $ref: any;
@@ -65,8 +66,10 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
   options: O,
 ) {
   const obj = key === null ? parent : parent[key as keyof typeof parent];
+  const bundleOptions = (options.bundle || {}) as BundleOptions;
+  const isExcludedPath = bundleOptions.excludedPathMatcher || (() => false);
 
-  if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+  if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
     if ($Ref.isAllowed$Ref(obj)) {
       inventory$Ref(parent, key, path, pathFromRoot, indirections, inventory, $refs, options);
     } else {
@@ -97,6 +100,14 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
         } else {
           crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
         }
+
+        // We need to ensure that we have an object to work with here because we may be crawling
+        // an `examples` schema and `value` may be nullish.
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          if ("$ref" in value) {
+            bundleOptions?.onBundle?.(value["$ref"], obj[key], obj as any, key);
+          }
+        }
       }
     }
   }

package/lib/options.ts

@@ -12,6 +12,26 @@ export type DeepPartial<T> = T extends object
       [P in keyof T]?: DeepPartial<T[P]>;
     }
   : T;
+
+export interface BundleOptions {
+  /**
+   * A function, called for each path, which can return true to stop this path and all
+   * subpaths from being processed further. This is useful in schemas where some
+   * subpaths contain literal $ref keys that should not be changed.
+   */
+  excludedPathMatcher?(path: string): boolean;
+
+  /**
+   * Callback invoked during bundling.
+   *
+   * @argument {string} path - The path being processed (ie. the `$ref` string)
+   * @argument {JSONSchemaObject} value - The JSON-Schema that the `$ref` resolved to
+   * @argument {JSONSchemaObject} parent - The parent of the processed object
+   * @argument {string} parentPropName - The prop name of the parent object whose value was processed
+   */
+  onBundle?(path: string, value: JSONSchemaObject, parent?: JSONSchemaObject, parentPropName?: string): void;
+}
+
 export interface DereferenceOptions {
   /**
    * Determines whether circular `$ref` pointers are handled.
@@ -107,6 +127,11 @@ export interface $RefParserOptions<S extends object = JSONSchema> {
    */
   continueOnError: boolean;
 
+  /**
+   * The `bundle` options control how JSON Schema `$Ref` Parser will process `$ref` pointers within the JSON schema.
+   */
+  bundle: BundleOptions;
+
   /**
    * The `dereference` options control how JSON Schema `$Ref` Parser will dereference `$ref` pointers within the JSON schema.
    */
@@ -168,6 +193,20 @@ export const getJsonSchemaRefParserDefaultOptions = () => {
      */
     continueOnError: false,
 
+    /**
+     * Determines the types of JSON references that are allowed.
+     */
+    bundle: {
+      /**
+       * A function, called for each path, which can return true to stop this path and all
+       * subpaths from being processed further. This is useful in schemas where some
+       * subpaths contain literal $ref keys that should not be changed.
+       *
+       * @type {function}
+       */
+      excludedPathMatcher: () => false,
+    },
+
     /**
      * Determines the types of JSON references that are allowed.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "14.0.3",
+  "version": "14.1.1",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "scripts": {
     "prepublishOnly": "yarn build",