@scalar/json-magic 0.12.2 → 0.12.4

package/dist/diff/utils.js

@@ -1,48 +1,103 @@
-const isKeyCollisions = (a, b) => {
-  if (typeof a !== typeof b) {
-    return true;
-  }
-  if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
-    const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
-    for (const key of keys) {
-      if (a[key] !== void 0 && b[key] !== void 0) {
-        if (isKeyCollisions(a[key], b[key])) {
-          return true;
+/**
+ * Deep check for objects for collisions
+ * Check primitives if their values are different
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns true if there is a collision, false otherwise
+ *
+ * @example
+ * // Objects with different values for same key
+ * isKeyCollisions({ a: 1 }, { a: 2 }) // true
+ *
+ * // Objects with different types
+ * isKeyCollisions({ a: 1 }, { a: '1' }) // true
+ *
+ * // Objects with no collisions
+ * isKeyCollisions({ a: 1 }, { b: 2 }) // false
+ *
+ * // Nested objects with collision
+ * isKeyCollisions({ a: { b: 1 } }, { a: { b: 2 } }) // true
+ */
+export const isKeyCollisions = (a, b) => {
+    if (typeof a !== typeof b) {
+        return true;
+    }
+    if (typeof a === 'object' && typeof b === 'object' && a !== null && b !== null) {
+        const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+        for (const key of keys) {
+            if (a[key] !== undefined && b[key] !== undefined) {
+                if (isKeyCollisions(a[key], b[key])) {
+                    return true;
+                }
+            }
         }
-      }
+        return false;
     }
-    return false;
-  }
-  return a !== b;
+    // We handle all primitives here
+    return a !== b;
 };
-const mergeObjects = (a, b) => {
-  for (const key in b) {
-    if (!(key in a)) {
-      a[key] = b[key];
-    } else {
-      const aValue = a[key];
-      const bValue = b[key];
-      if (typeof aValue === "object" && aValue !== null && typeof bValue === "object" && bValue !== null) {
-        a[key] = mergeObjects(aValue, bValue);
-      }
+/**
+ * Deep merges two objects, combining their properties recursively.
+ *
+ * ⚠️ Note: This operation assumes there are no key collisions between the objects.
+ * Use isKeyCollisions() to check for collisions before merging.
+ *
+ * @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) {
+        if (!(key in a)) {
+            a[key] = b[key];
+        }
+        else {
+            const aValue = a[key];
+            const bValue = b[key];
+            if (typeof aValue === 'object' && aValue !== null && typeof bValue === 'object' && bValue !== null) {
+                a[key] = mergeObjects(aValue, bValue);
+            }
+        }
     }
-  }
-  return a;
+    return a;
 };
-const isArrayEqual = (a, b) => {
-  if (a.length !== b.length) {
-    return false;
-  }
-  for (let i = 0; i <= a.length; ++i) {
-    if (a[i] !== b[i]) {
-      return false;
+/**
+ * Checks if two arrays have the same elements in the same order.
+ *
+ * @param a - First array to compare
+ * @param b - Second array to compare
+ * @returns True if arrays have same length and elements, false otherwise
+ *
+ * @example
+ * // Arrays with same elements
+ * isArrayEqual([1, 2, 3], [1, 2, 3]) // true
+ *
+ * // Arrays with different elements
+ * isArrayEqual([1, 2, 3], [1, 2, 4]) // false
+ *
+ * // Arrays with different lengths
+ * isArrayEqual([1, 2], [1, 2, 3]) // false
+ */
+export const isArrayEqual = (a, b) => {
+    if (a.length !== b.length) {
+        return false;
     }
-  }
-  return true;
-};
-export {
-  isArrayEqual,
-  isKeyCollisions,
-  mergeObjects
+    for (let i = 0; i <= a.length; ++i) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
 };
-//# sourceMappingURL=utils.js.map

package/dist/helpers/convert-to-local-ref.js

@@ -1,26 +1,33 @@
-const convertToLocalRef = (ref, currentContext, schemas) => {
-  const [baseUrl, pathOrAnchor] = ref.split("#", 2);
-  if (baseUrl) {
-    if (!schemas.has(baseUrl)) {
-      return void 0;
+/**
+ * Translates a JSON Reference ($ref) to a local object path within the root schema.
+ *
+ * @param ref - The JSON Reference string (e.g., "#/foo/bar", "other.json#/baz", "other.json#anchor")
+ * @param currentContext - The current base context (usually the $id of the current schema or parent)
+ * @param schemas - A map of schema identifiers ($id, $anchor) to their local object paths
+ * @returns The local object path as a string, or undefined if the reference cannot be resolved
+ */
+export const convertToLocalRef = (ref, currentContext, schemas) => {
+    // Split the reference into base URL and path/anchor (e.g., "foo.json#/bar" => ["foo.json", "/bar"])
+    const [baseUrl, pathOrAnchor] = ref.split('#', 2);
+    if (baseUrl) {
+        if (!schemas.has(baseUrl)) {
+            return undefined;
+        }
+        if (!pathOrAnchor) {
+            return schemas.get(baseUrl);
+        }
+        // If the pathOrAnchor is a JSON pointer, we need to append it to the baseUrl
+        if (pathOrAnchor.startsWith('/')) {
+            return `${schemas.get(baseUrl)}${pathOrAnchor}`;
+        }
+        // If the pathOrAnchor is an anchor, we need to return the anchor
+        return schemas.get(`${baseUrl}#${pathOrAnchor}`);
     }
-    if (!pathOrAnchor) {
-      return schemas.get(baseUrl);
+    if (pathOrAnchor) {
+        if (pathOrAnchor.startsWith('/')) {
+            return pathOrAnchor.slice(1);
+        }
+        return schemas.get(`${currentContext}#${pathOrAnchor}`);
     }
-    if (pathOrAnchor.startsWith("/")) {
-      return `${schemas.get(baseUrl)}${pathOrAnchor}`;
-    }
-    return schemas.get(`${baseUrl}#${pathOrAnchor}`);
-  }
-  if (pathOrAnchor) {
-    if (pathOrAnchor.startsWith("/")) {
-      return pathOrAnchor.slice(1);
-    }
-    return schemas.get(`${currentContext}#${pathOrAnchor}`);
-  }
-  return void 0;
-};
-export {
-  convertToLocalRef
+    return undefined;
 };
-//# sourceMappingURL=convert-to-local-ref.js.map

package/dist/helpers/escape-json-pointer.js

@@ -1,7 +1,8 @@
-function escapeJsonPointer(str) {
-  return str.replace(/~/g, "~0").replace(/\//g, "~1");
+/**
+ * Escapes a JSON pointer string.
+ *
+ * Example: `/foo/bar~baz` -> `'~1foo~1bar~0baz'`
+ */
+export function escapeJsonPointer(str) {
+    return str.replace(/~/g, '~0').replace(/\//g, '~1');
 }
-export {
-  escapeJsonPointer
-};
-//# sourceMappingURL=escape-json-pointer.js.map

package/dist/helpers/get-schemas.js

@@ -1,37 +1,64 @@
-const getId = (input) => {
-  if (input && typeof input === "object" && input["$id"] && typeof input["$id"] === "string") {
-    return input["$id"];
-  }
-  return void 0;
+/**
+ * Retrieves the $id property from the input object if it exists and is a string.
+ *
+ * @param input - The object to extract the $id from.
+ * @returns The $id string if present, otherwise undefined.
+ */
+export const getId = (input) => {
+    if (input && typeof input === 'object' && input['$id'] && typeof input['$id'] === 'string') {
+        return input['$id'];
+    }
+    return undefined;
 };
+/**
+ * Joins an array of path segments into a single string separated by '/'.
+ *
+ * @param segments - The array of path segments.
+ * @returns The joined path string.
+ */
 const getPath = (segments) => {
-  return segments.join("/");
+    return segments.join('/');
 };
-const getSchemas = (input, base = "", segments = [], map = /* @__PURE__ */ new Map(), visited = /* @__PURE__ */ new WeakSet()) => {
-  if (typeof input !== "object" || input === null) {
-    return map;
-  }
-  if (visited.has(input)) {
-    return map;
-  }
-  visited.add(input);
-  const id = getId(input);
-  if (id) {
-    map.set(id, getPath(segments));
-  }
-  const newBase = id ?? base;
-  if (input["$anchor"] && typeof input["$anchor"] === "string") {
-    map.set(`${newBase}#${input["$anchor"]}`, getPath(segments));
-  }
-  for (const key in input) {
-    if (typeof input[key] === "object" && input[key] !== null) {
-      getSchemas(input[key], newBase, [...segments, key], map, visited);
+/**
+ * Recursively traverses the input object to collect all schemas identified by $id and $anchor properties.
+ *
+ * - If an object has a $id property, it is added to the map with its $id as the key.
+ * - If an object has a $anchor property, it is added to the map with a key composed of the current base and the anchor.
+ * - The function performs a depth-first search (DFS) through all nested objects.
+ *
+ * @param input - The input object to traverse.
+ * @param base - The current base URI, used for resolving anchors.
+ * @param map - The map collecting found schemas.
+ * @returns A map of schema identifiers to their corresponding objects.
+ */
+export const getSchemas = (input, base = '', segments = [], map = new Map(), visited = new WeakSet()) => {
+    // Only process non-null objects
+    if (typeof input !== 'object' || input === null) {
+        return map;
     }
-  }
-  return map;
-};
-export {
-  getId,
-  getSchemas
+    // If the object has already been visited, return the map
+    if (visited.has(input)) {
+        return map;
+    }
+    // Add the object to the visited set
+    visited.add(input);
+    // Attempt to get $id from the current object
+    const id = getId(input);
+    // If $id exists, add the object to the map with $id as the key
+    if (id) {
+        map.set(id, getPath(segments));
+    }
+    // Update the base for nested anchors
+    const newBase = id ?? base;
+    // If $anchor exists, add the object to the map with base#anchor as the key
+    if (input['$anchor'] && typeof input['$anchor'] === 'string') {
+        map.set(`${newBase}#${input['$anchor']}`, getPath(segments));
+    }
+    // Recursively traverse all properties (DFS)
+    for (const key in input) {
+        if (typeof input[key] === 'object' && input[key] !== null) {
+            getSchemas(input[key], newBase, [...segments, key], map, visited);
+        }
+    }
+    return map;
 };
-//# sourceMappingURL=get-schemas.js.map

package/dist/helpers/get-segments-from-path.js

@@ -1,11 +1,15 @@
-import { unescapeJsonPointer } from "./unescape-json-pointer.js";
-function getSegmentsFromPath(path) {
-  return (
+import { unescapeJsonPointer } from './unescape-json-pointer.js';
+/**
+ * Translate `/paths/~1test` to `['paths', '/test']`
+ */
+export function getSegmentsFromPath(path) {
+    return (
     // /paths/~1test
-    path.split("/").slice(1).map(unescapeJsonPointer)
-  );
+    path
+        // ['', 'paths', '~1test']
+        .split('/')
+        // ['paths', '~test']
+        .slice(1)
+        // ['paths', '/test']
+        .map(unescapeJsonPointer));
 }
-export {
-  getSegmentsFromPath
-};
-//# sourceMappingURL=get-segments-from-path.js.map

package/dist/helpers/get-value-by-path.js

@@ -1,23 +1,39 @@
-import { getId } from "../helpers/get-schemas.js";
-function getValueByPath(target, segments) {
-  return segments.reduce(
-    (acc, key) => {
-      if (acc.value === void 0) {
-        return { context: "", value: void 0 };
-      }
-      if (typeof acc.value !== "object" || acc.value === null) {
-        return { context: "", value: void 0 };
-      }
-      const id = getId(acc.value);
-      return { context: id ?? acc.context, value: acc.value?.[key] };
-    },
-    {
-      context: "",
-      value: target
-    }
-  );
+import { getId } from '../helpers/get-schemas.js';
+/**
+ * Traverses an object using an array of string segments (path keys) and returns
+ * the value at the specified path along with its context (id if available).
+ *
+ * @param target - The root object to traverse.
+ * @param segments - An array of string keys representing the path to traverse.
+ * @returns An object containing the final context (id or previous context) and the value at the path.
+ *
+ * @example
+ * const obj = {
+ *   foo: {
+ *     bar: {
+ *       baz: 42
+ *     }
+ *   }
+ * };
+ * // Returns: { context: '', value: 42 }
+ * getValueByPath(obj, ['foo', 'bar', 'baz']);
+ */
+export function getValueByPath(target, segments) {
+    return segments.reduce((acc, key) => {
+        // If the accumulator is undefined, the path does not exist
+        if (acc.value === undefined) {
+            return { context: '', value: undefined };
+        }
+        // If the accumulator is not an object or is null, stop traversal
+        if (typeof acc.value !== 'object' || acc.value === null) {
+            return { context: '', value: undefined };
+        }
+        // Attempt to get the id from the current value for context tracking
+        const id = getId(acc.value);
+        // Return the next context and value for the next iteration
+        return { context: id ?? acc.context, value: acc.value?.[key] };
+    }, {
+        context: '',
+        value: target,
+    });
 }
-export {
-  getValueByPath
-};
-//# sourceMappingURL=get-value-by-path.js.map

package/dist/helpers/is-file-path.js

@@ -1,10 +1,20 @@
-import { isHttpUrl } from "../helpers/is-http-url.js";
-import { isJsonObject } from "../helpers/is-json-object.js";
-import { isYaml } from "../helpers/is-yaml.js";
-function isFilePath(value) {
-  return !isHttpUrl(value) && !isYaml(value) && !isJsonObject(value);
+import { isHttpUrl } from '../helpers/is-http-url.js';
+import { isJsonObject } from '../helpers/is-json-object.js';
+import { isYaml } from '../helpers/is-yaml.js';
+/**
+ * Checks if a string represents a file path by ensuring it's not a remote URL,
+ * YAML content, or JSON content.
+ *
+ * @param value - The string to check
+ * @returns true if the string appears to be a file path, false otherwise
+ * @example
+ * ```ts
+ * isFilePath('./schemas/user.json') // true
+ * isFilePath('https://example.com/schema.json') // false
+ * isFilePath('{"type": "object"}') // false
+ * isFilePath('type: object') // false
+ * ```
+ */
+export function isFilePath(value) {
+    return !isHttpUrl(value) && !isYaml(value) && !isJsonObject(value);
 }
-export {
-  isFilePath
-};
-//# sourceMappingURL=is-file-path.js.map

package/dist/helpers/is-http-url.js

@@ -1,12 +1,21 @@
-function isHttpUrl(value) {
-  try {
-    const url = new URL(value);
-    return url.protocol === "http:" || url.protocol === "https:";
-  } catch {
-    return false;
-  }
+/**
+ * Checks if a string is a remote URL (starts with http:// or https://)
+ * @param value - The URL string to check
+ * @returns true if the string is a remote URL, false otherwise
+ * @example
+ * ```ts
+ * isHttpUrl('https://example.com/schema.json') // true
+ * isHttpUrl('http://api.example.com/schemas/user.json') // true
+ * isHttpUrl('#/components/schemas/User') // false
+ * isHttpUrl('./local-schema.json') // false
+ * ```
+ */
+export function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
 }
-export {
-  isHttpUrl
-};
-//# sourceMappingURL=is-http-url.js.map

package/dist/helpers/is-json-object.js

@@ -1,16 +1,30 @@
-import { isObject } from "@scalar/helpers/object/is-object";
-function isJsonObject(value) {
-  if (!/^\s*(\{)/.test(value.slice(0, 500))) {
-    return false;
-  }
-  try {
-    const val = JSON.parse(value);
-    return isObject(val);
-  } catch {
-    return false;
-  }
+import { isObject } from '@scalar/helpers/object/is-object';
+/**
+ * Determines if a string represents a valid JSON object (i.e., a plain object, not an array, primitive, or null).
+ * The function first checks if the string appears to start with an opening curly brace (ignoring leading whitespace),
+ * which is a quick heuristic to rule out arrays, primitives, and most invalid JSON. If this check passes,
+ * it attempts to parse the string with JSON.parse. The result is then checked to ensure it is a plain object
+ * (not an array, null, or primitive) using the isObject utility.
+ *
+ * @param value - The string to evaluate
+ * @returns true if the string is valid JSON and parses to a plain object, false otherwise
+ *
+ * @example
+ * isJsonObject('{"foo": "bar"}') // true
+ * isJsonObject('[1,2,3]') // false
+ * isJsonObject('not json') // false
+ * isJsonObject('42') // false
+ */
+export function isJsonObject(value) {
+    // Quickly rule out anything that doesn't start with an object brace
+    if (!/^\s*(\{)/.test(value.slice(0, 500))) {
+        return false;
+    }
+    try {
+        const val = JSON.parse(value);
+        return isObject(val);
+    }
+    catch {
+        return false;
+    }
 }
-export {
-  isJsonObject
-};
-//# sourceMappingURL=is-json-object.js.map

package/dist/helpers/is-yaml.js

@@ -1,7 +1,18 @@
-function isYaml(value) {
-  return /^\s*(?:-\s*)?[\w\-]+\s*:\s*.+\n.*/.test(value);
+/**
+ * Checks if a string appears to be YAML content.
+ * This function uses a simple heuristic: it looks for a line that starts with an optional dash,
+ * followed by a key (alphanumeric or dash), a colon, and a value, and then at least one more line.
+ * This is not a full YAML parser, but works for basic detection.
+ *
+ * @param value - The string to check
+ * @returns true if the string looks like YAML, false otherwise
+ *
+ * @example
+ * isYaml('openapi: 3.0.0\ninfo:\n  title: Example') // true
+ * isYaml('{"openapi": "3.0.0", "info": {"title": "Example"}}') // false
+ * isYaml('- name: value\n- name: value2') // true
+ * isYaml('type: object') // false (only one line)
+ */
+export function isYaml(value) {
+    return /^\s*(?:-\s*)?[\w\-]+\s*:\s*.+\n.*/.test(value);
 }
-export {
-  isYaml
-};
-//# sourceMappingURL=is-yaml.js.map

package/dist/helpers/json-path-utils.js

@@ -1,16 +1,31 @@
-function createPathFromSegments(obj, segments) {
-  return segments.reduce((acc, part) => {
-    if (acc[part] === void 0) {
-      if (isNaN(Number(part))) {
-        acc[part] = {};
-      } else {
-        acc[part] = [];
-      }
-    }
-    return acc[part];
-  }, obj);
+/**
+ * Creates a nested path in an object from an array of path segments.
+ * Only creates intermediate objects/arrays if they don't already exist.
+ *
+ * @param obj - The target object to create the path in
+ * @param segments - Array of path segments to create
+ * @returns The final nested object/array at the end of the path
+ *
+ * @example
+ * ```ts
+ * const obj = {}
+ * createPathFromSegments(obj, ['components', 'schemas', 'User'])
+ * // Creates: { components: { schemas: { User: {} } } }
+ *
+ * createPathFromSegments(obj, ['items', '0', 'name'])
+ * // Creates: { items: [{ name: {} }] }
+ * ```
+ */
+export function createPathFromSegments(obj, segments) {
+    return segments.reduce((acc, part) => {
+        if (acc[part] === undefined) {
+            if (isNaN(Number(part))) {
+                acc[part] = {};
+            }
+            else {
+                acc[part] = [];
+            }
+        }
+        return acc[part];
+    }, obj);
 }
-export {
-  createPathFromSegments
-};
-//# sourceMappingURL=json-path-utils.js.map

package/dist/helpers/normalize.js

@@ -1,29 +1,30 @@
-import { parse } from "yaml";
-function normalize(content) {
-  if (content === null) {
-    return void 0;
-  }
-  if (typeof content === "string") {
-    if (content.trim() === "") {
-      return void 0;
+import { parse } from 'yaml';
+/**
+ * Normalize a string (YAML, JSON, object) to a JavaScript datatype.
+ */
+export function normalize(content) {
+    if (content === null) {
+        return undefined;
     }
-    try {
-      return JSON.parse(content);
-    } catch (_error) {
-      const hasColon = /^[^:]+:/.test(content);
-      const isJson = content.slice(0, 50).trimStart().startsWith("{");
-      if (!hasColon || isJson) {
-        return void 0;
-      }
-      return parse(content, {
-        maxAliasCount: 1e4,
-        merge: true
-      });
+    if (typeof content === 'string') {
+        if (content.trim() === '') {
+            return undefined;
+        }
+        try {
+            return JSON.parse(content);
+        }
+        catch (_error) {
+            // Does it look like YAML?
+            const hasColon = /^[^:]+:/.test(content);
+            const isJson = content.slice(0, 50).trimStart().startsWith('{');
+            if (!hasColon || isJson) {
+                return undefined;
+            }
+            return parse(content, {
+                maxAliasCount: 10000,
+                merge: true,
+            });
+        }
     }
-  }
-  return content;
+    return content;
 }
-export {
-  normalize
-};
-//# sourceMappingURL=normalize.js.map