@scalar/openapi-parser 0.29.4 → 0.29.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalar/openapi-parser
 
+## 0.29.5
+
+### Patch Changes
+
+- [#10274](https://github.com/scalar/scalar/pull/10274): Add a standard-agnostic `join` utility with configurable merge strategies and conflict reporting to `@scalar/json-magic/join`. Use it in the OpenAPI parser while retaining OpenAPI upgrades, component prefixes, and OpenAPI conflict reports in the parser.
+
 ## 0.29.4
 
 ## 0.29.3

package/dist/utils/join/join.d.ts

@@ -25,8 +25,8 @@ type JoinResult = {
  *
  * - Merges the "info" object, paths, webhooks, tags, and servers from all input documents.
  * - If there are conflicting paths or webhooks (same path and method), returns a list of conflicts.
- * - Only the first occurrence of a tag (by name) or server (by url) is included.
- * - The merge is performed in reverse order, so the first document in the input array has the highest precedence.
+ * - For tags (by name) and servers (by URL), the last input document wins.
+ * - Metadata uses the first input document when fields overlap.
  *
  * @param inputs - Array of OpenAPI documents (UnknownObject) to join
  * @returns {JoinResult} - { ok: true, document } if successful, or { ok: false, conflicts } if there are conflicts
@@ -44,7 +44,7 @@ type JoinResult = {
  *   tags: [{ name: "bar" }],
  *   servers: [{ url: "https://api2.example.com" }]
  * }
- * const result = join([doc1, doc2])
+ * const result = await join([doc1, doc2])
  * // result.ok === true
  * // result.document.info.title === "API 1"
  * // result.document.info.description === "Second API"

package/dist/utils/join/join.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../../src/utils/join/join.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,QAAQ,IAAI,mBAAmB,EAKhC,MAAM,2BAA2B,CAAA;AAClC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AA+PxD,KAAK,SAAS,GACV;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAC9D,KAAK,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,SAAS,EAAE,CAAA;CAAE,CAAA;AAMrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,IAAI,GAAU,QAAQ,aAAa,EAAE,EAAE,SAAS;IAAE,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAAE,KAAG,OAAO,CAAC,UAAU,CAkE/G,CAAA"}
+{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../../src/utils/join/join.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAgGxD,KAAK,SAAS,GACV;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAC9D,KAAK,UAAU,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,SAAS,EAAE,CAAA;CAAE,CAAA;AAMrG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,IAAI,GAAU,QAAQ,aAAa,EAAE,EAAE,SAAS;IAAE,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAAE,KAAG,OAAO,CAAC,UAAU,CA+E/G,CAAA"}

package/dist/utils/join/join.js

@@ -1,29 +1,8 @@
+import { isObject } from '@scalar/helpers/object/is-object';
 import { isPollutionKey } from '@scalar/helpers/object/prevent-pollution';
 import { bundle } from '@scalar/json-magic/bundle';
-import { mergeObjects } from '../../utils/join/merge-objects.js';
+import { join as joinDocuments } from '@scalar/json-magic/join';
 import { upgrade } from '../../utils/upgrade.js';
-/**
- * Returns the intersection of two sets as an array.
- *
- * @param a - The first set
- * @param b - The second set
- * @returns An array containing the elements present in both sets
- *
- * @example
- * const setA = new Set([1, 2, 3, 4])
- * const setB = new Set([3, 4, 5, 6])
- * const intersection = getSetIntersection(setA, setB)
- * // intersection: [3, 4]
- */
-const getSetIntersection = (a, b) => {
-    const result = [];
-    for (const value of a) {
-        if (b.has(value)) {
-            result.push(value);
-        }
-    }
-    return result;
-};
 /**
  * Returns the value if it is not nullish (or, for arrays, not empty), otherwise returns the provided default value.
  * Useful for handling OpenAPI fields that may be missing or empty.
@@ -37,122 +16,6 @@ const withDefault = (value, defaultValue) => {
     }
     return value ?? defaultValue;
 };
-/**
- * Merges multiple OpenAPI PathsObjects into a single PathsObject.
- * - If a path does not exist in the result, it is added directly.
- * - If a path already exists, its operations (get, post, etc.) are merged.
- * - If the same operation (e.g., "get") exists for the same path in multiple inputs,
- *   a conflict is recorded for that path and method.
- *
- * @param inputs - Array of OpenAPI 3.1 PathsObjects to merge
- * @returns An object containing the merged paths and a list of conflicts
- */
-const mergePaths = (inputs) => {
-    const result = {};
-    const conflicts = [];
-    for (const paths of inputs) {
-        if (typeof paths !== 'object') {
-            continue;
-        }
-        for (const [path, pathItem] of Object.entries(paths)) {
-            if (isPollutionKey(path)) {
-                continue;
-            }
-            if (!Object.hasOwn(result, path) || !result[path]) {
-                // If the path does not exist, add it directly
-                result[path] = pathItem;
-                continue;
-            }
-            // Find intersecting operation keys (e.g., "get", "post") for this path
-            const intersectingKeys = getSetIntersection(new Set(Object.keys(result[path])), new Set(Object.keys(pathItem)));
-            // If the path exists, merge the operations (get, post, etc.)
-            result[path] = { ...result[path], ...pathItem };
-            // Record conflicts for each intersecting operation key
-            intersectingKeys.forEach((key) => conflicts.push({ method: key, path }));
-        }
-    }
-    return { paths: result, conflicts };
-};
-/**
- * Merges multiple arrays of OpenAPI TagObjects into a single array, ensuring uniqueness by tag name.
- * - If a tag with the same name appears in multiple arrays, only the first occurrence is included in the result.
- *
- * @param inputs - Array of arrays of OpenAPI 3.1 TagObjects to merge
- * @returns An array of unique TagObjects (by name)
- */
-const mergeTags = (inputs) => {
-    const cache = new Set();
-    const result = [];
-    for (const tags of inputs) {
-        for (const tag of tags) {
-            if (!cache.has(tag.name)) {
-                result.push(tag);
-            }
-            cache.add(tag.name);
-        }
-    }
-    return result;
-};
-/**
- * Merges multiple arrays of OpenAPI ServerObjects into a single array, ensuring uniqueness by server URL.
- * - If a server with the same URL appears in multiple arrays, only the first occurrence is included in the result.
- *
- * @param inputs - Array of arrays of OpenAPI 3.1 ServerObjects to merge
- * @returns An array of unique ServerObjects (by url)
- */
-const mergeServers = (inputs) => {
-    const cache = new Set();
-    const result = [];
-    for (const servers of inputs) {
-        for (const server of servers) {
-            if (!cache.has(server.url)) {
-                result.push(server);
-            }
-            cache.add(server.url);
-        }
-    }
-    return result;
-};
-/**
- * Merges multiple OpenAPI ComponentsObject instances into a single components object.
- * - If a component with the same type and name appears in multiple inputs, only the first occurrence is included.
- * - Any conflicts (duplicate component names within the same type) are recorded in the `conflicts` array.
- *
- * @param inputs - Array of OpenAPI 3.1 ComponentsObjects to merge
- * @returns An object containing the merged components and an array of conflicts
- */
-const mergeComponents = (inputs) => {
-    const result = {};
-    const conflicts = [];
-    for (const components of inputs) {
-        if (typeof components !== 'object') {
-            continue;
-        }
-        // Merge each component type (schemas, responses, parameters, etc.)
-        for (const [key, value] of Object.entries(components)) {
-            if (isPollutionKey(key)) {
-                continue;
-            }
-            for (const [name, component] of Object.entries(value)) {
-                if (isPollutionKey(name)) {
-                    continue;
-                }
-                if (!Object.hasOwn(result, key)) {
-                    result[key] = {};
-                }
-                if (Object.hasOwn(result[key], name) && result[key][name]) {
-                    // If the component already exists, record a conflict
-                    conflicts.push({ componentType: key, name });
-                }
-                else {
-                    // Otherwise, add the component
-                    result[key][name] = component;
-                }
-            }
-        }
-    }
-    return { components: result, conflicts };
-};
 /**
  * Prefixes component names and their references in multiple OpenAPI documents.
  *
@@ -229,8 +92,8 @@ const asOpenApiDocumentV3_1 = (document) => {
  *
  * - Merges the "info" object, paths, webhooks, tags, and servers from all input documents.
  * - If there are conflicting paths or webhooks (same path and method), returns a list of conflicts.
- * - Only the first occurrence of a tag (by name) or server (by url) is included.
- * - The merge is performed in reverse order, so the first document in the input array has the highest precedence.
+ * - For tags (by name) and servers (by URL), the last input document wins.
+ * - Metadata uses the first input document when fields overlap.
  *
  * @param inputs - Array of OpenAPI documents (UnknownObject) to join
  * @returns {JoinResult} - { ok: true, document } if successful, or { ok: false, conflicts } if there are conflicts
@@ -248,7 +111,7 @@ const asOpenApiDocumentV3_1 = (document) => {
  *   tags: [{ name: "bar" }],
  *   servers: [{ url: "https://api2.example.com" }]
  * }
- * const result = join([doc1, doc2])
+ * const result = await join([doc1, doc2])
  * // result.ok === true
  * // result.document.info.title === "API 1"
  * // result.document.info.description === "Second API"
@@ -257,7 +120,7 @@ const asOpenApiDocumentV3_1 = (document) => {
  * // result.document.servers contains both server URLs
  */
 export const join = async (inputs, config) => {
-    // Reverse the input list and upgrade them (first input has highest precedence)
+    // Keep OpenAPI version normalization separate from the format-independent join.
     const upgraded = inputs.map((it) => upgrade(it).specification);
     // Preprocess documents by prefixing components if specified
     if (config?.prefixComponents) {
@@ -265,49 +128,69 @@ export const join = async (inputs, config) => {
     }
     // Reverse the upgraded documents to ensure the first document has the highest precedence
     upgraded.reverse();
-    // Merge only the "info" object from all inputs
-    const info = upgraded.reduce((acc, curr) => {
-        if (curr.info && typeof curr.info === 'object') {
-            return mergeObjects(acc, curr.info);
+    const documents = upgraded.map((document) => ({
+        ...document,
+        info: isObject(document.info) ? document.info : {},
+        paths: document.paths ?? {},
+        webhooks: document.webhooks ?? {},
+        components: document.components ?? {},
+        tags: document.tags ?? [],
+        servers: document.servers ?? [],
+    }));
+    const result = joinDocuments(documents, {
+        strategy: ({ path, current }) => {
+            const [field] = path;
+            // Keep legacy filtering at merge boundaries, but preserve keys inside copied schemas and examples.
+            if (isPollutionKey(path.at(-1)) && (field === 'info' || field === 'components' || path.length === 2)) {
+                return 'skip';
+            }
+            if (field === 'info') {
+                return 'merge-by-index';
+            }
+            if (field === 'tags') {
+                return { uniqueBy: 'name' };
+            }
+            if (field === 'servers') {
+                return { uniqueBy: 'url' };
+            }
+            if (field === 'paths' || field === 'webhooks' || field === 'components') {
+                if (path.length < 3) {
+                    return 'merge';
+                }
+                // Preserve the existing handling of falsy component definitions.
+                return field === 'components' && !current ? 'replace' : 'conflict';
+            }
+            return 'replace';
+        },
+    });
+    if (result.ok === false) {
+        const conflicts = [];
+        // Keep the public conflict shape and category order stable.
+        for (const field of ['paths', 'webhooks', 'components']) {
+            for (const { path } of result.conflicts) {
+                if (path[0] !== field) {
+                    continue;
+                }
+                if (field === 'components') {
+                    conflicts.push({ type: 'component', componentType: path[1], name: path[2] });
+                }
+                else {
+                    conflicts.push({ type: field === 'paths' ? 'path' : 'webhook', path: path[1], method: path[2] });
+                }
+            }
         }
-        return acc;
-    }, {});
-    // Merge paths from all documents, collecting conflicts
-    const { paths, conflicts: pathConflicts } = mergePaths(upgraded.map((it) => it.paths ?? {}));
-    // Merge webhooks from all documents, collecting conflicts
-    const { paths: webhooks, conflicts: webhookConflicts } = mergePaths(upgraded.map((it) => it.webhooks ?? {}));
-    // Merge tags, ensuring uniqueness by tag name
-    const tags = mergeTags(upgraded.map((it) => it.tags ?? []));
-    // Merge servers, ensuring uniqueness by server url
-    const servers = mergeServers(upgraded.map((it) => it.servers ?? []));
-    // Merge components, collecting conflicts
-    const { components, conflicts: componentConflicts } = mergeComponents(upgraded.map((it) => it.components ?? {}));
-    // Merge all documents in the upgraded array into a single object (shallow merge)
-    const result = upgraded.reduce((acc, curr) => ({ ...acc, ...curr }), {});
-    // Collect all conflicts (paths and webhooks)
-    const conflicts = [
-        ...pathConflicts.map((it) => ({ type: 'path', ...it })),
-        ...webhookConflicts.map((it) => ({ type: 'webhook', ...it })),
-        ...componentConflicts.map((it) => ({ type: 'component', ...it })),
-    ];
-    // If there are any conflicts, return them
-    if (conflicts.length) {
-        return {
-            ok: false,
-            conflicts,
-        };
+        return { ok: false, conflicts };
     }
-    // Return the merged OpenAPI document
     return {
         ok: true,
         document: asOpenApiDocumentV3_1({
-            ...result,
-            info,
-            paths,
-            webhooks: withDefault(webhooks, undefined),
-            tags: withDefault(tags, undefined),
-            servers: withDefault(servers, undefined),
-            components: withDefault(components, undefined),
+            ...result.document,
+            info: result.document.info ?? {},
+            paths: result.document.paths ?? {},
+            webhooks: withDefault(result.document.webhooks, undefined),
+            tags: withDefault(result.document.tags, undefined),
+            servers: withDefault(result.document.servers, undefined),
+            components: withDefault(result.document.components, undefined),
         }),
     };
 };

package/package.json

@@ -17,7 +17,7 @@
     "parser",
     "typescript"
   ],
-  "version": "0.29.4",
+  "version": "0.29.5",
   "engines": {
     "node": ">=22"
   },
@@ -48,12 +48,12 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@scalar/helpers": "0.12.0",
-    "@scalar/json-magic": "0.14.0",
-    "@scalar/openapi-types": "0.9.6",
-    "@scalar/openapi-upgrader": "0.2.17",
-    "@scalar/openapi-validator": "0.1.3",
-    "@scalar/types": "0.20.1",
+    "@scalar/helpers": "0.13.0",
+    "@scalar/json-magic": "0.15.0",
+    "@scalar/openapi-types": "0.9.7",
+    "@scalar/openapi-upgrader": "0.3.0",
+    "@scalar/openapi-validator": "0.1.4",
+    "@scalar/types": "0.21.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/dist/utils/join/merge-objects.d.ts

@@ -1,21 +0,0 @@
-/**
- * Deep merges two objects, combining their properties recursively.
- *
- * ⚠️ Note: This operation assumes there are no key collisions between the objects.
- * @param a - Target object to merge into
- * @param b - Source object to merge from
- * @returns The merged object (mutates and returns a)
- *
- * @example
- * // Simple merge
- * const a = { name: 'John' }
- * const b = { age: 30 }
- * mergeObjects(a, b) // { name: 'John', age: 30 }
- *
- * // Nested merge
- * const a = { user: { name: 'John' } }
- * const b = { user: { age: 30 } }
- * mergeObjects(a, b) // { user: { name: 'John', age: 30 } }
- */
-export declare const mergeObjects: <R>(a: Record<string, unknown>, b: Record<string, unknown>) => R;
-//# sourceMappingURL=merge-objects.d.ts.map

package/dist/utils/join/merge-objects.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"merge-objects.d.ts","sourceRoot":"","sources":["../../../src/utils/join/merge-objects.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,CAwBxF,CAAA"}

package/dist/utils/join/merge-objects.js

@@ -1,45 +0,0 @@
-import { isObjectLike } from '@scalar/helpers/object/is-object';
-import { isPollutionKey } from '@scalar/helpers/object/prevent-pollution';
-/**
- * Deep merges two objects, combining their properties recursively.
- *
- * ⚠️ Note: This operation assumes there are no key collisions between the objects.
- * @param a - Target object to merge into
- * @param b - Source object to merge from
- * @returns The merged object (mutates and returns a)
- *
- * @example
- * // Simple merge
- * const a = { name: 'John' }
- * const b = { age: 30 }
- * mergeObjects(a, b) // { name: 'John', age: 30 }
- *
- * // Nested merge
- * const a = { user: { name: 'John' } }
- * const b = { user: { age: 30 } }
- * mergeObjects(a, b) // { user: { name: 'John', age: 30 } }
- */
-export const mergeObjects = (a, b) => {
-    for (const key in b) {
-        // Skip inherited keys and prototype pollution vectors such as an own `__proto__` key that
-        // survives JSON.parse. Without this guard the recursive merge below would walk into
-        // Object.prototype and pollute it for the whole process.
-        if (!Object.hasOwn(b, key) || isPollutionKey(key)) {
-            continue;
-        }
-        if (!(key in a)) {
-            a[key] = b[key];
-        }
-        else {
-            const aValue = a[key];
-            const bValue = b[key];
-            if (isObjectLike(aValue) && isObjectLike(bValue)) {
-                mergeObjects(aValue, bValue);
-            }
-            else {
-                a[key] = bValue; // Overwrite with b's value if not an object
-            }
-        }
-    }
-    return a;
-};