@apidevtools/json-schema-ref-parser 14.0.2 → 14.1.0

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,9 @@ function crawl(parent, key, path, pathFromRoot, indirections, inventory, $refs,
                 else {
                     crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
                 }
+                if (value["$ref"]) {
+                    bundleOptions?.onBundle?.(value["$ref"], obj[key], obj, key);
+                }
             }
         }
     }

package/dist/lib/index.js

@@ -69,22 +69,20 @@ Object.defineProperty(exports, "isUnsafeUrl", { enumerable: true, get: function
  * @class
  */
 class $RefParser {
-    constructor() {
-        /**
-         * The parsed (and possibly dereferenced) JSON schema object
-         *
-         * @type {object}
-         * @readonly
-         */
-        this.schema = null;
-        /**
-         * The resolved JSON references
-         *
-         * @type {$Refs}
-         * @readonly
-         */
-        this.$refs = new refs_js_1.default();
-    }
+    /**
+     * The parsed (and possibly dereferenced) JSON schema object
+     *
+     * @type {object}
+     * @readonly
+     */
+    schema = null;
+    /**
+     * The resolved JSON references
+     *
+     * @type {$Refs}
+     * @readonly
+     */
+    $refs = new refs_js_1.default();
     async parse() {
         const args = (0, normalize_args_js_1.default)(arguments);
         let promise;

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/dist/lib/pointer.js

@@ -62,6 +62,33 @@ const safeDecodeURIComponent = (encodedURIComponent) => {
  * @class
  */
 class Pointer {
+    /**
+     * The {@link $Ref} object that contains this {@link Pointer} object.
+     */
+    $ref;
+    /**
+     * The file path or URL, containing the JSON pointer in the hash.
+     * This path is relative to the path of the main JSON schema file.
+     */
+    path;
+    /**
+     * The original path or URL, used for error messages.
+     */
+    originalPath;
+    /**
+     * The value of the JSON pointer.
+     * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
+     */
+    value;
+    /**
+     * Indicates whether the pointer references itself.
+     */
+    circular;
+    /**
+     * The number of indirect references that were traversed to resolve the value.
+     * Resolving a single pointer may require resolving multiple $Refs.
+     */
+    indirections;
     constructor($ref, path, friendlyPath) {
         this.$ref = $ref;
         this.path = path;

package/dist/lib/ref.js

@@ -42,11 +42,39 @@ const url_js_1 = require("./util/url.js");
  * @class
  */
 class $Ref {
+    /**
+     * The file path or URL of the referenced file.
+     * This path is relative to the path of the main JSON schema file.
+     *
+     * This path does NOT contain document fragments (JSON pointers). It always references an ENTIRE file.
+     * Use methods such as {@link $Ref#get}, {@link $Ref#resolve}, and {@link $Ref#exists} to get
+     * specific JSON pointers within the file.
+     *
+     * @type {string}
+     */
+    path;
+    /**
+     * The resolved value of the JSON reference.
+     * Can be any JSON type, not just objects. Unknown file types are represented as Buffers (byte arrays).
+     *
+     * @type {?*}
+     */
+    value;
+    /**
+     * The {@link $Refs} object that contains this {@link $Ref} object.
+     *
+     * @type {$Refs}
+     */
+    $refs;
+    /**
+     * Indicates the type of {@link $Ref#path} (e.g. "file", "http", etc.)
+     */
+    pathType;
+    /**
+     * List of all errors. Undefined if no errors.
+     */
+    errors = [];
     constructor($refs) {
-        /**
-         * List of all errors. Undefined if no errors.
-         */
-        this.errors = [];
         this.$refs = $refs;
     }
     /**

package/dist/lib/refs.js

@@ -47,6 +47,12 @@ const convert_path_to_posix_1 = __importDefault(require("./util/convert-path-to-
  * See https://apidevtools.com/json-schema-ref-parser/docs/refs.html
  */
 class $Refs {
+    /**
+     * This property is true if the schema contains any circular references. You may want to check this property before serializing the dereferenced schema as JSON, since JSON.stringify() does not support circular references by default.
+     *
+     * See https://apidevtools.com/json-schema-ref-parser/docs/refs.html#circular
+     */
+    circular;
     /**
      * Returns the paths/URLs of all the files in your schema (including the main schema file).
      *
@@ -166,33 +172,21 @@ class $Refs {
         }
         return $ref.resolve(absPath, options, path, pathFromRoot);
     }
+    /**
+     * A map of paths/urls to {@link $Ref} objects
+     *
+     * @type {object}
+     * @protected
+     */
+    _$refs = {};
+    /**
+     * The {@link $Ref} object that is the root of the JSON schema.
+     *
+     * @type {$Ref}
+     * @protected
+     */
+    _root$Ref;
     constructor() {
-        /**
-         * A map of paths/urls to {@link $Ref} objects
-         *
-         * @type {object}
-         * @protected
-         */
-        this._$refs = {};
-        /**
-         * Returns the paths of all the files/URLs that are referenced by the JSON schema,
-         * including the schema itself.
-         *
-         * @param [types] - Only return paths of the given types ("file", "http", etc.)
-         * @returns
-         */
-        /**
-         * Returns the map of JSON references and their resolved values.
-         *
-         * @param [types] - Only return references of the given types ("file", "http", etc.)
-         * @returns
-         */
-        /**
-         * Returns a POJO (plain old JavaScript object) for serialization as JSON.
-         *
-         * @returns {object}
-         */
-        this.toJSON = this.values;
         /**
          * Indicates whether the schema contains any circular references.
          *
@@ -203,6 +197,25 @@ class $Refs {
         // @ts-ignore
         this._root$Ref = null;
     }
+    /**
+     * Returns the paths of all the files/URLs that are referenced by the JSON schema,
+     * including the schema itself.
+     *
+     * @param [types] - Only return paths of the given types ("file", "http", etc.)
+     * @returns
+     */
+    /**
+     * Returns the map of JSON references and their resolved values.
+     *
+     * @param [types] - Only return references of the given types ("file", "http", etc.)
+     * @returns
+     */
+    /**
+     * Returns a POJO (plain old JavaScript object) for serialization as JSON.
+     *
+     * @returns {object}
+     */
+    toJSON = this.values;
 }
 exports.default = $Refs;
 /**

package/dist/lib/resolve-external.js

@@ -82,7 +82,7 @@ function resolveExternal(parser, options) {
  * then the corresponding promise will internally reference an array of promises.
  */
 function crawl(obj, path, $refs, options, seen, external) {
-    seen || (seen = new Set());
+    seen ||= new Set();
     let promises = [];
     if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !seen.has(obj)) {
         seen.add(obj); // Track previously seen objects to avoid infinite recursion

package/dist/lib/resolvers/http.js

@@ -53,7 +53,7 @@ exports.default = {
     /**
      * HTTP request timeout (in milliseconds).
      */
-    timeout: 60000, // 60 seconds
+    timeout: 60_000, // 60 seconds
     /**
      * The maximum number of HTTP redirects to follow.
      * To disable automatic following of redirects, set this to zero.

package/dist/lib/util/errors.js

@@ -49,28 +49,34 @@ function getDeepKeys(obj, omit = []) {
     return uniqueKeys;
 }
 class JSONParserError extends Error {
+    name;
+    message;
+    source;
+    path;
+    code;
     constructor(message, source) {
         super();
-        this.toJSON = toJSON.bind(this);
         this.code = "EUNKNOWN";
         this.name = "JSONParserError";
         this.message = message;
         this.source = source;
         this.path = null;
     }
+    toJSON = toJSON.bind(this);
     get footprint() {
         return `${this.path}+${this.source}+${this.code}+${this.message}`;
     }
 }
 exports.JSONParserError = JSONParserError;
 class JSONParserErrorGroup extends Error {
+    files;
     constructor(parser) {
         super();
-        this.toJSON = toJSON.bind(this);
         this.files = parser;
         this.name = "JSONParserErrorGroup";
         this.message = `${this.errors.length} error${this.errors.length > 1 ? "s" : ""} occurred while reading '${(0, url_js_1.toFileSystemPath)(parser.$refs._root$Ref.path)}'`;
     }
+    toJSON = toJSON.bind(this);
     static getParserErrors(parser) {
         const errors = [];
         for (const $ref of Object.values(parser.$refs._$refs)) {
@@ -86,26 +92,27 @@ class JSONParserErrorGroup extends Error {
 }
 exports.JSONParserErrorGroup = JSONParserErrorGroup;
 class ParserError extends JSONParserError {
+    code = "EPARSER";
+    name = "ParserError";
     constructor(message, source) {
         super(`Error parsing ${source}: ${message}`, source);
-        this.code = "EPARSER";
-        this.name = "ParserError";
     }
 }
 exports.ParserError = ParserError;
 class UnmatchedParserError extends JSONParserError {
+    code = "EUNMATCHEDPARSER";
+    name = "UnmatchedParserError";
     constructor(source) {
         super(`Could not find parser for "${source}"`, source);
-        this.code = "EUNMATCHEDPARSER";
-        this.name = "UnmatchedParserError";
     }
 }
 exports.UnmatchedParserError = UnmatchedParserError;
 class ResolverError extends JSONParserError {
+    code = "ERESOLVER";
+    name = "ResolverError";
+    ioErrorCode;
     constructor(ex, source) {
         super(ex.message || `Error reading file "${source}"`, source);
-        this.code = "ERESOLVER";
-        this.name = "ResolverError";
         if ("code" in ex) {
             this.ioErrorCode = String(ex.code);
         }
@@ -113,18 +120,22 @@ class ResolverError extends JSONParserError {
 }
 exports.ResolverError = ResolverError;
 class UnmatchedResolverError extends JSONParserError {
+    code = "EUNMATCHEDRESOLVER";
+    name = "UnmatchedResolverError";
     constructor(source) {
         super(`Could not find resolver for "${source}"`, source);
-        this.code = "EUNMATCHEDRESOLVER";
-        this.name = "UnmatchedResolverError";
     }
 }
 exports.UnmatchedResolverError = UnmatchedResolverError;
 class MissingPointerError extends JSONParserError {
+    code = "EMISSINGPOINTER";
+    name = "MissingPointerError";
+    targetToken;
+    targetRef;
+    targetFound;
+    parentPath;
     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;
@@ -133,18 +144,18 @@ class MissingPointerError extends JSONParserError {
 }
 exports.MissingPointerError = MissingPointerError;
 class TimeoutError extends JSONParserError {
+    code = "ETIMEOUT";
+    name = "TimeoutError";
     constructor(timeout) {
         super(`Dereferencing timeout reached: ${timeout}ms`);
-        this.code = "ETIMEOUT";
-        this.name = "TimeoutError";
     }
 }
 exports.TimeoutError = TimeoutError;
 class InvalidPointerError extends JSONParserError {
+    code = "EUNMATCHEDRESOLVER";
+    name = "InvalidPointerError";
     constructor(pointer, path) {
         super(`Invalid $ref pointer "${pointer}". Pointers must begin with "#/"`, (0, url_js_1.stripHash)(path));
-        this.code = "EUNMATCHEDRESOLVER";
-        this.name = "InvalidPointerError";
     }
 }
 exports.InvalidPointerError = InvalidPointerError;

package/dist/lib/util/plugins.js

@@ -90,7 +90,7 @@ async function run(plugins, method, file, $refs) {
             // console.log('    success');
             resolve({
                 plugin,
-                result,
+                result: result,
             });
         }
         function onError(error) {

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,10 @@ function crawl<S extends object = JSONSchema, O extends ParserOptions<S> = Parse
         } else {
           crawl(obj, key, keyPath, keyPathFromRoot, indirections, inventory, $refs, options);
         }
+
+        if (value["$ref"]) {
+          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/lib/util/plugins.ts

@@ -108,7 +108,7 @@ export async function run<S extends object = JSONSchema, O extends ParserOptions
       // console.log('    success');
       resolve({
         plugin,
-        result,
+        result: result!,
       });
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apidevtools/json-schema-ref-parser",
-  "version": "14.0.2",
+  "version": "14.1.0",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "scripts": {
     "prepublishOnly": "yarn build",
@@ -59,36 +59,35 @@
     "fs": false
   },
   "engines": {
-    "node": ">= 16"
+    "node": ">= 20"
   },
   "files": [
     "lib",
-    "dist",
-    "cjs"
+    "dist"
   ],
   "devDependencies": {
-    "@eslint/compat": "^1.3.0",
-    "@eslint/js": "^9.29.0",
+    "@eslint/compat": "^1.3.1",
+    "@eslint/js": "^9.30.0",
     "@types/eslint": "^9.6.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^24",
-    "@typescript-eslint/eslint-plugin": "^8.34.1",
-    "@typescript-eslint/parser": "^8.34.1",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
     "@vitest/coverage-v8": "^3.2.4",
     "cross-env": "^7.0.3",
-    "eslint": "^9.29.0",
+    "eslint": "^9.30.0",
     "eslint-config-prettier": "^10.1.5",
     "eslint-config-standard": "^17.1.0",
-    "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-prettier": "^5.5.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.1",
     "eslint-plugin-promise": "^7.2.1",
     "eslint-plugin-unused-imports": "^4.1.4",
     "globals": "^16.2.0",
     "jsdom": "^26.1.0",
-    "prettier": "^3.5.3",
+    "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.34.1",
+    "typescript-eslint": "^8.35.1",
     "vitest": "^3.2.4"
   },
   "dependencies": {

package/dist/vite.config.d.ts

@@ -1,2 +0,0 @@
-declare const _default: import("vite").UserConfig;
-export default _default;

package/dist/vite.config.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const config_1 = require("vitest/config");
-const isBrowser = process.env.BROWSER === "true";
-exports.default = (0, config_1.defineConfig)({
-    test: {
-        environment: isBrowser ? "jsdom" : "node",
-        dir: "test",
-        exclude: ["**/__IGNORED__/**"],
-        watch: false,
-        globalSetup: isBrowser ? ["./test/fixtures/server.ts"] : undefined,
-        testTimeout: 5000,
-        globals: true,
-        passWithNoTests: true,
-        reporters: ["verbose"],
-        coverage: { reporter: ["lcov", "html", "text"] },
-        snapshotSerializers: ["./test/utils/serializeJson.ts"],
-    },
-});