@scalar/json-magic 0.12.3 → 0.12.4

package/dist/bundle/index.js

@@ -1,6 +1 @@
-import { bundle, resolveAndCopyReferences } from "./bundle.js";
-export {
-  bundle,
-  resolveAndCopyReferences
-};
-//# sourceMappingURL=index.js.map
+export { bundle, resolveAndCopyReferences } from './bundle.js';

package/dist/bundle/plugins/browser.js

@@ -1,9 +1,4 @@
-import { fetchUrls } from "./fetch-urls/index.js";
-import { parseJson } from "./parse-json/index.js";
-import { parseYaml } from "./parse-yaml/index.js";
-export {
-  fetchUrls,
-  parseJson,
-  parseYaml
-};
-//# sourceMappingURL=browser.js.map
+// biome-ignore lint/performance/noBarrelFile: entrypoint
+export { fetchUrls } from './fetch-urls/index.js';
+export { parseJson } from './parse-json/index.js';
+export { parseYaml } from './parse-yaml/index.js';

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

@@ -1,56 +1,83 @@
-import { createLimiter } from "@scalar/helpers/general/create-limiter";
-import { isHttpUrl } from "../../../helpers/is-http-url.js";
-import { normalize } from "../../../helpers/normalize.js";
+import { createLimiter } from '@scalar/helpers/general/create-limiter';
+import { isHttpUrl } from '../../../helpers/is-http-url.js';
+import { normalize } from '../../../helpers/normalize.js';
+/**
+ * Safely checks for host from a URL
+ * Needed because we cannot create a URL from a relative remote URL ex: examples/openapi.json
+ */
 const getHost = (url) => {
-  try {
-    return new URL(url).host;
-  } catch {
-    return null;
-  }
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return null;
+    }
 };
