@scalar/json-magic 0.13.4 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @scalar/json-magic
 
+## 0.14.0
+
+### Minor Changes
+
+- [#10241](https://github.com/scalar/scalar/pull/10241): Expose helpers for indexing locally embedded `$id` and `$anchor` resources and resolving a reference to its local path.
+
+### Patch Changes
+
+- [#10257](https://github.com/scalar/scalar/pull/10257): Resolve a relative reference reached through a local pointer during a partial bundle against the document origin; it was resolved against an empty base and failed.
+
+## 0.13.5
+
+### Patch Changes
+
+- [#9817](https://github.com/scalar/scalar/pull/9817): Resolve relative `externalValue` URLs on example objects against the document origin, so external request and response examples load even when referenced with a relative path
+- [#9666](https://github.com/scalar/scalar/pull/9666): Only normalize OpenAPI Reference Objects during bundling, never Schema Objects. `normalizeRefs` used to strip every sibling except `$ref` on any node outside `components/schemas`, which also hit inline schemas. In JSON Schema 2020-12 a `$ref` may legally carry sibling keywords — for example a `$defs`/`$dynamicAnchor` binding that specializes a generic template like `Paginated<T>` — and such schemas appear inline anywhere a schema is allowed (a response's `content.<media>.schema`, an `allOf` branch, …). Dropping those siblings discarded the binding, leaving `$dynamicRef` to resolve to the template's empty fallback and rendering an empty array (for example the `data` array of `GET /planets` in the Scalar Galaxy). Reference Objects are still normalized as before. A new `@scalar/helpers/openapi/is-schema-path` helper detects schema positions.
+- [#10112](https://github.com/scalar/scalar/pull/10112): Pin guarded requests to validated public IP addresses and reject custom transports that bypass the connection checks.
+- [#10140](https://github.com/scalar/scalar/pull/10140): Replace redundant type assertions with compiler-checked annotations, typed accumulators, and existing guards across helpers, API conversion, request handling, and schema rendering.
+
+  Narrow DOM elements and caught errors before accessing their properties. Correct header lookup to include missing values and handle them during PowerShell snippet generation.
+
+  Validate release-note provider responses, represent unresolved references and absent groups in helper return types, and require narrowing merged object values. Preserve AsyncAPI broker credentials separately from HTTP authentication schemes.
+
 ## 0.13.4
 
 ### Patch Changes

package/dist/bundle/bundle.d.ts

@@ -124,13 +124,17 @@ export type LoaderPlugin = {
  *
  * - `path`: The JSON pointer path (as an array of strings) from the document root to the current node.
  * - `resolutionCache`: A cache for storing promises of resolved references.
+ * - `origin`: The origin (URL or file path) of the document this node lives in. Lifecycle plugins can
+ *   use it to resolve relative references (for example an example's `externalValue`) into absolute URLs.
  */
 type NodeProcessContext = {
     path: readonly string[];
+    referencedFromPath?: readonly string[];
     resolutionCache: Map<string, Promise<Readonly<ResolveResult>>>;
     parentNode: UnknownObject | null;
     rootNode: UnknownObject;
     loaders: LoaderPlugin[];
+    origin: string;
 };
 /**
  * A plugin type for lifecycle hooks, allowing custom logic to be injected into the bundler's process.

package/dist/bundle/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/bundle/bundle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/bundle/bundle.ts"],"names":[],"mappings":"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"}

package/dist/bundle/bundle.js

@@ -349,7 +349,7 @@ export async function bundle(input, config) {
             }
         }
     };
-    const bundler = async (root, origin = defaultOrigin, isChunkParent = false, depth = 0, currentPath = [], parent = null) => {
+    const bundler = async (root, origin = defaultOrigin, isChunkParent = false, depth = 0, currentPath = [], parent = null, referencedFromPath) => {
         // If a maximum depth is set in the config, stop bundling when the current depth reaches or exceeds it
         if (config.depth !== undefined && depth > config.depth) {
             return;
@@ -364,15 +364,19 @@ export async function bundle(input, config) {
         }
         // Mark this node as processed before continuing
         processedNodes.add(root);
+        // A node with its own `$id` establishes a new base for resolving relative references within it.
+        // Fall back to the origin inherited from the parent document otherwise.
+        const id = getId(root);
         const context = {
             path: currentPath,
+            referencedFromPath,
             resolutionCache: cache,
             parentNode: parent,
             rootNode: documentRoot,
             loaders: loaderPlugins,
+            origin: id ?? origin,
         };
         await executeHooks('onBeforeNodeProcess', root, context);
-        const id = getId(root);
         if (hasRef(root)) {
             const ref = root['$ref'];
             const isChunk = '$global' in root && typeof root['$global'] === 'boolean' && root['$global'];
@@ -393,7 +397,12 @@ export async function bundle(input, config) {
                     // referenced by this local reference to ensure the partial bundle is complete.
                     // This includes not just the direct reference but also all its dependencies,
                     // creating a complete and self-contained partial bundle.
-                    await bundler(targetValue.value, targetValue.context, isChunkParent, depth + 1, segments, parent);
+                    //
+                    // The pointer addresses the root document, so the target's base is the nearest `$id` on
+                    // the way to it, else the document origin. `getValueByPath` reports no `$id` as an empty
+                    // string, and handing that on as the origin left a relative reference under the target
+                    // (a chunk reference written relative to the document) with nothing to resolve against.
+                    await bundler(targetValue.value, targetValue.context || defaultOrigin, isChunkParent, depth + 1, segments, parent, referencedFromPath);
                 }
                 await executeHooks('onAfterNodeProcess', root, context);
                 return;
@@ -436,11 +445,9 @@ export async function bundle(input, config) {
                     // to handle any nested references it may contain. We pass the resolvedPath as the new origin
                     // to ensure any relative references within this content are resolved correctly relative to
                     // their new location in the bundled document.
-                    await bundler(result.data, isChunk ? origin : resolvedPath, isChunk, depth + 1, [
-                        config.externalDocumentsKey,
-                        compressedPath,
-                        documentRoot[config.externalDocumentsMappingsKey],
-                    ]);
+                    await bundler(result.data, isChunk ? origin : resolvedPath, isChunk, depth + 1, [config.externalDocumentsKey, compressedPath], null, 
+                    // Keep the referring document path across external hops, replacing the storage wrapper.
+                    referencedFromPath ? [...referencedFromPath, ...currentPath.slice(2)] : currentPath);
                     // Store the mapping between hashed keys and original URLs in x-ext-urls
                     // This allows tracking which external URLs were bundled and their corresponding locations
                     setValueAtPath(documentRoot, `/${config.externalDocumentsMappingsKey}/${escapeJsonPointer(compressedPath)}`, relativePath);
@@ -478,7 +485,7 @@ export async function bundle(input, config) {
             if (key === config.externalDocumentsKey || key === config.externalDocumentsMappingsKey) {
                 continue;
             }
-            await bundler(root[key], id ?? origin, isChunkParent, depth + 1, [...currentPath, key], root);
+            await bundler(root[key], id ?? origin, isChunkParent, depth + 1, [...currentPath, key], root, referencedFromPath);
         }
         await executeHooks('onAfterNodeProcess', root, context);
     };

package/dist/bundle/index.d.ts

@@ -1,3 +1,4 @@
+export { resolveReferencePath } from '../helpers/resolve-reference-path.js';
 export type { LifecyclePlugin, LoaderPlugin, Plugin, ResolveResult } from './bundle.js';
 export { bundle, extensions, isLocalRef, prefixInternalRef, prefixInternalRefRecursive, resolveAndCopyReferences, } from './bundle.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/bundle/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundle/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACpF,OAAO,EACL,MAAM,EACN,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,UAAU,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundle/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAEvE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACpF,OAAO,EACL,MAAM,EACN,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,UAAU,CAAA"}

package/dist/bundle/index.js

@@ -1 +1,2 @@
+export { resolveReferencePath } from '../helpers/resolve-reference-path.js';
 export { bundle, extensions, isLocalRef, prefixInternalRef, prefixInternalRefRecursive, resolveAndCopyReferences, } from './bundle.js';

package/dist/bundle/plugins/fetch-urls/fetch-public-url.d.ts

@@ -0,0 +1,3 @@
+/** Fetches through a connection pinned to validated addresses while preserving the host and TLS name. */
+export declare const fetchPublicUrl: (url: string, headers?: HeadersInit) => Promise<Response>;
+//# sourceMappingURL=fetch-public-url.d.ts.map

package/dist/bundle/plugins/fetch-urls/fetch-public-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-public-url.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/fetch-public-url.ts"],"names":[],"mappings":"AAIA,yGAAyG;AACzG,eAAO,MAAM,cAAc,GAAU,KAAK,MAAM,EAAE,UAAU,WAAW,KAAG,OAAO,CAAC,QAAQ,CAwCzF,CAAA"}

package/dist/bundle/plugins/fetch-urls/fetch-public-url.js

@@ -0,0 +1,42 @@
+import { Agent, fetch } from 'undici';
+import { resolvePublicHost } from './is-blocked-host.js';
+/** Fetches through a connection pinned to validated addresses while preserving the host and TLS name. */
+export const fetchPublicUrl = async (url, headers) => {
+    const target = new URL(url);
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+        throw new Error('Only HTTP and HTTPS URLs are supported');
+    }
+    const addresses = await resolvePublicHost(target.hostname);
+    if (!addresses) {
+        throw new Error('Refused to fetch a private or internal address');
+    }
+    // Never resolve the hostname again when connecting. A later DNS answer could point at a private IP.
+    const dispatcher = new Agent({
+        connect: {
+            lookup: (_hostname, options, callback) => {
+                if (options.all) {
+                    callback(null, addresses);
+                }
+                else {
+                    callback(null, addresses[0].address, addresses[0].family);
+                }
+            },
+        },
+    });
+    try {
+        const response = await fetch(target, {
+            headers: Object.fromEntries(new Headers(headers)),
+            redirect: 'error',
+            dispatcher,
+        });
+        const body = !response.ok || [204, 205].includes(response.status) ? null : await response.arrayBuffer();
+        return new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: Object.fromEntries(response.headers),
+        });
+    }
+    finally {
+        await dispatcher.destroy();
+    }
+};

package/dist/bundle/plugins/fetch-urls/index.d.ts

@@ -4,6 +4,7 @@ type FetchConfig = Partial<{
         headers: HeadersInit;
         domains: string[];
     }[];
+    /** Custom transports cannot be combined with blockPrivateNetworks. */
     fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
     /**
      * When true, refuse to fetch URLs that resolve to a private, loopback, link-local, or otherwise

package/dist/bundle/plugins/fetch-urls/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAI3D,KAAK,WAAW,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IACtD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC1F;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAA;CAC9B,CAAC,CAAA;AAyBF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAkExB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG,YAAY,CAShG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAI3D,KAAK,WAAW,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IACtD,sEAAsE;IACtE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAC1F;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAA;CAC9B,CAAC,CAAA;AAcF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA8CxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG,YAAY,CAShG"}

package/dist/bundle/plugins/fetch-urls/index.js

@@ -13,17 +13,6 @@ const getHost = (url) => {
         return null;
     }
 };
-/**
- * Safely reads the hostname (without port) from a URL, for the private-address check.
- */
-const getHostname = (url) => {
-    try {
-        return new URL(url).hostname;
-    }
-    catch {
-        return null;
-    }
-};
 /**
  * Fetches and normalizes data from a remote URL
  * @param url - The URL to fetch data from
@@ -40,32 +29,20 @@ const getHostname = (url) => {
  */
 export async function fetchUrl(url, limiter, config) {
     try {
-        // SSRF guard: optionally refuse to fetch internal or private targets before making the request.
-        // Only runs in Node, since the browser build has no DNS access and its own network isolation.
-        if (config?.blockPrivateNetworks && typeof window === 'undefined') {
-            const hostname = getHostname(url);
-            if (hostname) {
-                const { isBlockedHost } = await import('./is-blocked-host.js');
-                if (await isBlockedHost(hostname)) {
-                    console.warn(`[WARN] Refused to fetch a private or internal address: ${url}`);
-                    return {
-                        ok: false,
-                    };
-                }
-            }
-        }
         const host = getHost(url);
-        // Get the headers that match the domain
         const headers = config?.headers?.find((a) => a.domains.find((d) => d === host) !== undefined)?.headers;
-        const exec = config?.fetch ?? fetch;
-        // Under the SSRF guard, do not follow redirects. Otherwise a public URL that passes the host
-        // check above could redirect to an internal target (for example the metadata endpoint) that
-        // the redirect would reach without being re-validated.
-        const redirect = config?.blockPrivateNetworks && typeof window === 'undefined' ? 'error' : undefined;
-        const result = await limiter(() => exec(url, {
-            headers,
-            redirect,
-        }));
+        const guarded = config?.blockPrivateNetworks && typeof window === 'undefined';
+        const result = await limiter(async () => {
+            if (guarded) {
+                // A custom fetch can ignore the pinned connection and resolve the host again.
+                if (config?.fetch) {
+                    throw new Error('Custom fetch cannot be combined with private network blocking');
+                }
+                const { fetchPublicUrl } = await import('./fetch-public-url.js');
+                return fetchPublicUrl(url, headers);
+            }
+            return (config?.fetch ?? fetch)(url, { headers });
+        });
         if (result.ok) {
             const body = await result.text();
             return {

package/dist/bundle/plugins/fetch-urls/is-blocked-host.d.ts

@@ -1,3 +1,4 @@
+import type { LookupAddress } from 'node:dns';
 /**
  * Reports whether a hostname resolves to a private, loopback, link-local, or otherwise internal
  * address that a bundled `$ref` should not be allowed to reach.
@@ -12,4 +13,6 @@
  * @param hostname - The hostname or IP (brackets around an IPv6 literal are tolerated).
  */
 export declare const isBlockedHost: (hostname: string) => Promise<boolean>;
+/** Resolves a host once and returns only validated public addresses, or null when blocked. */
+export declare const resolvePublicHost: (hostname: string) => Promise<LookupAddress[] | null>;
 //# sourceMappingURL=is-blocked-host.d.ts.map

package/dist/bundle/plugins/fetch-urls/is-blocked-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-blocked-host.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/is-blocked-host.ts"],"names":[],"mappings":"AAmEA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAerE,CAAA"}
+{"version":3,"file":"is-blocked-host.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/is-blocked-host.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAqE7C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,OAAO,CAAiD,CAAA;AAEvH,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,aAAa,EAAE,GAAG,IAAI,CAWxF,CAAA"}

package/dist/bundle/plugins/fetch-urls/is-blocked-host.js

@@ -22,6 +22,7 @@ blockList.addSubnet('fe80::', 10, 'ipv6'); // link-local
 blockList.addSubnet('fc00::', 7, 'ipv6'); // unique local
 blockList.addSubnet('2002::', 16, 'ipv6'); // 6to4
 blockList.addSubnet('64:ff9b::', 96, 'ipv6'); // NAT64
+blockList.addSubnet('64:ff9b:1::', 48, 'ipv6'); // local NAT64 translation prefixes
 blockList.addSubnet('2001::', 32, 'ipv6'); // Teredo
 /**
  * Checks whether a single IP address falls inside a blocked range.
@@ -65,17 +66,16 @@ const ipIsBlocked = (ip) => {
  *
  * @param hostname - The hostname or IP (brackets around an IPv6 literal are tolerated).
  */
-export const isBlockedHost = async (hostname) => {
+export const isBlockedHost = async (hostname) => (await resolvePublicHost(hostname)) === null;
+/** Resolves a host once and returns only validated public addresses, or null when blocked. */
+export const resolvePublicHost = async (hostname) => {
     const host = hostname.replace(/^\[/, '').replace(/\]$/, '');
-    if (isIP(host)) {
-        return ipIsBlocked(host);
-    }
     try {
-        const addresses = await lookup(host, { all: true });
-        return addresses.some(({ address }) => ipIsBlocked(address));
+        const family = isIP(host);
+        const addresses = family ? [{ address: host, family }] : await lookup(host, { all: true });
+        return addresses.length === 0 || addresses.some(({ address }) => ipIsBlocked(address)) ? null : addresses;
     }
     catch {
-        // Block when the host cannot be resolved
-        return true;
+        return null;
     }
 };

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/diff/utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAoCxD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAsB3G,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,YAY7C,CAAA"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/diff/utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,KAAG,OAoCxD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAsB3G,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,YAY7C,CAAA"}

package/dist/diff/utils.js

@@ -1,3 +1,4 @@
+import { isObjectLike } from '@scalar/helpers/object/is-object';
 import { isPollutionKey } from '@scalar/helpers/object/prevent-pollution';
 /**
  * Deep check for objects for collisions
@@ -96,7 +97,7 @@ export const mergeObjects = (a, b) => {
         else {
             const aValue = a[key];
             const bValue = b[key];
-            if (typeof aValue === 'object' && aValue !== null && typeof bValue === 'object' && bValue !== null) {
+            if (isObjectLike(aValue) && isObjectLike(bValue)) {
                 a[key] = mergeObjects(aValue, bValue);
             }
         }

package/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.13.4",
+  "version": "0.14.0",
   "engines": {
     "node": ">=22"
   },
@@ -51,6 +51,16 @@
       "types": "./dist/helpers/escape-json-pointer.d.ts",
       "default": "./dist/helpers/escape-json-pointer.js"
     },
+    "./helpers/convert-to-local-ref": {
+      "import": "./dist/helpers/convert-to-local-ref.js",
+      "types": "./dist/helpers/convert-to-local-ref.d.ts",
+      "default": "./dist/helpers/convert-to-local-ref.js"
+    },
+    "./helpers/get-schemas": {
+      "import": "./dist/helpers/get-schemas.js",
+      "types": "./dist/helpers/get-schemas.d.ts",
+      "default": "./dist/helpers/get-schemas.js"
+    },
     "./helpers/get-segments-from-path": {
       "import": "./dist/helpers/get-segments-from-path.js",
       "types": "./dist/helpers/get-segments-from-path.d.ts",
@@ -107,9 +117,10 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@scalar/helpers": "0.12.0",
     "pathe": "^2.0.3",
-    "yaml": "^2.9.0",
-    "@scalar/helpers": "0.11.3"
+    "undici": "7.24.4",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "fastify": "^5.11.2",