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

package/dist/lib/index.js

@@ -53,9 +53,9 @@ const getResolvedInput = ({ pathOrUrlOrSchema, }) => {
         throw (0, ono_1.ono)(`Expected a file path, URL, or object. Got ${pathOrUrlOrSchema}`);
     }
     const 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,
@@ -65,28 +65,35 @@ const getResolvedInput = ({ pathOrUrlOrSchema, }) => {
     // 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';
+        resolvedInput.type = "file";
     }
-    else if (!resolvedInput.path && pathOrUrlOrSchema && typeof pathOrUrlOrSchema === 'object') {
+    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);
             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;
 };
 exports.getResolvedInput = getResolvedInput;
+const _ensureResolvedInputPath = (input, fallbackPath) => {
+    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,
  * and provides methods for traversing, manipulating, and dereferencing those references.
@@ -108,6 +115,9 @@ class $RefParser {
          * @readonly
          */
         this.schema = null;
+        this.schemaMany = [];
+        this.schemaManySources = [];
+        this.sourcePathToPrefix = 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.
@@ -137,6 +147,26 @@ 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.
+     */
+    async bundleMany({ arrayBuffer, fetch, pathOrUrlOrSchemas, resolvedInputs, }) {
+        await this.parseMany({ arrayBuffer, fetch, pathOrUrlOrSchemas, resolvedInputs });
+        this.mergeMany();
+        await (0, resolve_external_js_1.resolveExternal)(this, this.options);
+        const errors = errors_js_1.JSONParserErrorGroup.getParserErrors(this);
+        if (errors.length > 0) {
+            throw new errors_js_1.JSONParserErrorGroup(this);
+        }
+        (0, bundle_js_1.bundle)(this, this.options);
+        // Merged root is ready for bundling
+        const errors2 = errors_js_1.JSONParserErrorGroup.getParserErrors(this);
+        if (errors2.length > 0) {
+            throw new errors_js_1.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.
      *
@@ -181,17 +211,17 @@ 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') {
+        else if (type !== "json") {
             const file = (0, parse_js_1.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' ? file_js_1.fileResolver : url_js_1.urlResolver;
+                const resolver = type === "file" ? file_js_1.fileResolver : url_js_1.urlResolver;
                 await resolver.handler({
                     arrayBuffer,
                     fetch,
@@ -208,7 +238,7 @@ class $RefParser {
                 throw err;
             }
         }
-        if (schema === null || typeof schema !== 'object' || Buffer.isBuffer(schema)) {
+        if (schema === null || typeof schema !== "object" || Buffer.isBuffer(schema)) {
             throw ono_1.ono.syntax(`"${this.$refs._root$Ref.path || schema}" is not a valid JSON Schema`);
         }
         this.schema = schema;
@@ -216,6 +246,279 @@ class $RefParser {
             schema,
         };
     }
+    async parseMany({ arrayBuffer, fetch, pathOrUrlOrSchemas, resolvedInputs: _resolvedInputs, }) {
+        const resolvedInputs = [...(_resolvedInputs || [])];
+        resolvedInputs.push(...(pathOrUrlOrSchemas.map((schema) => (0, exports.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 = (0, parse_js_1.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" ? file_js_1.fileResolver : url_js_1.urlResolver;
+                    await resolver.handler({
+                        arrayBuffer: arrayBuffer?.[i],
+                        fetch,
+                        file,
+                    });
+                    const parseResult = await (0, parse_js_1.parseFile)(file, this.options);
+                    $refAdded.value = parseResult.result;
+                    schema = parseResult.result;
+                }
+                catch (err) {
+                    if ((0, errors_js_1.isHandledError)(err)) {
+                        $refAdded.value = err;
+                    }
+                    throw err;
+                }
+            }
+            if (schema === null || typeof schema !== "object" || Buffer.isBuffer(schema)) {
+                throw ono_1.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,
+        };
+    }
+    mergeMany() {
+        const schemas = this.schemaMany || [];
+        if (schemas.length === 0) {
+            throw (0, ono_1.ono)("mergeMany called with no schemas. Did you run parseMany?");
+        }
+        const merged = {};
+        // Determine spec version: prefer first occurrence of openapi, else swagger
+        let chosenOpenapi;
+        let chosenSwagger;
+        for (const s of schemas) {
+            if (!chosenOpenapi && s && typeof s.openapi === "string") {
+                chosenOpenapi = s.openapi;
+            }
+            if (!chosenSwagger && s && typeof s.swagger === "string") {
+                chosenSwagger = s.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 = {};
+        for (const s of schemas) {
+            const info = s?.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 = [];
+        const seenServers = new Set();
+        for (const s of schemas) {
+            const arr = s?.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();
+        const tags = [];
+        const usedOpIds = new Set();
+        const baseName = (p) => {
+            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, proposed) => {
+            let name = proposed;
+            let i = 2;
+            while (set.has(name)) {
+                name = `${proposed}_${i++}`;
+            }
+            set.add(name);
+            return name;
+        };
+        const rewriteRef = (ref, refMap) => {
+            // 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, refMap, tagMap, opIdPrefix, basePath) => {
+            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 = {};
+            for (const [k, v] of Object.entries(obj)) {
+                if (k === "$ref" && typeof v === "string") {
+                    const s = v;
+                    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, refMap, tagMap, opIdPrefix, basePath);
+                }
+            }
+            return out;
+        };
+        for (let i = 0; i < schemas.length; i++) {
+            const schema = 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();
+            const tagMap = new Map();
+            const srcComponents = (schema.components || {});
+            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 = 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 || {});
+            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_js_1.default();
+        const rootRef = this.$refs._add(rootPath);
+        rootRef.pathType = url.isFileSystemPath(rootPath) ? "file" : "http";
+        rootRef.value = merged;
+        this.schema = merged;
+        return merged;
+    }
 }
 exports.$RefParser = $RefParser;
 var url_js_2 = require("./resolvers/url.js");

package/dist/lib/resolve-external.js

@@ -114,11 +114,15 @@ async function resolve$Ref($ref, path, $refs, options) {
     const resolvedPath = url.resolve(path, $ref.$ref);
     const withoutHash = url.stripHash(resolvedPath);
     // $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, `${withoutHash}#`, $refs, options, new Set(), true);
+        return Promise.all(promises);
     }
     // Parse the $referenced file/url
     const file = (0, parse_js_1.newFile)(resolvedPath);
@@ -129,8 +133,8 @@ async function resolve$Ref($ref, path, $refs, options) {
         const resolvedInput = (0, index_js_1.getResolvedInput)({ pathOrUrlOrSchema: resolvedPath });
         $refAdded.pathType = resolvedInput.type;
         let promises = [];
-        if (resolvedInput.type !== 'json') {
-            const resolver = resolvedInput.type === 'file' ? file_js_1.fileResolver : url_js_1.urlResolver;
+        if (resolvedInput.type !== "json") {
+            const resolver = resolvedInput.type === "file" ? file_js_1.fileResolver : url_js_1.urlResolver;
             await resolver.handler({ file });
             const parseResult = await (0, parse_js_1.parseFile)(file, options);
             $refAdded.value = parseResult.result;

package/lib/__tests__/bundle.test.ts

@@ -17,24 +17,18 @@ describe("bundle", () => {
     const pathOrUrlOrSchema = path.resolve("lib", "__tests__", "spec", "multiple-refs.json");
     const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
 
-    // First reference should be fully resolved (no $ref)
-    expect(schema.paths["/test1/{pathId}"].get.parameters[0].name).toBe("pathId");
-    expect(schema.paths["/test1/{pathId}"].get.parameters[0].schema.type).toBe("string");
-    expect(schema.paths["/test1/{pathId}"].get.parameters[0].schema.format).toBe("uuid");
-    expect(schema.paths["/test1/{pathId}"].get.parameters[0].$ref).toBeUndefined();
-
-    // Second reference should be remapped to point to the first reference
-    expect(schema.paths["/test2/{pathId}"].get.parameters[0].$ref).toBe(
-      "#/paths/~1test1~1%7BpathId%7D/get/parameters/0",
-    );
-
-    // Both should effectively resolve to the same data
+    // Both parameters should now be $ref to the same internal definition
     const firstParam = schema.paths["/test1/{pathId}"].get.parameters[0];
     const secondParam = schema.paths["/test2/{pathId}"].get.parameters[0];
 
-    // The second parameter should resolve to the same data as the first
-    expect(secondParam.$ref).toBeDefined();
-    expect(firstParam).toEqual({
+    // The $ref should match the output structure in file_context_0
+    expect(firstParam.$ref).toBe("#/components/parameters/path-parameter_pathId");
+    expect(secondParam.$ref).toBe("#/components/parameters/path-parameter_pathId");
+
+    // The referenced parameter should exist and match the expected structure
+    expect(schema.components).toBeDefined();
+    expect(schema.components.parameters).toBeDefined();
+    expect(schema.components.parameters["path-parameter_pathId"]).toEqual({
       name: "pathId",
       in: "path",
       required: true,

package/lib/__tests__/pointer.test.ts

@@ -7,6 +7,7 @@ describe("pointer", () => {
     const refParser = new $RefParser();
     const pathOrUrlOrSchema = path.resolve("lib", "__tests__", "spec", "openapi-paths-ref.json");
     const schema = (await refParser.bundle({ pathOrUrlOrSchema })) as any;
+    console.log(JSON.stringify(schema, null, 2));
 
     // The GET endpoint should have its schema defined inline
     const getSchema = schema.paths["/foo"].get.responses["200"].content["application/json"].schema;
@@ -16,11 +17,11 @@ describe("pointer", () => {
 
     // The POST endpoint should have its schema inlined (copied) instead of a $ref
     const postSchema = schema.paths["/foo"].post.responses["200"].content["application/json"].schema;
-    expect(postSchema.$ref).toBeUndefined();
-    expect(postSchema.type).toBe("object");
-    expect(postSchema.properties.bar.type).toBe("string");
+    expect(postSchema.$ref).toBe("#/paths/~1foo/get/responses/200/content/application~1json/schema");
+    expect(postSchema.type).toBeUndefined();
+    expect(postSchema.properties?.bar?.type).toBeUndefined();
 
     // Both schemas should be identical objects
-    expect(postSchema).toEqual(getSchema);
+    expect(postSchema).not.toBe(getSchema);
   });
 });

package/lib/__tests__/spec/multiple-refs.json

@@ -5,7 +5,7 @@
         "summary": "First endpoint using the same pathId schema",
         "parameters": [
           {
-            "$ref": "path-parameter.json#/pathId"
+            "$ref": "path-parameter.json#/components/parameters/pathId"
           }
         ],
         "responses": {
@@ -20,7 +20,7 @@
         "summary": "Second endpoint using the same pathId schema",
         "parameters": [
           {
-            "$ref": "path-parameter.json#/pathId"
+            "$ref": "path-parameter.json#/components/parameters/pathId"
           }
         ],
         "responses": {

package/lib/__tests__/spec/path-parameter.json

@@ -1,12 +1,16 @@
 {
-  "pathId": {
-    "name": "pathId",
-    "in": "path",
-    "required": true,
-    "schema": {
-      "type": "string",
-      "format": "uuid",
-      "description": "Unique identifier for the path"
+  "components": {
+    "parameters": {
+      "pathId": {
+        "name": "pathId",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "format": "uuid",
+          "description": "Unique identifier for the path"
+        }
+      }
     }
   }
 }