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

package/lib/dereference.ts

@@ -1,4 +1,5 @@
 import $Ref from "./ref.js";
+import cloneDeep from "lodash/cloneDeep";
 import Pointer from "./pointer.js";
 import { ono } from "@jsdevtools/ono";
 import * as url from "./util/url.js";
@@ -17,10 +18,7 @@ export default dereference;
  * @param parser
  * @param options
  */
-function dereference(
-  parser: $RefParser,
-  options: ParserOptions,
-) {
+function dereference(parser: $RefParser, options: ParserOptions) {
   const start = Date.now();
   // console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
   const dereferenced = crawl<JSONSchema>(
@@ -200,11 +198,12 @@ function dereference$Ref<S extends object = JSONSchema>(
       }
       return {
         circular: cache.circular,
-        value: Object.assign({}, cache.value, extraKeys),
+        value: Object.assign({}, cloneDeep(cache.value), extraKeys),
       };
     }
 
-    return cache;
+    // Return a deep-cloned value so each occurrence is an independent copy
+    return { circular: cache.circular, value: cloneDeep(cache.value) };
   }
 
   const pointer = $refs._resolve($refPath, path, options);

package/lib/index.ts

@@ -14,7 +14,7 @@ import { fileResolver } from "./resolvers/file.js";
 interface ResolvedInput {
   path: string;
   schema: string | JSONSchema | Buffer | Awaited<JSONSchema> | undefined;
-  type: 'file' | 'json' | 'url';
+  type: "file" | "json" | "url";
 }
 
 export const getResolvedInput = ({
@@ -27,10 +27,10 @@ export const getResolvedInput = ({
   }
 
   const resolvedInput: ResolvedInput = {
-    path: typeof pathOrUrlOrSchema === 'string' ? pathOrUrlOrSchema : '',
+    path: typeof pathOrUrlOrSchema === "string" ? pathOrUrlOrSchema : "",
     schema: undefined,
-    type: 'url',
-  }
+    type: "url",
+  };
 
   // If the path is a filesystem path, then convert it to a URL.
   // NOTE: According to the JSON Reference spec, these should already be URLs,
@@ -40,27 +40,36 @@ export const getResolvedInput = ({
   // If it doesn't work for your use-case, then use a URL instead.
   if (resolvedInput.path && url.isFileSystemPath(resolvedInput.path)) {
     resolvedInput.path = url.fromFileSystemPath(resolvedInput.path);
-    resolvedInput.type = 'file';
-  } else if (!resolvedInput.path && pathOrUrlOrSchema && typeof pathOrUrlOrSchema === 'object') {
+    resolvedInput.type = "file";
+  } else if (!resolvedInput.path && pathOrUrlOrSchema && typeof pathOrUrlOrSchema === "object") {
     if ("$id" in pathOrUrlOrSchema && pathOrUrlOrSchema.$id) {
       // when schema id has defined an URL should use that hostname to request the references,
       // instead of using the current page URL
       const { hostname, protocol } = new URL(pathOrUrlOrSchema.$id as string);
       resolvedInput.path = `${protocol}//${hostname}:${protocol === "https:" ? 443 : 80}`;
-      resolvedInput.type = 'url';
+      resolvedInput.type = "url";
     } else {
       resolvedInput.schema = pathOrUrlOrSchema;
-      resolvedInput.type = 'json';
+      resolvedInput.type = "json";
     }
   }
 
-  if (resolvedInput.type !== 'json') {
+  if (resolvedInput.type !== "json") {
     // resolve the absolute path of the schema
     resolvedInput.path = url.resolve(url.cwd(), resolvedInput.path);
   }
 
   return resolvedInput;
-}
+};
+
+const _ensureResolvedInputPath = (input: ResolvedInput, fallbackPath: string): ResolvedInput => {
+  if (input.type === "json" && (!input.path || input.path.length === 0)) {
+    return { ...input, path: fallbackPath };
+  }
+  return input;
+};
+
+// NOTE: previously used helper removed as unused
 
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
@@ -74,7 +83,7 @@ export class $RefParser {
    * @readonly
    */
   $refs = new $Refs<JSONSchema>();
-  public options = getJsonSchemaRefParserDefaultOptions()
+  public options = getJsonSchemaRefParserDefaultOptions();
   /**
    * The parsed (and possibly dereferenced) JSON schema object
    *
@@ -82,6 +91,9 @@ export class $RefParser {
    * @readonly
    */
   public schema: JSONSchema | null = null;
+  public schemaMany: JSONSchema[] = [];
+  public schemaManySources: string[] = [];
+  public sourcePathToPrefix: Map<string, string> = new Map();
 
   /**
    * 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.
@@ -109,6 +121,7 @@ export class $RefParser {
       pathOrUrlOrSchema,
       resolvedInput,
     });
+
     await resolveExternal(this, this.options);
     const errors = JSONParserErrorGroup.getParserErrors(this);
     if (errors.length > 0) {
@@ -122,6 +135,39 @@ export class $RefParser {
     return this.schema!;
   }
 
+  /**
+   * 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.
+   */
+  public async bundleMany({
+    arrayBuffer,
+    fetch,
+    pathOrUrlOrSchemas,
+    resolvedInputs,
+  }: {
+    arrayBuffer?: ArrayBuffer[];
+    fetch?: RequestInit;
+    pathOrUrlOrSchemas: Array<JSONSchema | string | unknown>;
+    resolvedInputs?: ResolvedInput[];
+  }): Promise<JSONSchema> {
+    await this.parseMany({ arrayBuffer, fetch, pathOrUrlOrSchemas, resolvedInputs });
+    this.mergeMany();
+
+    await resolveExternal(this, this.options);
+    const errors = JSONParserErrorGroup.getParserErrors(this);
+    if (errors.length > 0) {
+      throw new JSONParserErrorGroup(this);
+    }
+    _bundle(this, this.options);
+    // Merged root is ready for bundling
+
+    const errors2 = JSONParserErrorGroup.getParserErrors(this);
+    if (errors2.length > 0) {
+      throw new JSONParserErrorGroup(this);
+    }
+    return this.schema!;
+  }
+
   /**
    * 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.
    *
@@ -185,17 +231,17 @@ export class $RefParser {
     if (schema) {
       // immediately add a new $Ref with the schema object as value
       const $ref = this.$refs._add(path);
-      $ref.pathType = url.isFileSystemPath(path) ? 'file' : 'http';
+      $ref.pathType = url.isFileSystemPath(path) ? "file" : "http";
       $ref.value = schema;
-    } else if (type !== 'json') {
-      const file = newFile(path)
+    } else if (type !== "json") {
+      const file = newFile(path);
 
       // Add a new $Ref for this file, even though we don't have the value yet.
       // This ensures that we don't simultaneously read & parse the same file multiple times
       const $refAdded = this.$refs._add(file.url);
       $refAdded.pathType = type;
       try {
-        const resolver = type === 'file' ? fileResolver : urlResolver;
+        const resolver = type === "file" ? fileResolver : urlResolver;
         await resolver.handler({
           arrayBuffer,
           fetch,
@@ -208,12 +254,12 @@ export class $RefParser {
         if (isHandledError(err)) {
           $refAdded.value = err;
         }
-    
+
         throw err;
       }
     }
 
-    if (schema === null || typeof schema !== 'object' || Buffer.isBuffer(schema)) {
+    if (schema === null || typeof schema !== "object" || Buffer.isBuffer(schema)) {
       throw ono.syntax(`"${this.$refs._root$Ref.path || schema}" is not a valid JSON Schema`);
     }
 
@@ -223,7 +269,317 @@ export class $RefParser {
       schema,
     };
   }
+
+  private async parseMany({
+    arrayBuffer,
+    fetch,
+    pathOrUrlOrSchemas,
+    resolvedInputs: _resolvedInputs,
+  }: {
+    arrayBuffer?: ArrayBuffer[];
+    fetch?: RequestInit;
+    pathOrUrlOrSchemas: Array<JSONSchema | string | unknown>;
+    resolvedInputs?: ResolvedInput[];
+  }): Promise<{ schemaMany: JSONSchema[] }> {
+    const resolvedInputs = [...(_resolvedInputs || [])];
+    resolvedInputs.push(...(pathOrUrlOrSchemas.map((schema) => getResolvedInput({ pathOrUrlOrSchema: schema })) || []));
+
+    this.schemaMany = [];
+    this.schemaManySources = [];
+    this.sourcePathToPrefix = new Map();
+
+    for (let i = 0; i < resolvedInputs.length; i++) {
+      const resolvedInput = resolvedInputs[i];
+      const { path, type } = resolvedInput;
+      let { schema } = resolvedInput;
+
+      if (schema) {
+        // keep schema as-is
+      } else if (type !== "json") {
+        const file = newFile(path);
+
+        // Add a new $Ref for this file, even though we don't have the value yet.
+        // This ensures that we don't simultaneously read & parse the same file multiple times
+        const $refAdded = this.$refs._add(file.url);
+        $refAdded.pathType = type;
+        try {
+          const resolver = type === "file" ? fileResolver : urlResolver;
+          await resolver.handler({
+            arrayBuffer: arrayBuffer?.[i],
+            fetch,
+            file,
+          });
+          const parseResult = await parseFile(file, this.options);
+          $refAdded.value = parseResult.result;
+          schema = parseResult.result;
+        } catch (err) {
+          if (isHandledError(err)) {
+            $refAdded.value = err;
+          }
+
+          throw err;
+        }
+      }
+
+      if (schema === null || typeof schema !== "object" || Buffer.isBuffer(schema)) {
+        throw ono.syntax(`"${this.$refs._root$Ref.path || schema}" is not a valid JSON Schema`);
+      }
+
+      this.schemaMany.push(schema);
+      this.schemaManySources.push(path && path.length ? path : url.cwd());
+    }
+
+    return {
+      schemaMany: this.schemaMany,
+    };
+  }
+
+  public mergeMany(): JSONSchema {
+    const schemas = this.schemaMany || [];
+    if (schemas.length === 0) {
+      throw ono("mergeMany called with no schemas. Did you run parseMany?");
+    }
+
+    const merged: any = {};
+
+    // Determine spec version: prefer first occurrence of openapi, else swagger
+    let chosenOpenapi: string | undefined;
+    let chosenSwagger: string | undefined;
+    for (const s of schemas) {
+      if (!chosenOpenapi && s && typeof (s as any).openapi === "string") {
+        chosenOpenapi = (s as any).openapi;
+      }
+      if (!chosenSwagger && s && typeof (s as any).swagger === "string") {
+        chosenSwagger = (s as any).swagger;
+      }
+      if (chosenOpenapi && chosenSwagger) {
+        break;
+      }
+    }
+    if (typeof chosenOpenapi === "string") {
+      merged.openapi = chosenOpenapi;
+    } else if (typeof chosenSwagger === "string") {
+      merged.swagger = chosenSwagger;
+    }
+
+    // Merge info: take first non-empty per-field across inputs
+    const infoAccumulator: any = {};
+    for (const s of schemas) {
+      const info = (s as any)?.info;
+      if (info && typeof info === "object") {
+        for (const [k, v] of Object.entries(info)) {
+          if (infoAccumulator[k] === undefined && v !== undefined) {
+            infoAccumulator[k] = JSON.parse(JSON.stringify(v));
+          }
+        }
+      }
+    }
+    if (Object.keys(infoAccumulator).length > 0) {
+      merged.info = infoAccumulator;
+    }
+
+    // Merge servers: union by url+description
+    const servers: any[] = [];
+    const seenServers = new Set<string>();
+    for (const s of schemas) {
+      const arr = (s as any)?.servers;
+      if (Array.isArray(arr)) {
+        for (const srv of arr) {
+          if (srv && typeof srv === "object") {
+            const key = `${srv.url || ""}|${srv.description || ""}`;
+            if (!seenServers.has(key)) {
+              seenServers.add(key);
+              servers.push(JSON.parse(JSON.stringify(srv)));
+            }
+          }
+        }
+      }
+    }
+    if (servers.length > 0) {
+      merged.servers = servers;
+    }
+
+    merged.paths = {};
+    merged.components = {};
+
+    const componentSections = [
+      "schemas",
+      "parameters",
+      "requestBodies",
+      "responses",
+      "headers",
+      "securitySchemes",
+      "examples",
+      "links",
+      "callbacks",
+    ];
+    for (const sec of componentSections) {
+      merged.components[sec] = {};
+    }
+
+    const tagNameSet = new Set<string>();
+    const tags: any[] = [];
+    const usedOpIds = new Set<string>();
+
+    const baseName = (p: string) => {
+      try {
+        const withoutHash = p.split("#")[0];
+        const parts = withoutHash.split("/");
+        const filename = parts[parts.length - 1] || "schema";
+        const dot = filename.lastIndexOf(".");
+        const raw = dot > 0 ? filename.substring(0, dot) : filename;
+        return raw.replace(/[^A-Za-z0-9_-]/g, "_");
+      } catch {
+        return "schema";
+      }
+    };
+    const unique = (set: Set<string>, proposed: string) => {
+      let name = proposed;
+      let i = 2;
+      while (set.has(name)) {
+        name = `${proposed}_${i++}`;
+      }
+      set.add(name);
+      return name;
+    };
+
+    const rewriteRef = (ref: string, refMap: Map<string, string>): string => {
+      // OAS3: #/components/{section}/{name}...
+      let m = ref.match(/^#\/components\/([^/]+)\/([^/]+)(.*)$/);
+      if (m) {
+        const base = `#/components/${m[1]}/${m[2]}`;
+        const mapped = refMap.get(base);
+        if (mapped) {
+          return mapped + (m[3] || "");
+        }
+      }
+      // OAS2: #/definitions/{name}...
+      m = ref.match(/^#\/definitions\/([^/]+)(.*)$/);
+      if (m) {
+        const base = `#/components/schemas/${m[1]}`;
+        const mapped = refMap.get(base);
+        if (mapped) {
+          // map definitions -> components/schemas
+          return mapped + (m[2] || "");
+        }
+      }
+      return ref;
+    };
+
+    const cloneAndRewrite = (
+      obj: any,
+      refMap: Map<string, string>,
+      tagMap: Map<string, string>,
+      opIdPrefix: string,
+      basePath: string,
+    ): any => {
+      if (obj === null || obj === undefined) {
+        return obj;
+      }
+      if (Array.isArray(obj)) {
+        return obj.map((v) => cloneAndRewrite(v, refMap, tagMap, opIdPrefix, basePath));
+      }
+      if (typeof obj !== "object") {
+        return obj;
+      }
+
+      const out: any = {};
+      for (const [k, v] of Object.entries(obj)) {
+        if (k === "$ref" && typeof v === "string") {
+          const s = v as string;
+          if (s.startsWith("#")) {
+            out[k] = rewriteRef(s, refMap);
+          } else {
+            const proto = url.getProtocol(s);
+            if (proto === undefined) {
+              // relative external ref -> absolutize against source base path
+              out[k] = url.resolve(basePath + "#", s);
+            } else {
+              out[k] = s;
+            }
+          }
+        } else if (k === "tags" && Array.isArray(v) && v.every((x) => typeof x === "string")) {
+          out[k] = v.map((t) => tagMap.get(t) || t);
+        } else if (k === "operationId" && typeof v === "string") {
+          out[k] = unique(usedOpIds, `${opIdPrefix}_${v}`);
+        } else {
+          out[k] = cloneAndRewrite(v as any, refMap, tagMap, opIdPrefix, basePath);
+        }
+      }
+      return out;
+    };
+
+    for (let i = 0; i < schemas.length; i++) {
+      const schema: any = schemas[i] || {};
+      const sourcePath = this.schemaManySources[i] || `multi://input/${i + 1}`;
+      const prefix = baseName(sourcePath);
+
+      // Track prefix for this source path (strip hash). Only map real file/http paths
+      const withoutHash = url.stripHash(sourcePath);
+      const protocol = url.getProtocol(withoutHash);
+      if (protocol === undefined || protocol === "file" || protocol === "http" || protocol === "https") {
+        this.sourcePathToPrefix.set(withoutHash, prefix);
+      }
+
+      const refMap = new Map<string, string>();
+      const tagMap = new Map<string, string>();
+
+      const srcComponents = (schema.components || {}) as any;
+      for (const sec of componentSections) {
+        const group = srcComponents[sec] || {};
+        for (const [name] of Object.entries(group)) {
+          const newName = `${prefix}_${name}`;
+          refMap.set(`#/components/${sec}/${name}`, `#/components/${sec}/${newName}`);
+        }
+      }
+
+      const srcTags: any[] = Array.isArray(schema.tags) ? schema.tags : [];
+      for (const t of srcTags) {
+        if (!t || typeof t !== "object" || typeof t.name !== "string") {
+          continue;
+        }
+        const desired = t.name;
+        const finalName = tagNameSet.has(desired) ? `${prefix}_${desired}` : desired;
+        tagNameSet.add(finalName);
+        tagMap.set(desired, finalName);
+        if (!tags.find((x) => x && x.name === finalName)) {
+          tags.push({ ...t, name: finalName });
+        }
+      }
+
+      for (const sec of componentSections) {
+        const group = (schema.components && schema.components[sec]) || {};
+        for (const [name, val] of Object.entries(group)) {
+          const newName = `${prefix}_${name}`;
+          merged.components[sec][newName] = cloneAndRewrite(val, refMap, tagMap, prefix, url.stripHash(sourcePath));
+        }
+      }
+
+      const srcPaths = (schema.paths || {}) as Record<string, any>;
+      for (const [p, item] of Object.entries(srcPaths)) {
+        let targetPath = p;
+        if (merged.paths[p]) {
+          const trimmed = p.startsWith("/") ? p.substring(1) : p;
+          targetPath = `/${prefix}/${trimmed}`;
+        }
+        merged.paths[targetPath] = cloneAndRewrite(item, refMap, tagMap, prefix, url.stripHash(sourcePath));
+      }
+    }
+
+    if (tags.length > 0) {
+      merged.tags = tags;
+    }
+
+    // Rebuild $refs root using the first input's path to preserve external resolution semantics
+    const rootPath = this.schemaManySources[0] || url.cwd();
+    this.$refs = new $Refs();
+    const rootRef = this.$refs._add(rootPath);
+    rootRef.pathType = url.isFileSystemPath(rootPath) ? "file" : "http";
+    rootRef.value = merged;
+    this.schema = merged;
+    return merged as JSONSchema;
+  }
 }
 
-export { sendRequest } from './resolvers/url.js'
+export { sendRequest } from "./resolvers/url.js";
 export type { JSONSchema } from "./types/index.js";

package/lib/resolve-external.ts

@@ -21,10 +21,7 @@ import { urlResolver } from "./resolvers/url.js";
  * The promise resolves once all JSON references in the schema have been resolved,
  * including nested references that are contained in externally-referenced files.
  */
-export function resolveExternal(
-  parser: $RefParser,
-  options: $RefParserOptions,
-) {
+export function resolveExternal(parser: $RefParser, options: $RefParserOptions) {
   try {
     // console.log('Resolving $ref pointers in %s', parser.$refs._root$Ref.path);
     const promises = crawl(parser.schema, parser.$refs._root$Ref.path + "#", parser.$refs, options);
@@ -101,29 +98,33 @@ async function resolve$Ref<S extends object = JSONSchema>(
 
   // $ref.$ref = url.relative($refs._root$Ref.path, resolvedPath);
 
+  // If this ref points back to an input source we've already merged, avoid re-importing
+  // by checking if the path (without hash) matches a known source in parser and we can serve it internally later.
+  // We keep normal flow but ensure cache hit if already added.
   // Do we already have this $ref?
   const ref = $refs._$refs[withoutHash];
   if (ref) {
-    // We've already parsed this $ref, so use the existing value
-    return Promise.resolve(ref.value);
+    // We've already parsed this $ref, so crawl it to resolve its own externals
+    const promises = crawl(ref.value as S, `${withoutHash}#`, $refs, options, new Set(), true);
+    return Promise.all(promises);
   }
 
   // Parse the $referenced file/url
-  const file = newFile(resolvedPath)
+  const file = newFile(resolvedPath);
 
   // Add a new $Ref for this file, even though we don't have the value yet.
   // This ensures that we don't simultaneously read & parse the same file multiple times
   const $refAdded = $refs._add(file.url);
 
   try {
-    const resolvedInput = getResolvedInput({ pathOrUrlOrSchema: resolvedPath })
+    const resolvedInput = getResolvedInput({ pathOrUrlOrSchema: resolvedPath });
 
     $refAdded.pathType = resolvedInput.type;
 
     let promises: any = [];
 
-    if (resolvedInput.type !== 'json') {
-      const resolver = resolvedInput.type === 'file' ? fileResolver : urlResolver;
+    if (resolvedInput.type !== "json") {
+      const resolver = resolvedInput.type === "file" ? fileResolver : urlResolver;
       await resolver.handler({ file });
       const parseResult = await parseFile(file, options);
       $refAdded.value = parseResult.result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hey-api/json-schema-ref-parser",
-  "version": "1.0.8",
+  "version": "1.2.0",
   "description": "Parse, Resolve, and Dereference JSON Schema $ref pointers",
   "homepage": "https://heyapi.dev/",
   "repository": {