@hey-api/json-schema-ref-parser 1.0.8 → 1.2.0

package/dist/lib/bundle.js

@@ -37,34 +37,113 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bundle = void 0;
-const isEqual_1 = __importDefault(require("lodash/isEqual"));
 const ref_js_1 = __importDefault(require("./ref.js"));
 const pointer_js_1 = __importDefault(require("./pointer.js"));
 const url = __importStar(require("./util/url.js"));
+const DEBUG_PERFORMANCE = process.env.DEBUG === "true" ||
+    (typeof globalThis !== "undefined" && globalThis.DEBUG_BUNDLE_PERFORMANCE === true);
+const perf = {
+    mark: (name) => DEBUG_PERFORMANCE && performance.mark(name),
+    measure: (name, start, end) => DEBUG_PERFORMANCE && performance.measure(name, start, end),
+    log: (message, ...args) => DEBUG_PERFORMANCE && console.log("[PERF] " + message, ...args),
+    warn: (message, ...args) => DEBUG_PERFORMANCE && console.warn("[PERF] " + message, ...args),
+};
 /**
- * TODO
+ * Fast lookup using Map instead of linear search with deep equality
  */
-const findInInventory = (inventory, $refParent, $refKey) => {
-    for (const entry of inventory) {
-        if (entry) {
-            if ((0, isEqual_1.default)(entry.parent, $refParent)) {
-                if (entry.key === $refKey) {
-                    return entry;
-                }
-            }
+const createInventoryLookup = () => {
+    const lookup = new Map();
+    const objectIds = new WeakMap(); // Use WeakMap to avoid polluting objects
+    let idCounter = 0;
+    let lookupCount = 0;
+    let addCount = 0;
+    const getObjectId = (obj) => {
+        if (!objectIds.has(obj)) {
+            objectIds.set(obj, `obj_${++idCounter}`);
         }
+        return objectIds.get(obj);
+    };
+    const createInventoryKey = ($refParent, $refKey) => {
+        // Use WeakMap-based lookup to avoid polluting the actual schema objects
+        return `${getObjectId($refParent)}_${$refKey}`;
+    };
+    return {
+        add: (entry) => {
+            addCount++;
+            const key = createInventoryKey(entry.parent, entry.key);
+            lookup.set(key, entry);
+            if (addCount % 100 === 0) {
+                perf.log(`Inventory lookup: Added ${addCount} entries, map size: ${lookup.size}`);
+            }
+        },
+        find: ($refParent, $refKey) => {
+            lookupCount++;
+            const key = createInventoryKey($refParent, $refKey);
+            const result = lookup.get(key);
+            if (lookupCount % 100 === 0) {
+                perf.log(`Inventory lookup: ${lookupCount} lookups performed`);
+            }
+            return result;
+        },
+        remove: (entry) => {
+            const key = createInventoryKey(entry.parent, entry.key);
+            lookup.delete(key);
+        },
+        getStats: () => ({ lookupCount, addCount, mapSize: lookup.size }),
+    };
+};
+/**
+ * Determine the container type from a JSON Pointer path.
+ * Analyzes the path tokens to identify the appropriate OpenAPI component container.
+ *
+ * @param path - The JSON Pointer path to analyze
+ * @returns The container type: "schemas", "parameters", "requestBodies", "responses", or "headers"
+ */
+const getContainerTypeFromPath = (path) => {
+    const tokens = pointer_js_1.default.parse(path);
+    const has = (t) => tokens.includes(t);
+    // Prefer more specific containers first
+    if (has("parameters")) {
+        return "parameters";
+    }
+    if (has("requestBody")) {
+        return "requestBodies";
     }
-    return undefined;
+    if (has("headers")) {
+        return "headers";
+    }
+    if (has("responses")) {
+        return "responses";
+    }
+    if (has("schema")) {
+        return "schemas";
+    }
+    // default: treat as schema-like
+    return "schemas";
 };
 /**
  * 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.
  */
-const inventory$Ref = ({ $refKey, $refParent, $refs, indirections, inventory, options, path, pathFromRoot, }) => {
+const inventory$Ref = ({ $refKey, $refParent, $refs, indirections, inventory, inventoryLookup, options, path, pathFromRoot, visitedObjects = new WeakSet(), resolvedRefs = new Map(), }) => {
+    perf.mark("inventory-ref-start");
     const $ref = $refKey === null ? $refParent : $refParent[$refKey];
     const $refPath = url.resolve(path, $ref.$ref);
-    const pointer = $refs._resolve($refPath, pathFromRoot, options);
+    // Check cache first to avoid redundant resolution
+    let pointer = resolvedRefs.get($refPath);
+    if (!pointer) {
+        perf.mark("resolve-start");
+        pointer = $refs._resolve($refPath, pathFromRoot, options);
+        perf.mark("resolve-end");
+        perf.measure("resolve-time", "resolve-start", "resolve-end");
+        if (pointer) {
+            resolvedRefs.set($refPath, pointer);
+            perf.log(`Cached resolved $ref: ${$refPath}`);
+        }
+    }
     if (pointer === null) {
+        perf.mark("inventory-ref-end");
+        perf.measure("inventory-ref-time", "inventory-ref-start", "inventory-ref-end");
         return;
     }
     const parsed = pointer_js_1.default.parse(pathFromRoot);
@@ -75,17 +154,23 @@ const inventory$Ref = ({ $refKey, $refParent, $refs, indirections, inventory, op
     const extended = ref_js_1.default.isExtended$Ref($ref);
     indirections += pointer.indirections;
     // Check if this exact location (parent + key + pathFromRoot) has already been inventoried
-    const existingEntry = findInInventory(inventory, $refParent, $refKey);
+    perf.mark("lookup-start");
+    const existingEntry = inventoryLookup.find($refParent, $refKey);
+    perf.mark("lookup-end");
+    perf.measure("lookup-time", "lookup-start", "lookup-end");
     if (existingEntry && existingEntry.pathFromRoot === pathFromRoot) {
         // This exact location has already been inventoried, so we don't need to process it again
         if (depth < existingEntry.depth || indirections < existingEntry.indirections) {
             removeFromInventory(inventory, existingEntry);
+            inventoryLookup.remove(existingEntry);
         }
         else {
+            perf.mark("inventory-ref-end");
+            perf.measure("inventory-ref-time", "inventory-ref-start", "inventory-ref-end");
             return;
         }
     }
-    inventory.push({
+    const newEntry = {
         $ref, // The JSON Reference (e.g. {$ref: string})
         circular: pointer.circular, // Is this $ref pointer DIRECTLY circular? (i.e. it references itself)
         depth, // How far from the JSON Schema root is this $ref pointer?
@@ -98,9 +183,14 @@ const inventory$Ref = ({ $refKey, $refParent, $refs, indirections, inventory, op
         parent: $refParent, // The object that contains this $ref pointer
         pathFromRoot, // The path to the $ref pointer, from the JSON Schema root
         value: pointer.value, // The resolved value of the $ref pointer
-    });
+        originalContainerType: external ? getContainerTypeFromPath(pointer.path) : undefined, // The original container type in the external file
+    };
+    inventory.push(newEntry);
+    inventoryLookup.add(newEntry);
+    perf.log(`Inventoried $ref: ${$ref.$ref} -> ${file}${hash} (external: ${external}, depth: ${depth})`);
     // Recursively crawl the resolved value
     if (!existingEntry || external) {
+        perf.mark("crawl-recursive-start");
         crawl({
             parent: pointer.value,
             key: null,
@@ -108,18 +198,31 @@ const inventory$Ref = ({ $refKey, $refParent, $refs, indirections, inventory, op
             pathFromRoot,
             indirections: indirections + 1,
             inventory,
+            inventoryLookup,
             $refs,
             options,
+            visitedObjects,
+            resolvedRefs,
         });
+        perf.mark("crawl-recursive-end");
+        perf.measure("crawl-recursive-time", "crawl-recursive-start", "crawl-recursive-end");
     }
+    perf.mark("inventory-ref-end");
+    perf.measure("inventory-ref-time", "inventory-ref-start", "inventory-ref-end");
 };
 /**
  * Recursively crawls the given value, and inventories all JSON references.
  */
-const crawl = ({ $refs, indirections, inventory, key, options, parent, path, pathFromRoot, }) => {
+const crawl = ({ $refs, indirections, inventory, inventoryLookup, key, options, parent, path, pathFromRoot, visitedObjects = new WeakSet(), resolvedRefs = new Map(), }) => {
     const obj = key === null ? parent : parent[key];
     if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj)) {
+        // Early exit if we've already processed this exact object
+        if (visitedObjects.has(obj)) {
+            perf.log(`Skipping already visited object at ${pathFromRoot}`);
+            return;
+        }
         if (ref_js_1.default.isAllowed$Ref(obj)) {
+            perf.log(`Found $ref at ${pathFromRoot}: ${obj.$ref}`);
             inventory$Ref({
                 $refParent: parent,
                 $refKey: key,
@@ -127,11 +230,16 @@ const crawl = ({ $refs, indirections, inventory, key, options, parent, path, pat
                 pathFromRoot,
                 indirections,
                 inventory,
+                inventoryLookup,
                 $refs,
                 options,
+                visitedObjects,
+                resolvedRefs,
             });
         }
         else {
+            // Mark this object as visited BEFORE processing its children
+            visitedObjects.add(obj);
             // 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
@@ -162,8 +270,11 @@ const crawl = ({ $refs, indirections, inventory, key, options, parent, path, pat
                         pathFromRoot: keyPathFromRoot,
                         indirections,
                         inventory,
+                        inventoryLookup,
                         $refs,
                         options,
+                        visitedObjects,
+                        resolvedRefs,
                     });
                 }
                 else {
@@ -174,8 +285,11 @@ const crawl = ({ $refs, indirections, inventory, key, options, parent, path, pat
                         pathFromRoot: keyPathFromRoot,
                         indirections,
                         inventory,
+                        inventoryLookup,
                         $refs,
                         options,
+                        visitedObjects,
+                        resolvedRefs,
                     });
                 }
             }
@@ -183,29 +297,15 @@ const crawl = ({ $refs, indirections, inventory, key, options, parent, path, pat
     }
 };
 /**
- * Re-maps every $ref pointer, so that they're all relative to the root of the JSON Schema.
- * Each referenced value is dereferenced EXACTLY ONCE.  All subsequent references to the same
- * value are re-mapped to point to the first reference.
- *
- * @example: {
- *    first: { $ref: somefile.json#/some/part },
- *    second: { $ref: somefile.json#/another/part },
- *    third: { $ref: somefile.json },
- *    fourth: { $ref: somefile.json#/some/part/sub/part }
- *  }
- *
- * In this example, there are four references to the same file, but since the third reference points
- * to the ENTIRE file, that's the only one we need to dereference.  The other three can just be
- * remapped to point inside the third one.
- *
- * On the other hand, if the third reference DIDN'T exist, then the first and second would both need
- * 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 inventory
+ * Remap external refs by hoisting resolved values into a shared container in the root schema
+ * and pointing all occurrences to those internal definitions. Internal refs remain internal.
  */
-function remap(inventory) {
+function remap(parser, inventory) {
+    perf.log(`Starting remap with ${inventory.length} inventory entries`);
+    perf.mark("remap-start");
+    const root = parser.schema;
     // Group & sort all the $ref pointers, so they're in the order that we need to dereference/remap them
+    perf.mark("sort-inventory-start");
     inventory.sort((a, b) => {
         if (a.file !== b.file) {
             // Group all the $refs that point to the same file
@@ -246,54 +346,189 @@ function remap(inventory) {
             }
         }
     });
-    let file, hash, pathFromRoot;
-    for (const entry of inventory) {
-        // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
-        if (!entry.external && !entry.hash?.startsWith("#/paths/")) {
-            // This $ref already resolves to the main JSON Schema file
-            entry.$ref.$ref = entry.hash;
+    perf.mark("sort-inventory-end");
+    perf.measure("sort-inventory-time", "sort-inventory-start", "sort-inventory-end");
+    perf.log(`Sorted ${inventory.length} inventory entries`);
+    // Ensure or return a container by component type. Prefer OpenAPI-aware placement;
+    // otherwise use existing root containers; otherwise create components/*.
+    const ensureContainer = (type) => {
+        const isOas3 = !!(root && typeof root === "object" && typeof root.openapi === "string");
+        const isOas2 = !!(root && typeof root === "object" && typeof root.swagger === "string");
+        if (isOas3) {
+            if (!root.components || typeof root.components !== "object") {
+                root.components = {};
+            }
+            if (!root.components[type] || typeof root.components[type] !== "object") {
+                root.components[type] = {};
+            }
+            return { obj: root.components[type], prefix: `#/components/${type}` };
         }
-        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;
+        if (isOas2) {
+            if (type === "schemas") {
+                if (!root.definitions || typeof root.definitions !== "object") {
+                    root.definitions = {};
+                }
+                return { obj: root.definitions, prefix: "#/definitions" };
+            }
+            if (type === "parameters") {
+                if (!root.parameters || typeof root.parameters !== "object") {
+                    root.parameters = {};
+                }
+                return { obj: root.parameters, prefix: "#/parameters" };
+            }
+            if (type === "responses") {
+                if (!root.responses || typeof root.responses !== "object") {
+                    root.responses = {};
+                }
+                return { obj: root.responses, prefix: "#/responses" };
+            }
+            // requestBodies/headers don't exist as reusable containers in OAS2; fallback to definitions
+            if (!root.definitions || typeof root.definitions !== "object") {
+                root.definitions = {};
+            }
+            return { obj: root.definitions, prefix: "#/definitions" };
         }
-        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_js_1.default.join(pathFromRoot, pointer_js_1.default.parse(entry.hash.replace(hash, "#")));
+        // No explicit version: prefer existing containers
+        if (root && typeof root === "object") {
+            if (root.components && typeof root.components === "object") {
+                if (!root.components[type] || typeof root.components[type] !== "object") {
+                    root.components[type] = {};
+                }
+                return { obj: root.components[type], prefix: `#/components/${type}` };
+            }
+            if (root.definitions && typeof root.definitions === "object") {
+                return { obj: root.definitions, prefix: "#/definitions" };
+            }
+            // Create components/* by default if nothing exists
+            if (!root.components || typeof root.components !== "object") {
+                root.components = {};
+            }
+            if (!root.components[type] || typeof root.components[type] !== "object") {
+                root.components[type] = {};
+            }
+            return { obj: root.components[type], prefix: `#/components/${type}` };
         }
-        else {
-            // We've moved to a new file or new hash
-            file = entry.file;
-            hash = entry.hash;
-            pathFromRoot = entry.pathFromRoot;
-            // This is the first $ref to point to this value, so dereference the value.
-            // Any other $refs that point to the same value will point to this $ref instead
-            entry.$ref = entry.parent[entry.key] = ref_js_1.default.dereference(entry.$ref, entry.value);
-            if (entry.circular) {
-                // This $ref points to itself
+        // Fallback
+        root.definitions = root.definitions || {};
+        return { obj: root.definitions, prefix: "#/definitions" };
+    };
+    /**
+     * Choose the appropriate component container for bundling.
+     * Prioritizes the original container type from external files over usage location.
+     *
+     * @param entry - The inventory entry containing reference information
+     * @returns The container type to use for bundling
+     */
+    const chooseComponent = (entry) => {
+        // If we have the original container type from the external file, use it
+        if (entry.originalContainerType) {
+            return entry.originalContainerType;
+        }
+        // Fallback to usage path for internal references or when original type is not available
+        return getContainerTypeFromPath(entry.pathFromRoot);
+    };
+    // Track names per (container prefix) and per target
+    const targetToNameByPrefix = new Map();
+    const usedNamesByObj = new Map();
+    const sanitize = (name) => name.replace(/[^A-Za-z0-9_-]/g, "_");
+    const baseName = (filePath) => {
+        try {
+            const withoutHash = filePath.split("#")[0];
+            const parts = withoutHash.split("/");
+            const filename = parts[parts.length - 1] || "schema";
+            const dot = filename.lastIndexOf(".");
+            return sanitize(dot > 0 ? filename.substring(0, dot) : filename);
+        }
+        catch {
+            return "schema";
+        }
+    };
+    const lastToken = (hash) => {
+        if (!hash || hash === "#") {
+            return "root";
+        }
+        const tokens = hash.replace(/^#\//, "").split("/");
+        return sanitize(tokens[tokens.length - 1] || "root");
+    };
+    const uniqueName = (containerObj, proposed) => {
+        if (!usedNamesByObj.has(containerObj)) {
+            usedNamesByObj.set(containerObj, new Set(Object.keys(containerObj || {})));
+        }
+        const used = usedNamesByObj.get(containerObj);
+        let name = proposed;
+        let i = 2;
+        while (used.has(name)) {
+            name = `${proposed}_${i++}`;
+        }
+        used.add(name);
+        return name;
+    };
+    perf.mark("remap-loop-start");
+    for (const entry of inventory) {
+        // Safety check: ensure entry and entry.$ref are valid objects
+        if (!entry || !entry.$ref || typeof entry.$ref !== "object") {
+            perf.warn(`Skipping invalid inventory entry:`, entry);
+            continue;
+        }
+        // Keep internal refs internal
+        if (!entry.external) {
+            if (entry.$ref && typeof entry.$ref === "object") {
+                entry.$ref.$ref = entry.hash;
+            }
+            continue;
+        }
+        // Avoid changing direct self-references; keep them internal
+        if (entry.circular) {
+            if (entry.$ref && typeof entry.$ref === "object") {
                 entry.$ref.$ref = entry.pathFromRoot;
             }
+            continue;
+        }
+        // Choose appropriate container based on original location in external file
+        const component = chooseComponent(entry);
+        const { obj: container, prefix } = ensureContainer(component);
+        const targetKey = `${entry.file}::${entry.hash}`;
+        if (!targetToNameByPrefix.has(prefix)) {
+            targetToNameByPrefix.set(prefix, new Map());
+        }
+        const namesForPrefix = targetToNameByPrefix.get(prefix);
+        let defName = namesForPrefix.get(targetKey);
+        if (!defName) {
+            // If the external file is one of the original input sources, prefer its assigned prefix
+            let proposedBase = baseName(entry.file);
+            try {
+                const parserAny = parser;
+                if (parserAny && parserAny.sourcePathToPrefix && typeof parserAny.sourcePathToPrefix.get === "function") {
+                    const withoutHash = (entry.file || "").split("#")[0];
+                    const mapped = parserAny.sourcePathToPrefix.get(withoutHash);
+                    if (mapped && typeof mapped === "string") {
+                        proposedBase = mapped;
+                    }
+                }
+            }
+            catch {
+                // Ignore errors
+            }
+            const proposed = `${proposedBase}_${lastToken(entry.hash)}`;
+            defName = uniqueName(container, proposed);
+            namesForPrefix.set(targetKey, defName);
+            // Store the resolved value under the container
+            container[defName] = entry.value;
+        }
+        // Point the occurrence to the internal definition, preserving extensions
+        const refPath = `${prefix}/${defName}`;
+        if (entry.extended && entry.$ref && typeof entry.$ref === "object") {
+            entry.$ref.$ref = refPath;
+        }
+        else {
+            entry.parent[entry.key] = { $ref: refPath };
         }
     }
-    // we want to ensure that any $refs that point to another $ref are remapped to point to the final value
-    // let hadChange = true;
-    // while (hadChange) {
-    //   hadChange = false;
-    //   for (const entry of inventory) {
-    //     if (entry.$ref && typeof entry.$ref === "object" && "$ref" in entry.$ref) {
-    //       const resolved = inventory.find((e: InventoryEntry) => e.pathFromRoot === entry.$ref.$ref);
-    //       if (resolved) {
-    //         const resolvedPointsToAnotherRef =
-    //           resolved.$ref && typeof resolved.$ref === "object" && "$ref" in resolved.$ref;
-    //         if (resolvedPointsToAnotherRef && entry.$ref.$ref !== resolved.$ref.$ref) {
-    //           // console.log('Re-mapping $ref pointer "%s" at %s', entry.$ref.$ref, entry.pathFromRoot);
-    //           entry.$ref.$ref = resolved.$ref.$ref;
-    //           hadChange = true;
-    //         }
-    //       }
-    //     }
-    //   }
-    // }
+    perf.mark("remap-loop-end");
+    perf.measure("remap-loop-time", "remap-loop-start", "remap-loop-end");
+    perf.mark("remap-end");
+    perf.measure("remap-total-time", "remap-start", "remap-end");
+    perf.log(`Completed remap of ${inventory.length} entries`);
 }
 function removeFromInventory(inventory, entry) {
     const index = inventory.indexOf(entry);
@@ -309,8 +544,14 @@ function removeFromInventory(inventory, entry) {
  */
 const bundle = (parser, options) => {
     // console.log('Bundling $ref pointers in %s', parser.$refs._root$Ref.path);
+    perf.mark("bundle-start");
     // Build an inventory of all $ref pointers in the JSON Schema
     const inventory = [];
+    const inventoryLookup = createInventoryLookup();
+    perf.log("Starting crawl phase");
+    perf.mark("crawl-phase-start");
+    const visitedObjects = new WeakSet();
+    const resolvedRefs = new Map(); // Cache for resolved $ref targets
     crawl({
         parent: parser,
         key: "schema",
@@ -318,10 +559,40 @@ const bundle = (parser, options) => {
         pathFromRoot: "#",
         indirections: 0,
         inventory,
+        inventoryLookup,
         $refs: parser.$refs,
         options,
+        visitedObjects,
+        resolvedRefs,
     });
+    perf.mark("crawl-phase-end");
+    perf.measure("crawl-phase-time", "crawl-phase-start", "crawl-phase-end");
+    const stats = inventoryLookup.getStats();
+    perf.log(`Crawl phase complete. Found ${inventory.length} $refs. Lookup stats:`, stats);
     // Remap all $ref pointers
-    remap(inventory);
+    perf.log("Starting remap phase");
+    perf.mark("remap-phase-start");
+    remap(parser, inventory);
+    perf.mark("remap-phase-end");
+    perf.measure("remap-phase-time", "remap-phase-start", "remap-phase-end");
+    perf.mark("bundle-end");
+    perf.measure("bundle-total-time", "bundle-start", "bundle-end");
+    perf.log("Bundle complete. Performance summary:");
+    // Log final stats
+    const finalStats = inventoryLookup.getStats();
+    perf.log(`Final inventory stats:`, finalStats);
+    perf.log(`Resolved refs cache size: ${resolvedRefs.size}`);
+    if (DEBUG_PERFORMANCE) {
+        // Log all performance measures
+        const measures = performance.getEntriesByType("measure");
+        measures.forEach((measure) => {
+            if (measure.name.includes("time")) {
+                console.log(`${measure.name}: ${measure.duration.toFixed(2)}ms`);
+            }
+        });
+        // Clear performance marks and measures for next run
+        performance.clearMarks();
+        performance.clearMeasures();
+    }
 };
 exports.bundle = bundle;

package/dist/lib/dereference.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const ref_js_1 = __importDefault(require("./ref.js"));
+const cloneDeep_1 = __importDefault(require("lodash/cloneDeep"));
 const pointer_js_1 = __importDefault(require("./pointer.js"));
 const ono_1 = require("@jsdevtools/ono");
 const url = __importStar(require("./util/url.js"));
@@ -160,10 +161,11 @@ function dereference$Ref($ref, path, pathFromRoot, parents, processedObjects, de
             }
             return {
                 circular: cache.circular,
-                value: Object.assign({}, cache.value, extraKeys),
+                value: Object.assign({}, (0, cloneDeep_1.default)(cache.value), extraKeys),
             };
         }
-        return cache;
+        // Return a deep-cloned value so each occurrence is an independent copy
+        return { circular: cache.circular, value: (0, cloneDeep_1.default)(cache.value) };
     }
     const pointer = $refs._resolve($refPath, path, options);
     if (pointer === null) {

package/dist/lib/index.d.ts

@@ -3,7 +3,7 @@ import type { JSONSchema } from "./types/index.js";
 interface ResolvedInput {
     path: string;
     schema: string | JSONSchema | Buffer | Awaited<JSONSchema> | undefined;
-    type: 'file' | 'json' | 'url';
+    type: "file" | "json" | "url";
 }
 export declare const getResolvedInput: ({ pathOrUrlOrSchema, }: {
     pathOrUrlOrSchema: JSONSchema | string | unknown;
@@ -28,6 +28,9 @@ export declare class $RefParser {
      * @readonly
      */
     schema: JSONSchema | null;
+    schemaMany: JSONSchema[];
+    schemaManySources: string[];
+    sourcePathToPrefix: Map<string, string>;
     /**
      * Bundles all referenced files/URLs into a single schema that only has internal `$ref` pointers. This lets you split-up your schema however you want while you're building it, but easily combine all those files together when it's time to package or distribute the schema to other people. The resulting schema size will be small, since it will still contain internal JSON references rather than being fully-dereferenced.
      *
@@ -43,6 +46,16 @@ export declare class $RefParser {
         pathOrUrlOrSchema: JSONSchema | string | unknown;
         resolvedInput?: ResolvedInput;
     }): Promise<JSONSchema>;
+    /**
+     * Bundles multiple roots (files/URLs/objects) into a single schema by creating a synthetic root
+     * that references each input, resolving all externals, and then hoisting via the existing bundler.
+     */
+    bundleMany({ arrayBuffer, fetch, pathOrUrlOrSchemas, resolvedInputs, }: {
+        arrayBuffer?: ArrayBuffer[];
+        fetch?: RequestInit;
+        pathOrUrlOrSchemas: Array<JSONSchema | string | unknown>;
+        resolvedInputs?: ResolvedInput[];
+    }): Promise<JSONSchema>;
     /**
      * Dereferences all `$ref` pointers in the JSON Schema, replacing each reference with its resolved value. This results in a schema object that does not contain any `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.
      *
@@ -72,6 +85,8 @@ export declare class $RefParser {
     }): Promise<{
         schema: JSONSchema;
     }>;
+    private parseMany;
+    mergeMany(): JSONSchema;
 }
-export { sendRequest } from './resolvers/url.js';
+export { sendRequest } from "./resolvers/url.js";
 export type { JSONSchema } from "./types/index.js";