-async function fetchUrl(url, limiter, config) {
-  try {
-    const host = getHost(url);
-    const headers = config?.headers?.find((a) => a.domains.find((d) => d === host) !== void 0)?.headers;
-    const exec = config?.fetch ?? fetch;
-    const result = await limiter(
-      () => exec(url, {
-        headers
-      })
-    );
-    if (result.ok) {
-      const body = await result.text();
-      return {
-        ok: true,
-        data: normalize(body),
-        raw: body
-      };
+/**
+ * Fetches and normalizes data from a remote URL
+ * @param url - The URL to fetch data from
+ * @returns A promise that resolves to either the normalized data or an error result
+ * @example
+ * ```ts
+ * const result = await fetchUrl('https://api.example.com/data.json')
+ * if (result.ok) {
+ *   console.log(result.data) // The normalized data
+ * } else {
+ *   console.log('Failed to fetch data')
+ * }
+ * ```
+ */
+export async function fetchUrl(url, limiter, config) {
+    try {
+        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;
+        const result = await limiter(() => exec(url, {
+            headers,
+        }));
+        if (result.ok) {
+            const body = await result.text();
+            return {
+                ok: true,
+                data: normalize(body),
+                raw: body,
+            };
+        }
+        const contentType = result.headers.get('Content-Type') ?? '';
+        // Warn if the content type is HTML or XML as we only support JSON/YAML
+        if (['text/html', 'application/xml'].includes(contentType)) {
+            console.warn(`[WARN] We only support JSON/YAML formats, received ${contentType}`);
+        }
+        console.warn(`[WARN] Fetch failed with status ${result.status} ${result.statusText} for URL: ${url}`);
+        return {
+            ok: false,
+        };
     }
-    const contentType = result.headers.get("Content-Type") ?? "";
-    if (["text/html", "application/xml"].includes(contentType)) {
-      console.warn(`[WARN] We only support JSON/YAML formats, received ${contentType}`);
+    catch {
+        console.warn(`[WARN] Failed to parse JSON/YAML from URL: ${url}`);
+        return {
+            ok: false,
+        };
     }
-    console.warn(`[WARN] Fetch failed with status ${result.status} ${result.statusText} for URL: ${url}`);
-    return {
-      ok: false
-    };
-  } catch {
-    console.warn(`[WARN] Failed to parse JSON/YAML from URL: ${url}`);
+}
+/**
+ * Creates a plugin for handling remote URL references.
+ * This plugin validates and fetches data from HTTP/HTTPS URLs.
+ *
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * const urlPlugin = fetchUrls()
+ * if (urlPlugin.validate('https://example.com/schema.json')) {
+ *   const result = await urlPlugin.exec('https://example.com/schema.json')
+ * }
+ */
+export function fetchUrls(config) {
+    // If there is a limit specified we limit the number of concurrent calls
+    const limiter = config?.limit ? createLimiter(config.limit) : (fn) => fn();
     return {
-      ok: false
+        type: 'loader',
+        validate: isHttpUrl,
+        exec: (value) => fetchUrl(value, limiter, config),
     };
-  }
-}
-function fetchUrls(config) {
-  const limiter = config?.limit ? createLimiter(config.limit) : (fn) => fn();
-  return {
-    type: "loader",
-    validate: isHttpUrl,
-    exec: (value) => fetchUrl(value, limiter, config)
-  };
 }
-export {
-  fetchUrl,
-  fetchUrls
-};
-//# sourceMappingURL=index.js.map

package/dist/bundle/plugins/node.js

@@ -1,11 +1,5 @@
-import { fetchUrls } from "./fetch-urls/index.js";
-import { parseJson } from "./parse-json/index.js";
-import { parseYaml } from "./parse-yaml/index.js";
-import { readFiles } from "./read-files/index.js";
-export {
-  fetchUrls,
-  parseJson,
-  parseYaml,
-  readFiles
-};
-//# sourceMappingURL=node.js.map
+// biome-ignore lint/performance/noBarrelFile: entrypoint
+export { fetchUrls } from './fetch-urls/index.js';
+export { parseJson } from './parse-json/index.js';
+export { parseYaml } from './parse-yaml/index.js';
+export { readFiles } from './read-files/index.js';

package/dist/bundle/plugins/parse-json/index.js

@@ -1,24 +1,31 @@
-import { isJsonObject } from "../../../helpers/is-json-object.js";
-function parseJson() {
-  return {
-    type: "loader",
-    validate: isJsonObject,
-    exec: (value) => {
-      try {
-        return Promise.resolve({
-          ok: true,
-          data: JSON.parse(value),
-          raw: value
-        });
-      } catch {
-        return Promise.resolve({
-          ok: false
-        });
-      }
-    }
-  };
+import { isJsonObject } from '../../../helpers/is-json-object.js';
+/**
+ * Creates a plugin that parses JSON strings into JavaScript objects.
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * ```ts
+ * const jsonPlugin = parseJson()
+ * const result = jsonPlugin.exec('{"name": "John", "age": 30}')
+ * // result = { name: 'John', age: 30 }
+ * ```
+ */
+export function parseJson() {
+    return {
+        type: 'loader',
+        validate: isJsonObject,
+        exec: (value) => {
+            try {
+                return Promise.resolve({
+                    ok: true,
+                    data: JSON.parse(value),
+                    raw: value,
+                });
+            }
+            catch {
+                return Promise.resolve({
+                    ok: false,
+                });
+            }
+        },
+    };
 }
-export {
-  parseJson
-};
-//# sourceMappingURL=index.js.map

package/dist/bundle/plugins/parse-yaml/index.js

@@ -1,25 +1,32 @@
-import YAML from "yaml";
-import { isYaml } from "../../../helpers/is-yaml.js";
-function parseYaml() {
-  return {
-    type: "loader",
-    validate: isYaml,
-    exec: (value) => {
-      try {
-        return Promise.resolve({
-          ok: true,
-          data: YAML.parse(value, { merge: true, maxAliasCount: 1e4 }),
-          raw: value
-        });
-      } catch {
-        return Promise.resolve({
-          ok: false
-        });
-      }
-    }
-  };
+import YAML from 'yaml';
+import { isYaml } from '../../../helpers/is-yaml.js';
+/**
+ * Creates a plugin that parses YAML strings into JavaScript objects.
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * ```ts
+ * const yamlPlugin = parseYaml()
+ * const result = yamlPlugin.exec('name: John\nage: 30')
+ * // result = { name: 'John', age: 30 }
+ * ```
+ */
+export function parseYaml() {
+    return {
+        type: 'loader',
+        validate: isYaml,
+        exec: (value) => {
+            try {
+                return Promise.resolve({
+                    ok: true,
+                    data: YAML.parse(value, { merge: true, maxAliasCount: 10000 }),
+                    raw: value,
+                });
+            }
+            catch {
+                return Promise.resolve({
+                    ok: false,
+                });
+            }
+        },
+    };
 }
-export {
-  parseYaml
-};
-//# sourceMappingURL=index.js.map

package/dist/bundle/plugins/read-files/index.js

@@ -1,32 +1,53 @@
-import { isFilePath } from "../../../helpers/is-file-path.js";
-import { normalize } from "../../../helpers/normalize.js";
-async function readFile(path) {
-  const fs = typeof window === "undefined" ? await import("node:fs/promises") : void 0;
-  if (fs === void 0) {
-    throw "Can not use readFiles plugin outside of a node environment";
-  }
-  try {
-    const fileContents = await fs.readFile(path, { encoding: "utf-8" });
-    return {
-      ok: true,
-      data: normalize(fileContents),
-      raw: fileContents
-    };
-  } catch {
+import { isFilePath } from '../../../helpers/is-file-path.js';
+import { normalize } from '../../../helpers/normalize.js';
+/**
+ * Reads and normalizes data from a local file
+ * @param path - The file path to read from
+ * @returns A promise that resolves to either the normalized data or an error result
+ * @example
+ * ```ts
+ * const result = await readFile('./schemas/user.json')
+ * if (result.ok) {
+ *   console.log(result.data) // The normalized data
+ * } else {
+ *   console.log('Failed to read file')
+ * }
+ * ```
+ */
+export async function readFile(path) {
+    const fs = typeof window === 'undefined' ? await import('node:fs/promises') : undefined;
+    if (fs === undefined) {
+        throw 'Can not use readFiles plugin outside of a node environment';
+    }
+    try {
+        const fileContents = await fs.readFile(path, { encoding: 'utf-8' });
+        return {
+            ok: true,
+            data: normalize(fileContents),
+            raw: fileContents,
+        };
+    }
+    catch {
+        return {
+            ok: false,
+        };
+    }
+}
+/**
+ * Creates a plugin for handling local file references.
+ * This plugin validates and reads data from local filesystem paths.
+ *
+ * @returns A plugin object with validate and exec functions
+ * @example
+ * const filePlugin = readFiles()
+ * if (filePlugin.validate('./local-schema.json')) {
+ *   const result = await filePlugin.exec('./local-schema.json')
+ * }
+ */
+export function readFiles() {
     return {
-      ok: false
+        type: 'loader',
+        validate: isFilePath,
+        exec: readFile,
     };
-  }
-}
-function readFiles() {
-  return {
-    type: "loader",
-    validate: isFilePath,
-    exec: readFile
-  };
 }
-export {
-  readFile,
-  readFiles
-};
-//# sourceMappingURL=index.js.map

package/dist/bundle/value-generator.js

@@ -1,52 +1,121 @@
-import { generateHash } from "@scalar/helpers/string/generate-hash";
-function getHash(value) {
-  const hashHex = generateHash(value);
-  const hash = hashHex.substring(0, 7);
-  return hash.match(/^\d+$/) ? "a" + hash.substring(1) : hash;
+import { generateHash } from '@scalar/helpers/string/generate-hash';
+/**
+ * Generates a short hash from a string value using xxhash.
+ *
+ * This function is used to create unique identifiers for external references
+ * while keeping the hash length manageable. It uses xxhash-wasm instead of
+ * crypto.subtle because crypto.subtle is only available in secure contexts (HTTPS) or on localhost.
+ * Returns the first 7 characters of the hash string.
+ * If the hash would be all numbers, it ensures at least one letter is included.
+ *
+ * @param value - The string to hash
+ * @returns A Promise that resolves to a 7-character hexadecimal hash with at least one letter
+ * @example
+ * // Returns "2ae91d7"
+ * getHash("https://example.com/schema.json")
+ */
+export function getHash(value) {
+    // Hash the data using xxhash
+    const hashHex = generateHash(value);
+    // Return first 7 characters of the hash, ensuring at least one letter
+    const hash = hashHex.substring(0, 7);
+    return hash.match(/^\d+$/) ? 'a' + hash.substring(1) : hash;
 }
-async function generateUniqueValue(compress, value, compressedToValue, prevCompressedValue, depth = 0) {
-  const MAX_DEPTH = 100;
-  if (depth >= MAX_DEPTH) {
-    throw "Can not generate unique compressed values";
-  }
-  const compressedValue = await compress(prevCompressedValue ?? value);
-  if (compressedToValue[compressedValue] !== void 0 && compressedToValue[compressedValue] !== value) {
-    return generateUniqueValue(compress, value, compressedToValue, compressedValue, depth + 1);
-  }
-  compressedToValue[compressedValue] = value;
-  return compressedValue;
-}
-const uniqueValueGeneratorFactory = (compress, compressedToValue) => {
-  const valueToCompressed = Object.fromEntries(Object.entries(compressedToValue).map(([key, value]) => [value, key]));
-  return {
-    /**
-     * Generates a unique compressed value for the given input string.
-     * First checks if a compressed value already exists in the cache.
-     * If not, generates a new unique compressed value and stores it in the cache.
-     *
-     * @param value - The original string value to compress
-     * @returns A Promise that resolves to the compressed string value
-     *
-     * @example
-     * const generator = uniqueValueGeneratorFactory(compress, {})
-     * const compressed = await generator.generate('example.com/schema.json')
-     * // Returns a unique compressed value like 'example'
-     */
-    generate: async (value) => {
-      const cache = valueToCompressed[value];
-      if (cache) {
-        return cache;
-      }
-      const generatedValue = await generateUniqueValue(compress, value, compressedToValue);
-      const compressedValue = generatedValue.match(/^\d+$/) ? `a${generatedValue}` : generatedValue;
-      valueToCompressed[value] = compressedValue;
-      return compressedValue;
+/**
+ * Generates a unique compressed value for a string, handling collisions by recursively compressing
+ * until a unique value is found. This is used to create unique identifiers for external
+ * references in the bundled OpenAPI document.
+ *
+ * @param compress - Function that generates a compressed value from a string
+ * @param value - The original string value to compress
+ * @param compressedToValue - Object mapping compressed values to their original values
+ * @param prevCompressedValue - Optional previous compressed value to use as input for generating a new value
+ * @param depth - Current recursion depth to prevent infinite loops
+ * @returns A unique compressed value that doesn't conflict with existing values
+ *
+ * @example
+ * const valueMap = {}
+ * // First call generates compressed value for "example.com/schema.json"
+ * const value1 = await generateUniqueValue(compress, "example.com/schema.json", valueMap)
+ * // Returns something like "2ae91d7"
+ *
+ * // Second call with same value returns same compressed value
+ * const value2 = await generateUniqueValue(compress, "example.com/schema.json", valueMap)
+ * // Returns same value as value1
+ *
+ * // Call with different value generates new unique compressed value
+ * const value3 = await generateUniqueValue(compress, "example.com/other.json", valueMap)
+ * // Returns different value like "3bf82e9"
+ */
+export async function generateUniqueValue(compress, value, compressedToValue, prevCompressedValue, depth = 0) {
+    // Prevent infinite recursion by limiting depth
+    const MAX_DEPTH = 100;
+    if (depth >= MAX_DEPTH) {
+        throw 'Can not generate unique compressed values';
     }
-  };
-};
-export {
-  generateUniqueValue,
-  getHash,
-  uniqueValueGeneratorFactory
+    // Compress the value, using previous compressed value if provided
+    const compressedValue = await compress(prevCompressedValue ?? value);
+    // Handle collision by recursively trying with compressed value as input
+    if (compressedToValue[compressedValue] !== undefined && compressedToValue[compressedValue] !== value) {
+        return generateUniqueValue(compress, value, compressedToValue, compressedValue, depth + 1);
+    }
+    // Store mapping and return unique compressed value
+    compressedToValue[compressedValue] = value;
+    return compressedValue;
+}
+/**
+ * Factory function that creates a value generator with caching capabilities.
+ * The generator maintains a bidirectional mapping between original values and their compressed forms.
+ *
+ * @param compress - Function that generates a compressed value from a string
+ * @param compressedToValue - Initial mapping of compressed values to their original values
+ * @returns An object with a generate method that produces unique compressed values
+ *
+ * @example
+ * const compress = (value) => value.substring(0, 6) // Simple compression example
+ * const initialMap = { 'abc123': 'example.com/schema.json' }
+ * const generator = uniqueValueGeneratorFactory(compress, initialMap)
+ *
+ * // Generate compressed value for new string
+ * const compressed = await generator.generate('example.com/other.json')
+ * // Returns something like 'example'
+ *
+ * // Generate compressed value for existing string
+ * const cached = await generator.generate('example.com/schema.json')
+ * // Returns 'abc123' from cache
+ */
+export const uniqueValueGeneratorFactory = (compress, compressedToValue) => {
+    // Create a reverse mapping from original values to their compressed forms
+    const valueToCompressed = Object.fromEntries(Object.entries(compressedToValue).map(([key, value]) => [value, key]));
+    return {
+        /**
+         * Generates a unique compressed value for the given input string.
+         * First checks if a compressed value already exists in the cache.
+         * If not, generates a new unique compressed value and stores it in the cache.
+         *
+         * @param value - The original string value to compress
+         * @returns A Promise that resolves to the compressed string value
+         *
+         * @example
+         * const generator = uniqueValueGeneratorFactory(compress, {})
+         * const compressed = await generator.generate('example.com/schema.json')
+         * // Returns a unique compressed value like 'example'
+         */
+        generate: async (value) => {
+            // Check if we already have a compressed value for this input
+            const cache = valueToCompressed[value];
+            if (cache) {
+                return cache;
+            }
+            // Generate a new unique compressed value
+            const generatedValue = await generateUniqueValue(compress, value, compressedToValue);
+            // Ensure the generated string contains at least one non-numeric character
+            // This prevents the `setValueAtPath` function from interpreting the value as an array index
+            // by forcing it to be treated as an object property name
+            const compressedValue = generatedValue.match(/^\d+$/) ? `a${generatedValue}` : generatedValue;
+            // Store the new mapping in our cache
+            valueToCompressed[value] = compressedValue;
+            return compressedValue;
+        },
+    };
 };
-//# sourceMappingURL=value-generator.js.map

package/dist/dereference/dereference.js

@@ -1,38 +1,68 @@
-import { bundle } from "../bundle/index.js";
-import { fetchUrls } from "../bundle/plugins/fetch-urls/index.js";
-import { createMagicProxy } from "../magic-proxy/index.js";
-const dereference = (input, options) => {
-  if (options?.sync) {
-    return {
-      success: true,
-      data: createMagicProxy(input)
-    };
-  }
-  const errors = [];
-  const plugins = options?.plugins || [fetchUrls()];
-  return bundle(input, {
-    plugins,
-    treeShake: false,
-    urlMap: true,
-    hooks: {
-      onResolveError(node) {
-        errors.push(`Failed to resolve ${node.$ref}`);
-      }
+import { bundle } from '../bundle/index.js';
+import { fetchUrls } from '../bundle/plugins/fetch-urls/index.js';
+import { createMagicProxy } from '../magic-proxy/index.js';
+/**
+ * Dereferences a JSON object, resolving all $ref pointers.
+ *
+ * This function can operate synchronously (no remote refs, no async plugins) or asynchronously (with remote refs).
+ * If `options.sync` is true, it simply wraps the input in a magic proxy and returns it.
+ * Otherwise, it bundles the document, resolving all $refs (including remote ones), and returns a promise.
+ *
+ * @param input - JSON Schema object to dereference.
+ * @param options - Optional settings. If `sync` is true, dereferencing is synchronous. If `plugins` is provided, those plugins are used for resolution instead of the default `fetchUrls()`.
+ * @returns A DereferenceResult (or Promise thereof) indicating success and the dereferenced data, or errors.
+ *
+ * @example
+ * // Synchronous dereference (no remote refs)
+ * const result = dereference({ openapi: '3.0.0', info: { title: 'My API', version: '1.0.0' } }, { sync: true });
+ * if (result.success) {
+ *   console.log(result.data); // Magic proxy-wrapped document
+ * }
+ *
+ * @example
+ * // Asynchronous dereference (with remote refs)
+ * dereference({ $ref: 'https://example.com/api.yaml' })
+ *   .then(result => {
+ *     if (result.success) {
+ *       console.log(result.data); // Fully dereferenced document
+ *     } else {
+ *       console.error(result.errors);
+ *     }
+ *   });
+ *
+ * @example
+ * // Asynchronous dereference (with custom loader plugin)
+ * const plugin = { type: 'loader', validate: (v) => v.startsWith('workspace:'), exec: (v) => resolve(v) };
+ * const result = await dereference({ $ref: 'workspace:my-schema' }, { plugins: [plugin] });
+ */
+export const dereference = (input, options) => {
+    if (options?.sync) {
+        return {
+            success: true,
+            data: createMagicProxy(input),
+        };
     }
-  }).then((result) => {
-    if (errors.length > 0) {
-      return {
-        success: false,
-        errors
-      };
-    }
-    return {
-      success: true,
-      data: createMagicProxy(result)
-    };
-  });
-};
-export {
-  dereference
+    const errors = [];
+    const plugins = options?.plugins || [fetchUrls()];
+    return bundle(input, {
+        plugins,
+        treeShake: false,
+        urlMap: true,
+        hooks: {
+            onResolveError(node) {
+                errors.push(`Failed to resolve ${node.$ref}`);
+            },
+        },
+    }).then((result) => {
+        if (errors.length > 0) {
+            return {
+                success: false,
+                errors,
+            };
+        }
+        return {
+            success: true,
+            data: createMagicProxy(result),
+        };
+    });
 };
-//# sourceMappingURL=dereference.js.map