@scalar/json-magic 0.3.0 → 0.4.0

package/.turbo/turbo-build.log

@@ -1,10 +1,10 @@
 
-> @scalar/json-magic@0.3.0 build /home/runner/work/scalar/scalar/packages/json-magic
+> @scalar/json-magic@0.4.0 build /home/runner/work/scalar/scalar/packages/json-magic
 > scalar-build-esbuild
 
-@scalar/json-magic: Build completed in 42.56ms
+@scalar/json-magic: Build completed in 27.42ms
 
-> @scalar/json-magic@0.3.0 types:build /home/runner/work/scalar/scalar/packages/json-magic
+> @scalar/json-magic@0.4.0 types:build /home/runner/work/scalar/scalar/packages/json-magic
 > scalar-types-build
 
-Types build completed in 1.52s
+Types build completed in 1.60s

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @scalar/json-magic
 
+## 0.4.0
+
+### Minor Changes
+
+- 99894bc: feat: correctly validate the schemas
+
+### Patch Changes
+
+- 06a46f0: fix: add proxy cache to fix reactivity issues
+- 63283aa: fix: use hidden properties during validation
+- Updated dependencies [98c55d0]
+- Updated dependencies [0e747c7]
+  - @scalar/helpers@0.0.9
+
+## 0.3.1
+
+### Patch Changes
+
+- 88385b1: fix: external ref linking when starting with a /
+
 ## 0.3.0
 
 ### Minor Changes

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

@@ -63,6 +63,10 @@ function resolveReferencePath(base, relativePath) {
   }
   if (isRemoteUrl(base)) {
     const url = new URL(base);
+    if (relativePath.startsWith("/")) {
+      url.pathname = relativePath;
+      return url.toString();
+    }
     const mergedPath = path.join(path.dirname(url.pathname), relativePath);
     return new URL(mergedPath, base).toString();
   }

package/dist/bundle/bundle.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/bundle/bundle.ts"],
-  "sourcesContent": ["import type { UnknownObject } from '@/types'\n\nimport { escapeJsonPointer } from '../utils/escape-json-pointer'\nimport path from '@/polyfills/path'\nimport { getSegmentsFromPath } from '../utils/get-segments-from-path'\nimport { isObject } from '../utils/is-object'\nimport { isYaml } from '../utils/is-yaml'\nimport { isJsonObject } from '../utils/is-json-object'\nimport { getHash, uniqueValueGeneratorFactory } from './value-generator'\n\n/**\n * Checks if a string is a remote URL (starts with http:// or https://)\n * @param value - The URL string to check\n * @returns true if the string is a remote URL, false otherwise\n * @example\n * ```ts\n * isRemoteUrl('https://example.com/schema.json') // true\n * isRemoteUrl('http://api.example.com/schemas/user.json') // true\n * isRemoteUrl('#/components/schemas/User') // false\n * isRemoteUrl('./local-schema.json') // false\n * ```\n */\nexport function isRemoteUrl(value: string) {\n  try {\n    const url = new URL(value)\n    return url.protocol === 'http:' || url.protocol === 'https:'\n  } catch {\n    return false\n  }\n}\n\n/**\n * Checks if a string represents a file path by ensuring it's not a remote URL,\n * YAML content, or JSON content.\n *\n * @param value - The string to check\n * @returns true if the string appears to be a file path, false otherwise\n * @example\n * ```ts\n * isFilePath('./schemas/user.json') // true\n * isFilePath('https://example.com/schema.json') // false\n * isFilePath('{\"type\": \"object\"}') // false\n * isFilePath('type: object') // false\n * ```\n */\nexport function isFilePath(value: string) {\n  return !isRemoteUrl(value) && !isYaml(value) && !isJsonObject(value)\n}\n\n/**\n * Checks if a string is a local reference (starts with #)\n * @param value - The reference string to check\n * @returns true if the string is a local reference, false otherwise\n * @example\n * ```ts\n * isLocalRef('#/components/schemas/User') // true\n * isLocalRef('https://example.com/schema.json') // false\n * isLocalRef('./local-schema.json') // false\n * ```\n */\nexport function isLocalRef(value: string): boolean {\n  return value.startsWith('#')\n}\n\nexport type ResolveResult = { ok: true; data: unknown } | { ok: false }\n\n/**\n * Resolves a string by finding and executing the appropriate plugin.\n * @param value - The string to resolve (URL, file path, etc)\n * @param plugins - Array of plugins that can handle different types of strings\n * @returns A promise that resolves to either the content or an error result\n * @example\n * // Using a URL plugin\n * await resolveContents('https://example.com/schema.json', [urlPlugin])\n * // Using a file plugin\n * await resolveContents('./schemas/user.json', [filePlugin])\n * // No matching plugin returns { ok: false }\n * await resolveContents('#/components/schemas/User', [urlPlugin, filePlugin])\n */\nasync function resolveContents(value: string, plugins: LoaderPlugin[]): Promise<ResolveResult> {\n  const plugin = plugins.find((p) => p.validate(value))\n\n  if (plugin) {\n    return plugin.exec(value)\n  }\n\n  return {\n    ok: false,\n  }\n}\n\n/**\n * Retrieves a nested value from an object using an array of property segments.\n * @param target - The target object to traverse\n * @param segments - Array of property names representing the path to the desired value\n * @returns The value at the specified path, or undefined if the path doesn't exist\n * @example\n * const obj = { foo: { bar: { baz: 42 } } };\n * getNestedValue(obj, ['foo', 'bar', 'baz']); // returns 42\n */\nexport function getNestedValue(target: Record<string, any>, segments: string[]) {\n  return segments.reduce<any>((acc, key) => {\n    if (acc === undefined) {\n      return undefined\n    }\n    return acc[key]\n  }, target)\n}\n\n/**\n * Sets a value at a specified path in an object, creating intermediate objects/arrays as needed.\n * This function traverses the object structure and creates any missing intermediate objects\n * or arrays based on the path segments. If the next segment is a numeric string, it creates\n * an array instead of an object.\n *\n * \u26A0\uFE0F Warning: Be careful with object keys that look like numbers (e.g. \"123\") as this function\n * will interpret them as array indices and create arrays instead of objects. If you need to\n * use numeric-looking keys, consider prefixing them with a non-numeric character.\n *\n * @param obj - The target object to set the value in\n * @param path - The JSON pointer path where the value should be set\n * @param value - The value to set at the specified path\n * @throws {Error} If attempting to set a value at the root path ('')\n *\n * @example\n * const obj = {}\n * setValueAtPath(obj, '/foo/bar/0', 'value')\n * // Result:\n * // {\n * //   foo: {\n * //     bar: ['value']\n * //   }\n * // }\n *\n * @example\n * const obj = { existing: { path: 'old' } }\n * setValueAtPath(obj, '/existing/path', 'new')\n * // Result:\n * // {\n * //   existing: {\n * //     path: 'new'\n * //   }\n * // }\n *\n * @example\n * // \u26A0\uFE0F Warning: This will create an array instead of an object with key \"123\"\n * setValueAtPath(obj, '/foo/123/bar', 'value')\n * // Result:\n * // {\n * //   foo: [\n * //     undefined,\n * //     undefined,\n * //     undefined,\n * //     { bar: 'value' }\n * //   ]\n * // }\n */\nexport function setValueAtPath(obj: any, path: string, value: any): void {\n  if (path === '') {\n    throw new Error(\"Cannot set value at root ('') pointer\")\n  }\n\n  const parts = getSegmentsFromPath(path)\n\n  let current = obj\n\n  for (let i = 0; i < parts.length; i++) {\n    const key = parts[i]\n    const isLast = i === parts.length - 1\n\n    const nextKey = parts[i + 1]\n    const shouldBeArray = /^\\d+$/.test(nextKey ?? '')\n\n    if (isLast) {\n      current[key] = value\n    } else {\n      if (!(key in current) || typeof current[key] !== 'object') {\n        current[key] = shouldBeArray ? [] : {}\n      }\n      current = current[key]\n    }\n  }\n}\n\n/**\n * Resolves a reference path by combining a base path with a relative path.\n * Handles both remote URLs and local file paths.\n *\n * @param base - The base path (can be a URL or local file path)\n * @param relativePath - The relative path to resolve against the base\n * @returns The resolved absolute path\n * @example\n * // Resolve remote URL\n * resolveReferencePath('https://example.com/api/schema.json', 'user.json')\n * // Returns: 'https://example.com/api/user.json'\n *\n * // Resolve local path\n * resolveReferencePath('/path/to/schema.json', 'user.json')\n * // Returns: '/path/to/user.json'\n */\nfunction resolveReferencePath(base: string, relativePath: string) {\n  if (isRemoteUrl(relativePath)) {\n    return relativePath\n  }\n\n  if (isRemoteUrl(base)) {\n    const url = new URL(base)\n\n    const mergedPath = path.join(path.dirname(url.pathname), relativePath)\n    return new URL(mergedPath, base).toString()\n  }\n\n  return path.join(path.dirname(base), relativePath)\n}\n\n/**\n * Prefixes an internal JSON reference with a given path prefix.\n * Takes a local reference (starting with #) and prepends the provided prefix segments.\n *\n * @param input - The internal reference string to prefix (must start with #)\n * @param prefix - Array of path segments to prepend to the reference\n * @returns The prefixed reference string\n * @throws Error if input is not a local reference\n * @example\n * prefixInternalRef('#/components/schemas/User', ['definitions'])\n * // Returns: '#/definitions/components/schemas/User'\n */\nexport function prefixInternalRef(input: string, prefix: string[]) {\n  if (!isLocalRef(input)) {\n    throw 'Please provide an internal ref'\n  }\n\n  return `#/${prefix.map(escapeJsonPointer).join('/')}${input.substring(1)}`\n}\n\n/**\n * Updates internal references in an object by adding a prefix to their paths.\n * Recursively traverses the input object and modifies any local $ref references\n * by prepending the given prefix to their paths. This is used when embedding external\n * documents to maintain correct reference paths relative to the main document.\n *\n * @param input - The object to update references in\n * @param prefix - Array of path segments to prepend to internal reference paths\n * @returns void\n * @example\n * ```ts\n * const input = {\n *   foo: {\n *     $ref: '#/components/schemas/User'\n *   }\n * }\n * prefixInternalRefRecursive(input, ['definitions'])\n * // Result:\n * // {\n * //   foo: {\n * //     $ref: '#/definitions/components/schemas/User'\n * //   }\n * // }\n * ```\n */\nexport function prefixInternalRefRecursive(input: unknown, prefix: string[]) {\n  if (!isObject(input)) {\n    return\n  }\n\n  Object.values(input).forEach((el) => prefixInternalRefRecursive(el, prefix))\n\n  if (typeof input === 'object' && '$ref' in input && typeof input['$ref'] === 'string') {\n    const ref = input['$ref']\n\n    if (!isLocalRef(ref)) {\n      return\n    }\n\n    input['$ref'] = prefixInternalRef(ref, prefix)\n  }\n}\n\n/**\n * Resolves and copies referenced values from a source document to a target document.\n * This function traverses the document and copies referenced values to the target document,\n * while tracking processed references to avoid duplicates. It only processes references\n * that belong to the same external document.\n *\n * @param targetDocument - The document to copy referenced values to\n * @param sourceDocument - The source document containing the references\n * @param referencePath - The JSON pointer path to the reference\n * @param externalRefsKey - The key used for external references (e.g. 'x-ext')\n * @param documentKey - The key identifying the external document\n * @param processedNodes - Set of already processed nodes to prevent duplicates\n * @example\n * ```ts\n * const source = {\n *   components: {\n *     schemas: {\n *       User: {\n *         $ref: '#/x-ext/users~1schema/definitions/Person'\n *       }\n *     }\n *   }\n * }\n *\n * const target = {}\n * resolveAndCopyReferences(\n *   target,\n *   source,\n *   '/components/schemas/User',\n *   'x-ext',\n *   'users/schema'\n * )\n * // Result: target will contain the User schema with resolved references\n * ```\n */\nconst resolveAndCopyReferences = (\n  targetDocument: unknown,\n  sourceDocument: unknown,\n  referencePath: string,\n  externalRefsKey: string,\n  documentKey: string,\n  processedNodes = new Set(),\n) => {\n  const referencedValue = getNestedValue(sourceDocument, getSegmentsFromPath(referencePath))\n\n  if (processedNodes.has(referencedValue)) {\n    return\n  }\n  processedNodes.add(referencedValue)\n\n  setValueAtPath(targetDocument, referencePath, referencedValue)\n\n  // Do the same for each local ref\n  const traverse = (node: unknown) => {\n    if (!node || typeof node !== 'object') {\n      return\n    }\n\n    if ('$ref' in node && typeof node['$ref'] === 'string') {\n      // We only process references from the same external document because:\n      // 1. Other documents will be handled in separate recursive branches\n      // 2. The source document only contains the current document's content\n      // This prevents undefined behavior and maintains proper document boundaries\n      if (node['$ref'].startsWith(`#/${externalRefsKey}/${escapeJsonPointer(documentKey)}`)) {\n        resolveAndCopyReferences(\n          targetDocument,\n          sourceDocument,\n          node['$ref'].substring(1),\n          documentKey,\n          externalRefsKey,\n          processedNodes,\n        )\n      }\n    }\n\n    for (const value of Object.values(node)) {\n      traverse(value)\n    }\n  }\n\n  traverse(referencedValue)\n}\n\n/**\n * A loader plugin for resolving external references during bundling.\n * Loader plugins are responsible for handling specific types of external references,\n * such as files, URLs, or custom protocols. Each loader plugin must provide:\n *\n * - A `validate` function to determine if the plugin can handle a given reference string.\n * - An `exec` function to asynchronously fetch and resolve the referenced data,\n *   returning a Promise that resolves to a `ResolveResult`.\n *\n * Loader plugins enable extensible support for different reference sources in the bundler.\n *\n * @property type - The plugin type, always 'loader' for loader plugins.\n * @property validate - Function to check if the plugin can handle a given reference value.\n * @property exec - Function to fetch and resolve the reference, returning the resolved data.\n */\nexport type LoaderPlugin = {\n  type: 'loader'\n  // Returns true if this plugin can handle the given reference value\n  validate: (value: string) => boolean\n  // Asynchronously fetches and resolves the reference, returning the resolved data\n  exec: (value: string) => Promise<ResolveResult>\n}\n\n/**\n * Context information for a node during traversal or processing.\n *\n * Note: The `path` parameter represents the path to the current node being processed.\n * If you are performing a partial bundle (i.e., providing a custom root), this path will be relative\n * to the root you provide, not the absolute root of the original document. You may need to prefix\n * it with your own base path if you want to construct a full path from the absolute document root.\n *\n * - `path`: The JSON pointer path (as an array of strings) from the document root to the current node.\n * - `resolutionCache`: A cache for storing promises of resolved references.\n */\ntype NodeProcessContext = {\n  path: readonly string[]\n  resolutionCache: Map<string, Promise<Readonly<ResolveResult>>>\n  parentNode: UnknownObject | null\n  rootNode: UnknownObject\n  loaders: LoaderPlugin[]\n}\n\n/**\n * A plugin type for lifecycle hooks, allowing custom logic to be injected into the bundler's process.\n * This type extends the Config['hooks'] interface and is identified by type: 'lifecycle'.\n */\nexport type LifecyclePlugin = { type: 'lifecycle' } & Config['hooks']\n\n/**\n * Represents a plugin used by the bundler for extensibility.\n *\n * Plugins can be either:\n * - Loader plugins: Responsible for resolving and loading external references (e.g., from files, URLs, or custom sources).\n * - Lifecycle plugins: Provide lifecycle hooks to customize or extend the bundling process.\n *\n * Loader plugins must implement:\n *   - `validate`: Checks if the plugin can handle a given reference value.\n *   - `exec`: Asynchronously resolves and returns the referenced data.\n *\n * Lifecycle plugins extend the bundler's lifecycle hooks for custom logic.\n */\nexport type Plugin = LoaderPlugin | LifecyclePlugin\n\n/**\n * Configuration options for the bundler.\n * Controls how external references are resolved and processed during bundling.\n */\ntype Config = {\n  /**\n   * Array of plugins that handle resolving references from different sources.\n   * Each plugin is responsible for fetching and processing data from specific sources\n   * like URLs or the filesystem.\n   */\n  plugins: Plugin[]\n\n  /**\n   * Optional root object that serves as the base document when bundling a subpart.\n   * This allows resolving references relative to the root document's location,\n   * ensuring proper path resolution for nested references.\n   */\n  root?: UnknownObject\n\n  /**\n   * Optional maximum depth for reference resolution.\n   * Limits how deeply the bundler will follow and resolve nested $ref pointers.\n   * Useful for preventing infinite recursion or excessive resource usage.\n   */\n  depth?: number\n\n  /**\n   * Optional origin path for the bundler.\n   * Used to resolve relative paths in references, especially when the input is a string URL or file path.\n   * If not provided, the bundler will use the input value as the origin.\n   */\n  origin?: string\n\n  /**\n   * Optional cache to store promises of resolved references.\n   * Helps avoid duplicate fetches/reads of the same resource by storing\n   * the resolution promises for reuse.\n   */\n  cache?: Map<string, Promise<ResolveResult>>\n\n  /**\n   * Cache of visited nodes during partial bundling.\n   * Used to prevent re-bundling the same tree multiple times when doing partial bundling,\n   * improving performance by avoiding redundant processing of already bundled sections.\n   */\n  visitedNodes?: Set<unknown>\n\n  /**\n   * Enable tree shaking to optimize the bundle size.\n   * When enabled, only the parts of external documents that are actually referenced\n   * will be included in the final bundle.\n   */\n  treeShake: boolean\n\n  /**\n   * Optional flag to generate a URL map.\n   * When enabled, tracks the original source URLs of bundled references\n   * in an x-ext-urls section for reference mapping.\n   */\n  urlMap?: boolean\n\n  /**\n   * Optional function to compress input URLs or file paths before bundling.\n   * Returns either a Promise resolving to the compressed string or the compressed string directly.\n   */\n  compress?: (value: string) => Promise<string> | string\n\n  /**\n   * Optional hooks to monitor the bundler's lifecycle.\n   * Allows tracking the progress and status of reference resolution.\n   */\n  hooks?: Partial<{\n    /**\n     * Optional hook called when the bundler starts resolving a $ref.\n     * Useful for tracking or logging the beginning of a reference resolution.\n     */\n    onResolveStart: (node: UnknownObject & Record<'$ref', unknown>) => void\n    /**\n     * Optional hook called when the bundler fails to resolve a $ref.\n     * Can be used for error handling, logging, or custom error reporting.\n     */\n    onResolveError: (node: UnknownObject & Record<'$ref', unknown>) => void\n    /**\n     * Optional hook called when the bundler successfully resolves a $ref.\n     * Useful for tracking successful resolutions or custom post-processing.\n     */\n    onResolveSuccess: (node: UnknownObject & Record<'$ref', unknown>) => void\n    /**\n     * Optional hook invoked before processing a node.\n     * Can be used for preprocessing, mutation, or custom logic before the node is handled by the bundler.\n     */\n    onBeforeNodeProcess: (node: UnknownObject, context: NodeProcessContext) => void | Promise<void>\n    /**\n     * Optional hook invoked after processing a node.\n     * Useful for postprocessing, cleanup, or custom logic after the node has been handled by the bundler.\n     */\n    onAfterNodeProcess: (node: UnknownObject, context: NodeProcessContext) => void | Promise<void>\n  }>\n}\n\n/**\n * Extension keys used for bundling external references in OpenAPI documents.\n * These custom extensions help maintain the structure and traceability of bundled documents.\n */\nconst extensions = {\n  /**\n   * Custom OpenAPI extension key used to store external references.\n   * This key will contain all bundled external documents.\n   * The x-ext key is used to maintain a clean separation between the main\n   * OpenAPI document and its bundled external references.\n   */\n  externalDocuments: 'x-ext',\n\n  /**\n   * Custom OpenAPI extension key used to maintain a mapping between\n   * hashed keys and their original URLs in x-ext.\n   * This mapping is essential for tracking the source of bundled references\n   */\n  externalDocumentsMappings: 'x-ext-urls',\n} as const\n\n/**\n * Bundles an OpenAPI specification by resolving all external references.\n * This function traverses the input object recursively and embeds external $ref\n * references into an x-ext section. External references can be URLs or local files.\n * The original $refs are updated to point to their embedded content in the x-ext section.\n * If the input is an object, it will be modified in place by adding an x-ext\n * property to store resolved external references.\n *\n * @param input - The OpenAPI specification to bundle. Can be either an object or string.\n *                If a string is provided, it will be resolved using the provided plugins.\n *                If no plugin can process the input, the onReferenceError hook will be invoked\n *                and an error will be emitted to the console.\n * @param config - Configuration object containing plugins and options for bundling OpenAPI specifications\n * @returns A promise that resolves to the bundled specification with all references embedded\n * @example\n * // Example with object input\n * const spec = {\n *   paths: {\n *     '/users': {\n *       $ref: 'https://example.com/schemas/users.yaml'\n *     }\n *   }\n * }\n *\n * const bundled = await bundle(spec, {\n *   plugins: [fetchUrls()],\n *   treeShake: true,\n *   urlMap: true,\n *   hooks: {\n *     onResolveStart: (ref) => console.log('Resolving:', ref.$ref),\n *     onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),\n *     onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)\n *   }\n * })\n * // Result:\n * // {\n * //   paths: {\n * //     '/users': {\n * //       $ref: '#/x-ext/abc123'\n * //     }\n * //   },\n * //   'x-ext': {\n * //     'abc123': {\n * //       // Resolved content from users.yaml\n * //     }\n * //   },\n * //   'x-ext-urls': {\n * //     'https://example.com/schemas/users.yaml': 'abc123'\n * //   }\n * // }\n *\n * // Example with URL input\n * const bundledFromUrl = await bundle('https://example.com/openapi.yaml', {\n *   plugins: [fetchUrls()],\n *   treeShake: true,\n *   urlMap: true,\n *   hooks: {\n *     onResolveStart: (ref) => console.log('Resolving:', ref.$ref),\n *     onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),\n *     onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)\n *   }\n * })\n * // The function will first fetch the OpenAPI spec from the URL,\n * // then bundle all its external references into the x-ext section\n */\nexport async function bundle(input: UnknownObject | string, config: Config) {\n  // Cache for storing promises of resolved external references (URLs and local files)\n  // to avoid duplicate fetches/reads of the same resource\n  const cache = config.cache ?? new Map<string, Promise<ResolveResult>>()\n\n  const loaderPlugins = config.plugins.filter((it) => it.type === 'loader')\n  const lifecyclePlugin = config.plugins.filter((it) => it.type === 'lifecycle')\n\n  /**\n   * Resolves the input value by either returning it directly if it's not a string,\n   * or attempting to resolve it using the provided plugins if it is a string.\n   * @returns The resolved input data or throws an error if resolution fails\n   */\n  const resolveInput = async () => {\n    if (typeof input !== 'string') {\n      return input\n    }\n    const result = await resolveContents(input, loaderPlugins)\n\n    if (result.ok && typeof result.data === 'object') {\n      return result.data\n    }\n\n    throw new Error(\n      'Failed to resolve input: Please provide a valid string value or pass a loader to process the input',\n    )\n  }\n\n  // Resolve the input specification, which could be either a direct object or a string URL/path\n  const rawSpecification = await resolveInput()\n\n  // Document root used to write all external documents\n  // We need this when we want to do a partial bundle of a document\n  const documentRoot = config.root ?? rawSpecification\n\n  // Determines if the bundling operation is partial.\n  // Partial bundling occurs when:\n  // - A root document is provided that is different from the raw specification being bundled, or\n  // - A maximum depth is specified in the config.\n  // In these cases, only a subset of the document may be bundled.\n  const isPartialBundling =\n    (config.root !== undefined && config.root !== rawSpecification) || config.depth !== undefined\n\n  // Set of nodes that have already been processed during bundling to prevent duplicate processing\n  const processedNodes = config.visitedNodes ?? new Set()\n\n  // Determines the initial origin path for the bundler based on the input type.\n  // For string inputs that are URLs or file paths, uses the input as the origin.\n  // For non-string inputs or other string types, returns an empty string.\n  const defaultOrigin = () => {\n    if (config.origin) {\n      return config.origin\n    }\n\n    if (typeof input !== 'string') {\n      return ''\n    }\n\n    if (isRemoteUrl(input) || isFilePath(input)) {\n      return input\n    }\n\n    return ''\n  }\n\n  // Create the cache to store the compressed values to their map values\n  if (documentRoot[extensions.externalDocumentsMappings] === undefined) {\n    documentRoot[extensions.externalDocumentsMappings] = {}\n  }\n  const { generate } = uniqueValueGeneratorFactory(\n    config.compress ?? getHash,\n    documentRoot[extensions.externalDocumentsMappings],\n  )\n\n  const bundler = async (\n    root: unknown,\n    origin: string = defaultOrigin(),\n    isChunkParent = false,\n    depth = 0,\n    path: readonly string[] = [],\n    parent: UnknownObject = null,\n  ) => {\n    // If a maximum depth is set in the config, stop bundling when the current depth reaches or exceeds it\n    if (config.depth !== undefined && depth > config.depth) {\n      return\n    }\n\n    if (!isObject(root) && !Array.isArray(root)) {\n      return\n    }\n\n    // Skip if this node has already been processed to prevent infinite recursion\n    // and duplicate processing of the same node\n    if (processedNodes.has(root)) {\n      return\n    }\n    // Mark this node as processed before continuing\n    processedNodes.add(root)\n\n    // Invoke the onBeforeNodeProcess hook for the current node before any further processing\n    await config.hooks?.onBeforeNodeProcess?.(root as UnknownObject, {\n      path,\n      resolutionCache: cache,\n      parentNode: parent,\n      rootNode: documentRoot as UnknownObject,\n      loaders: loaderPlugins,\n    })\n    // Invoke onBeforeNodeProcess hooks from all registered lifecycle plugins\n    for (const plugin of lifecyclePlugin) {\n      await plugin.onBeforeNodeProcess?.(root as UnknownObject, {\n        path,\n        resolutionCache: cache,\n        parentNode: parent,\n        rootNode: documentRoot as UnknownObject,\n        loaders: loaderPlugins,\n      })\n    }\n\n    if (typeof root === 'object' && '$ref' in root && typeof root['$ref'] === 'string') {\n      const ref = root['$ref']\n      const isChunk = '$global' in root && typeof root['$global'] === 'boolean' && root['$global']\n\n      if (isLocalRef(ref)) {\n        if (isPartialBundling) {\n          const segments = getSegmentsFromPath(ref.substring(1))\n          const parent = segments.length > 0 ? getNestedValue(documentRoot, segments.slice(0, -1)) : undefined\n\n          // When doing partial bundling, we need to recursively bundle all dependencies\n          // referenced by this local reference to ensure the partial bundle is complete.\n          // This includes not just the direct reference but also all its dependencies,\n          // creating a complete and self-contained partial bundle.\n          await bundler(getNestedValue(documentRoot, segments), origin, isChunkParent, depth + 1, segments, parent)\n        }\n        return\n      }\n\n      const [prefix, path = ''] = ref.split('#', 2)\n\n      // Combine the current origin with the new path to resolve relative references\n      // correctly within the context of the external file being processed\n      const resolvedPath = resolveReferencePath(origin, prefix)\n\n      // Generate a unique compressed path for the external document\n      // This is used as a key to store and reference the bundled external document\n      // The compression helps reduce the overall file size of the bundled document\n      const compressedPath = await generate(resolvedPath)\n\n      const seen = cache.has(resolvedPath)\n\n      if (!seen) {\n        cache.set(resolvedPath, resolveContents(resolvedPath, loaderPlugins))\n      }\n\n      config?.hooks?.onResolveStart?.(root)\n      lifecyclePlugin.forEach((it) => it.onResolveStart?.(root))\n\n      // Resolve the remote document\n      const result = await cache.get(resolvedPath)\n\n      if (result.ok) {\n        // Process the result only once to avoid duplicate processing and prevent multiple prefixing\n        // of internal references, which would corrupt the reference paths\n        if (!seen) {\n          // Skip prefixing for chunks since they are meant to be self-contained and their\n          // internal references should remain relative to their original location. Chunks\n          // are typically used for modular components that need to maintain their own\n          // reference context without being affected by the main document's structure.\n          if (!isChunk) {\n            // Update internal references in the resolved document to use the correct base path.\n            // When we embed external documents, their internal references need to be updated to\n            // maintain the correct path context relative to the main document. This is crucial\n            // because internal references in the external document are relative to its original\n            // location, but when embedded, they need to be relative to their new location in\n            // the main document's x-ext section. Without this update, internal references\n            // would point to incorrect locations and break the document structure.\n            prefixInternalRefRecursive(result.data, [extensions.externalDocuments, compressedPath])\n          }\n\n          // Recursively process the resolved content\n          // to handle any nested references it may contain. We pass the resolvedPath as the new origin\n          // to ensure any relative references within this content are resolved correctly relative to\n          // their new location in the bundled document.\n          await bundler(result.data, isChunk ? origin : resolvedPath, isChunk, depth + 1, [\n            extensions.externalDocuments,\n            compressedPath,\n            documentRoot[extensions.externalDocumentsMappings],\n          ])\n\n          // Store the mapping between hashed keys and original URLs in x-ext-urls\n          // This allows tracking which external URLs were bundled and their corresponding locations\n          setValueAtPath(\n            documentRoot,\n            `/${extensions.externalDocumentsMappings}/${escapeJsonPointer(compressedPath)}`,\n            resolvedPath,\n          )\n        }\n\n        if (config.treeShake === true) {\n          // Store only the subtree that is actually used\n          // This optimizes the bundle size by only including the parts of the external document\n          // that are referenced, rather than the entire document\n          resolveAndCopyReferences(\n            documentRoot,\n            { [extensions.externalDocuments]: { [compressedPath]: result.data } },\n            prefixInternalRef(`#${path}`, [extensions.externalDocuments, compressedPath]).substring(1),\n            extensions.externalDocuments,\n            compressedPath,\n          )\n        } else if (!seen) {\n          // Store the external document in the main document's x-ext key\n          // When tree shaking is disabled, we include the entire external document\n          // This preserves all content and is faster since we don't need to analyze and copy\n          // specific parts. This approach is ideal when storing the result in memory\n          // as it avoids the overhead of tree shaking operations\n          setValueAtPath(documentRoot, `/${extensions.externalDocuments}/${compressedPath}`, result.data)\n        }\n\n        // Update the $ref to point to the embedded document in x-ext\n        // This is necessary because we need to maintain the correct path context\n        // for the embedded document while preserving its internal structure\n        root.$ref = prefixInternalRef(`#${path}`, [extensions.externalDocuments, compressedPath])\n\n        config?.hooks?.onResolveSuccess?.(root)\n        lifecyclePlugin.forEach((it) => it.onResolveSuccess?.(root))\n\n        return\n      }\n\n      config?.hooks?.onResolveError?.(root)\n      lifecyclePlugin.forEach((it) => it.onResolveError?.(root))\n\n      return console.warn(\n        `Failed to resolve external reference \"${resolvedPath}\". The reference may be invalid, inaccessible, or missing a loader for this type of reference.`,\n      )\n    }\n\n    // Recursively traverse all child properties of the current object to resolve nested $ref references.\n    // This step ensures that any $refs located deeper within the object hierarchy are discovered and processed.\n    // We explicitly skip the extension keys (x-ext and x-ext-urls) to avoid reprocessing already bundled or mapped content.\n    await Promise.all(\n      Object.entries(root).map(async ([key, value]) => {\n        if (key === extensions.externalDocuments || key === extensions.externalDocumentsMappings) {\n          return\n        }\n\n        await bundler(value, origin, isChunkParent, depth + 1, [...path, key], root as UnknownObject)\n      }),\n    )\n\n    // Invoke the optional onAfterNodeProcess hook from the config, if provided.\n    // This allows for custom post-processing logic after a node has been handled by the bundler.\n    await config.hooks?.onAfterNodeProcess?.(root as UnknownObject, {\n      path,\n      resolutionCache: cache,\n      parentNode: parent,\n      rootNode: documentRoot as UnknownObject,\n      loaders: loaderPlugins,\n    })\n\n    // Iterate through all lifecycle plugins and invoke their onAfterNodeProcess hooks, if defined.\n    // This enables plugins to perform additional post-processing or cleanup after the node is processed.\n    for (const plugin of lifecyclePlugin) {\n      await plugin.onAfterNodeProcess?.(root as UnknownObject, {\n        path,\n        resolutionCache: cache,\n        parentNode: parent,\n        rootNode: documentRoot as UnknownObject,\n        loaders: loaderPlugins,\n      })\n    }\n  }\n\n  await bundler(rawSpecification)\n\n  // Keep urlMappings when doing partial bundling to track hash values and handle collisions\n  // For full bundling without urlMap config, remove the mappings to clean up the output\n  if (!config.urlMap && !isPartialBundling) {\n    // Remove the external document mappings from the output when doing a full bundle without urlMap config\n    delete documentRoot[extensions.externalDocumentsMappings]\n  }\n\n  return rawSpecification\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import type { UnknownObject } from '@/types'\n\nimport { escapeJsonPointer } from '../utils/escape-json-pointer'\nimport path from '@/polyfills/path'\nimport { getSegmentsFromPath } from '../utils/get-segments-from-path'\nimport { isObject } from '../utils/is-object'\nimport { isYaml } from '../utils/is-yaml'\nimport { isJsonObject } from '../utils/is-json-object'\nimport { getHash, uniqueValueGeneratorFactory } from './value-generator'\n\n/**\n * Checks if a string is a remote URL (starts with http:// or https://)\n * @param value - The URL string to check\n * @returns true if the string is a remote URL, false otherwise\n * @example\n * ```ts\n * isRemoteUrl('https://example.com/schema.json') // true\n * isRemoteUrl('http://api.example.com/schemas/user.json') // true\n * isRemoteUrl('#/components/schemas/User') // false\n * isRemoteUrl('./local-schema.json') // false\n * ```\n */\nexport function isRemoteUrl(value: string) {\n  try {\n    const url = new URL(value)\n    return url.protocol === 'http:' || url.protocol === 'https:'\n  } catch {\n    return false\n  }\n}\n\n/**\n * Checks if a string represents a file path by ensuring it's not a remote URL,\n * YAML content, or JSON content.\n *\n * @param value - The string to check\n * @returns true if the string appears to be a file path, false otherwise\n * @example\n * ```ts\n * isFilePath('./schemas/user.json') // true\n * isFilePath('https://example.com/schema.json') // false\n * isFilePath('{\"type\": \"object\"}') // false\n * isFilePath('type: object') // false\n * ```\n */\nexport function isFilePath(value: string) {\n  return !isRemoteUrl(value) && !isYaml(value) && !isJsonObject(value)\n}\n\n/**\n * Checks if a string is a local reference (starts with #)\n * @param value - The reference string to check\n * @returns true if the string is a local reference, false otherwise\n * @example\n * ```ts\n * isLocalRef('#/components/schemas/User') // true\n * isLocalRef('https://example.com/schema.json') // false\n * isLocalRef('./local-schema.json') // false\n * ```\n */\nexport function isLocalRef(value: string): boolean {\n  return value.startsWith('#')\n}\n\nexport type ResolveResult = { ok: true; data: unknown } | { ok: false }\n\n/**\n * Resolves a string by finding and executing the appropriate plugin.\n * @param value - The string to resolve (URL, file path, etc)\n * @param plugins - Array of plugins that can handle different types of strings\n * @returns A promise that resolves to either the content or an error result\n * @example\n * // Using a URL plugin\n * await resolveContents('https://example.com/schema.json', [urlPlugin])\n * // Using a file plugin\n * await resolveContents('./schemas/user.json', [filePlugin])\n * // No matching plugin returns { ok: false }\n * await resolveContents('#/components/schemas/User', [urlPlugin, filePlugin])\n */\nasync function resolveContents(value: string, plugins: LoaderPlugin[]): Promise<ResolveResult> {\n  const plugin = plugins.find((p) => p.validate(value))\n\n  if (plugin) {\n    return plugin.exec(value)\n  }\n\n  return {\n    ok: false,\n  }\n}\n\n/**\n * Retrieves a nested value from an object using an array of property segments.\n * @param target - The target object to traverse\n * @param segments - Array of property names representing the path to the desired value\n * @returns The value at the specified path, or undefined if the path doesn't exist\n * @example\n * const obj = { foo: { bar: { baz: 42 } } };\n * getNestedValue(obj, ['foo', 'bar', 'baz']); // returns 42\n */\nexport function getNestedValue(target: Record<string, any>, segments: string[]) {\n  return segments.reduce<any>((acc, key) => {\n    if (acc === undefined) {\n      return undefined\n    }\n    return acc[key]\n  }, target)\n}\n\n/**\n * Sets a value at a specified path in an object, creating intermediate objects/arrays as needed.\n * This function traverses the object structure and creates any missing intermediate objects\n * or arrays based on the path segments. If the next segment is a numeric string, it creates\n * an array instead of an object.\n *\n * \u26A0\uFE0F Warning: Be careful with object keys that look like numbers (e.g. \"123\") as this function\n * will interpret them as array indices and create arrays instead of objects. If you need to\n * use numeric-looking keys, consider prefixing them with a non-numeric character.\n *\n * @param obj - The target object to set the value in\n * @param path - The JSON pointer path where the value should be set\n * @param value - The value to set at the specified path\n * @throws {Error} If attempting to set a value at the root path ('')\n *\n * @example\n * const obj = {}\n * setValueAtPath(obj, '/foo/bar/0', 'value')\n * // Result:\n * // {\n * //   foo: {\n * //     bar: ['value']\n * //   }\n * // }\n *\n * @example\n * const obj = { existing: { path: 'old' } }\n * setValueAtPath(obj, '/existing/path', 'new')\n * // Result:\n * // {\n * //   existing: {\n * //     path: 'new'\n * //   }\n * // }\n *\n * @example\n * // \u26A0\uFE0F Warning: This will create an array instead of an object with key \"123\"\n * setValueAtPath(obj, '/foo/123/bar', 'value')\n * // Result:\n * // {\n * //   foo: [\n * //     undefined,\n * //     undefined,\n * //     undefined,\n * //     { bar: 'value' }\n * //   ]\n * // }\n */\nexport function setValueAtPath(obj: any, path: string, value: any): void {\n  if (path === '') {\n    throw new Error(\"Cannot set value at root ('') pointer\")\n  }\n\n  const parts = getSegmentsFromPath(path)\n\n  let current = obj\n\n  for (let i = 0; i < parts.length; i++) {\n    const key = parts[i]\n    const isLast = i === parts.length - 1\n\n    const nextKey = parts[i + 1]\n    const shouldBeArray = /^\\d+$/.test(nextKey ?? '')\n\n    if (isLast) {\n      current[key] = value\n    } else {\n      if (!(key in current) || typeof current[key] !== 'object') {\n        current[key] = shouldBeArray ? [] : {}\n      }\n      current = current[key]\n    }\n  }\n}\n\n/**\n * Resolves a reference path by combining a base path with a relative path.\n * Handles both remote URLs and local file paths.\n *\n * @param base - The base path (can be a URL or local file path)\n * @param relativePath - The relative path to resolve against the base\n * @returns The resolved absolute path\n * @example\n * // Resolve remote URL\n * resolveReferencePath('https://example.com/api/schema.json', 'user.json')\n * // Returns: 'https://example.com/api/user.json'\n *\n * // Resolve local path\n * resolveReferencePath('/path/to/schema.json', 'user.json')\n * // Returns: '/path/to/user.json'\n */\nfunction resolveReferencePath(base: string, relativePath: string) {\n  if (isRemoteUrl(relativePath)) {\n    return relativePath\n  }\n\n  if (isRemoteUrl(base)) {\n    const url = new URL(base)\n\n    // If the url stars with a / we want it to resolve from the origin so we replace the pathname\n    if (relativePath.startsWith('/')) {\n      url.pathname = relativePath\n      return url.toString()\n    }\n\n    const mergedPath = path.join(path.dirname(url.pathname), relativePath)\n    return new URL(mergedPath, base).toString()\n  }\n\n  return path.join(path.dirname(base), relativePath)\n}\n\n/**\n * Prefixes an internal JSON reference with a given path prefix.\n * Takes a local reference (starting with #) and prepends the provided prefix segments.\n *\n * @param input - The internal reference string to prefix (must start with #)\n * @param prefix - Array of path segments to prepend to the reference\n * @returns The prefixed reference string\n * @throws Error if input is not a local reference\n * @example\n * prefixInternalRef('#/components/schemas/User', ['definitions'])\n * // Returns: '#/definitions/components/schemas/User'\n */\nexport function prefixInternalRef(input: string, prefix: string[]) {\n  if (!isLocalRef(input)) {\n    throw 'Please provide an internal ref'\n  }\n\n  return `#/${prefix.map(escapeJsonPointer).join('/')}${input.substring(1)}`\n}\n\n/**\n * Updates internal references in an object by adding a prefix to their paths.\n * Recursively traverses the input object and modifies any local $ref references\n * by prepending the given prefix to their paths. This is used when embedding external\n * documents to maintain correct reference paths relative to the main document.\n *\n * @param input - The object to update references in\n * @param prefix - Array of path segments to prepend to internal reference paths\n * @returns void\n * @example\n * ```ts\n * const input = {\n *   foo: {\n *     $ref: '#/components/schemas/User'\n *   }\n * }\n * prefixInternalRefRecursive(input, ['definitions'])\n * // Result:\n * // {\n * //   foo: {\n * //     $ref: '#/definitions/components/schemas/User'\n * //   }\n * // }\n * ```\n */\nexport function prefixInternalRefRecursive(input: unknown, prefix: string[]) {\n  if (!isObject(input)) {\n    return\n  }\n\n  Object.values(input).forEach((el) => prefixInternalRefRecursive(el, prefix))\n\n  if (typeof input === 'object' && '$ref' in input && typeof input['$ref'] === 'string') {\n    const ref = input['$ref']\n\n    if (!isLocalRef(ref)) {\n      return\n    }\n\n    input['$ref'] = prefixInternalRef(ref, prefix)\n  }\n}\n\n/**\n * Resolves and copies referenced values from a source document to a target document.\n * This function traverses the document and copies referenced values to the target document,\n * while tracking processed references to avoid duplicates. It only processes references\n * that belong to the same external document.\n *\n * @param targetDocument - The document to copy referenced values to\n * @param sourceDocument - The source document containing the references\n * @param referencePath - The JSON pointer path to the reference\n * @param externalRefsKey - The key used for external references (e.g. 'x-ext')\n * @param documentKey - The key identifying the external document\n * @param processedNodes - Set of already processed nodes to prevent duplicates\n * @example\n * ```ts\n * const source = {\n *   components: {\n *     schemas: {\n *       User: {\n *         $ref: '#/x-ext/users~1schema/definitions/Person'\n *       }\n *     }\n *   }\n * }\n *\n * const target = {}\n * resolveAndCopyReferences(\n *   target,\n *   source,\n *   '/components/schemas/User',\n *   'x-ext',\n *   'users/schema'\n * )\n * // Result: target will contain the User schema with resolved references\n * ```\n */\nconst resolveAndCopyReferences = (\n  targetDocument: unknown,\n  sourceDocument: unknown,\n  referencePath: string,\n  externalRefsKey: string,\n  documentKey: string,\n  processedNodes = new Set(),\n) => {\n  const referencedValue = getNestedValue(sourceDocument, getSegmentsFromPath(referencePath))\n\n  if (processedNodes.has(referencedValue)) {\n    return\n  }\n  processedNodes.add(referencedValue)\n\n  setValueAtPath(targetDocument, referencePath, referencedValue)\n\n  // Do the same for each local ref\n  const traverse = (node: unknown) => {\n    if (!node || typeof node !== 'object') {\n      return\n    }\n\n    if ('$ref' in node && typeof node['$ref'] === 'string') {\n      // We only process references from the same external document because:\n      // 1. Other documents will be handled in separate recursive branches\n      // 2. The source document only contains the current document's content\n      // This prevents undefined behavior and maintains proper document boundaries\n      if (node['$ref'].startsWith(`#/${externalRefsKey}/${escapeJsonPointer(documentKey)}`)) {\n        resolveAndCopyReferences(\n          targetDocument,\n          sourceDocument,\n          node['$ref'].substring(1),\n          documentKey,\n          externalRefsKey,\n          processedNodes,\n        )\n      }\n    }\n\n    for (const value of Object.values(node)) {\n      traverse(value)\n    }\n  }\n\n  traverse(referencedValue)\n}\n\n/**\n * A loader plugin for resolving external references during bundling.\n * Loader plugins are responsible for handling specific types of external references,\n * such as files, URLs, or custom protocols. Each loader plugin must provide:\n *\n * - A `validate` function to determine if the plugin can handle a given reference string.\n * - An `exec` function to asynchronously fetch and resolve the referenced data,\n *   returning a Promise that resolves to a `ResolveResult`.\n *\n * Loader plugins enable extensible support for different reference sources in the bundler.\n *\n * @property type - The plugin type, always 'loader' for loader plugins.\n * @property validate - Function to check if the plugin can handle a given reference value.\n * @property exec - Function to fetch and resolve the reference, returning the resolved data.\n */\nexport type LoaderPlugin = {\n  type: 'loader'\n  // Returns true if this plugin can handle the given reference value\n  validate: (value: string) => boolean\n  // Asynchronously fetches and resolves the reference, returning the resolved data\n  exec: (value: string) => Promise<ResolveResult>\n}\n\n/**\n * Context information for a node during traversal or processing.\n *\n * Note: The `path` parameter represents the path to the current node being processed.\n * If you are performing a partial bundle (i.e., providing a custom root), this path will be relative\n * to the root you provide, not the absolute root of the original document. You may need to prefix\n * it with your own base path if you want to construct a full path from the absolute document root.\n *\n * - `path`: The JSON pointer path (as an array of strings) from the document root to the current node.\n * - `resolutionCache`: A cache for storing promises of resolved references.\n */\ntype NodeProcessContext = {\n  path: readonly string[]\n  resolutionCache: Map<string, Promise<Readonly<ResolveResult>>>\n  parentNode: UnknownObject | null\n  rootNode: UnknownObject\n  loaders: LoaderPlugin[]\n}\n\n/**\n * A plugin type for lifecycle hooks, allowing custom logic to be injected into the bundler's process.\n * This type extends the Config['hooks'] interface and is identified by type: 'lifecycle'.\n */\nexport type LifecyclePlugin = { type: 'lifecycle' } & Config['hooks']\n\n/**\n * Represents a plugin used by the bundler for extensibility.\n *\n * Plugins can be either:\n * - Loader plugins: Responsible for resolving and loading external references (e.g., from files, URLs, or custom sources).\n * - Lifecycle plugins: Provide lifecycle hooks to customize or extend the bundling process.\n *\n * Loader plugins must implement:\n *   - `validate`: Checks if the plugin can handle a given reference value.\n *   - `exec`: Asynchronously resolves and returns the referenced data.\n *\n * Lifecycle plugins extend the bundler's lifecycle hooks for custom logic.\n */\nexport type Plugin = LoaderPlugin | LifecyclePlugin\n\n/**\n * Configuration options for the bundler.\n * Controls how external references are resolved and processed during bundling.\n */\ntype Config = {\n  /**\n   * Array of plugins that handle resolving references from different sources.\n   * Each plugin is responsible for fetching and processing data from specific sources\n   * like URLs or the filesystem.\n   */\n  plugins: Plugin[]\n\n  /**\n   * Optional root object that serves as the base document when bundling a subpart.\n   * This allows resolving references relative to the root document's location,\n   * ensuring proper path resolution for nested references.\n   */\n  root?: UnknownObject\n\n  /**\n   * Optional maximum depth for reference resolution.\n   * Limits how deeply the bundler will follow and resolve nested $ref pointers.\n   * Useful for preventing infinite recursion or excessive resource usage.\n   */\n  depth?: number\n\n  /**\n   * Optional origin path for the bundler.\n   * Used to resolve relative paths in references, especially when the input is a string URL or file path.\n   * If not provided, the bundler will use the input value as the origin.\n   */\n  origin?: string\n\n  /**\n   * Optional cache to store promises of resolved references.\n   * Helps avoid duplicate fetches/reads of the same resource by storing\n   * the resolution promises for reuse.\n   */\n  cache?: Map<string, Promise<ResolveResult>>\n\n  /**\n   * Cache of visited nodes during partial bundling.\n   * Used to prevent re-bundling the same tree multiple times when doing partial bundling,\n   * improving performance by avoiding redundant processing of already bundled sections.\n   */\n  visitedNodes?: Set<unknown>\n\n  /**\n   * Enable tree shaking to optimize the bundle size.\n   * When enabled, only the parts of external documents that are actually referenced\n   * will be included in the final bundle.\n   */\n  treeShake: boolean\n\n  /**\n   * Optional flag to generate a URL map.\n   * When enabled, tracks the original source URLs of bundled references\n   * in an x-ext-urls section for reference mapping.\n   */\n  urlMap?: boolean\n\n  /**\n   * Optional function to compress input URLs or file paths before bundling.\n   * Returns either a Promise resolving to the compressed string or the compressed string directly.\n   */\n  compress?: (value: string) => Promise<string> | string\n\n  /**\n   * Optional hooks to monitor the bundler's lifecycle.\n   * Allows tracking the progress and status of reference resolution.\n   */\n  hooks?: Partial<{\n    /**\n     * Optional hook called when the bundler starts resolving a $ref.\n     * Useful for tracking or logging the beginning of a reference resolution.\n     */\n    onResolveStart: (node: UnknownObject & Record<'$ref', unknown>) => void\n    /**\n     * Optional hook called when the bundler fails to resolve a $ref.\n     * Can be used for error handling, logging, or custom error reporting.\n     */\n    onResolveError: (node: UnknownObject & Record<'$ref', unknown>) => void\n    /**\n     * Optional hook called when the bundler successfully resolves a $ref.\n     * Useful for tracking successful resolutions or custom post-processing.\n     */\n    onResolveSuccess: (node: UnknownObject & Record<'$ref', unknown>) => void\n    /**\n     * Optional hook invoked before processing a node.\n     * Can be used for preprocessing, mutation, or custom logic before the node is handled by the bundler.\n     */\n    onBeforeNodeProcess: (node: UnknownObject, context: NodeProcessContext) => void | Promise<void>\n    /**\n     * Optional hook invoked after processing a node.\n     * Useful for postprocessing, cleanup, or custom logic after the node has been handled by the bundler.\n     */\n    onAfterNodeProcess: (node: UnknownObject, context: NodeProcessContext) => void | Promise<void>\n  }>\n}\n\n/**\n * Extension keys used for bundling external references in OpenAPI documents.\n * These custom extensions help maintain the structure and traceability of bundled documents.\n */\nconst extensions = {\n  /**\n   * Custom OpenAPI extension key used to store external references.\n   * This key will contain all bundled external documents.\n   * The x-ext key is used to maintain a clean separation between the main\n   * OpenAPI document and its bundled external references.\n   */\n  externalDocuments: 'x-ext',\n\n  /**\n   * Custom OpenAPI extension key used to maintain a mapping between\n   * hashed keys and their original URLs in x-ext.\n   * This mapping is essential for tracking the source of bundled references\n   */\n  externalDocumentsMappings: 'x-ext-urls',\n} as const\n\n/**\n * Bundles an OpenAPI specification by resolving all external references.\n * This function traverses the input object recursively and embeds external $ref\n * references into an x-ext section. External references can be URLs or local files.\n * The original $refs are updated to point to their embedded content in the x-ext section.\n * If the input is an object, it will be modified in place by adding an x-ext\n * property to store resolved external references.\n *\n * @param input - The OpenAPI specification to bundle. Can be either an object or string.\n *                If a string is provided, it will be resolved using the provided plugins.\n *                If no plugin can process the input, the onReferenceError hook will be invoked\n *                and an error will be emitted to the console.\n * @param config - Configuration object containing plugins and options for bundling OpenAPI specifications\n * @returns A promise that resolves to the bundled specification with all references embedded\n * @example\n * // Example with object input\n * const spec = {\n *   paths: {\n *     '/users': {\n *       $ref: 'https://example.com/schemas/users.yaml'\n *     }\n *   }\n * }\n *\n * const bundled = await bundle(spec, {\n *   plugins: [fetchUrls()],\n *   treeShake: true,\n *   urlMap: true,\n *   hooks: {\n *     onResolveStart: (ref) => console.log('Resolving:', ref.$ref),\n *     onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),\n *     onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)\n *   }\n * })\n * // Result:\n * // {\n * //   paths: {\n * //     '/users': {\n * //       $ref: '#/x-ext/abc123'\n * //     }\n * //   },\n * //   'x-ext': {\n * //     'abc123': {\n * //       // Resolved content from users.yaml\n * //     }\n * //   },\n * //   'x-ext-urls': {\n * //     'https://example.com/schemas/users.yaml': 'abc123'\n * //   }\n * // }\n *\n * // Example with URL input\n * const bundledFromUrl = await bundle('https://example.com/openapi.yaml', {\n *   plugins: [fetchUrls()],\n *   treeShake: true,\n *   urlMap: true,\n *   hooks: {\n *     onResolveStart: (ref) => console.log('Resolving:', ref.$ref),\n *     onResolveSuccess: (ref) => console.log('Resolved:', ref.$ref),\n *     onResolveError: (ref) => console.log('Failed to resolve:', ref.$ref)\n *   }\n * })\n * // The function will first fetch the OpenAPI spec from the URL,\n * // then bundle all its external references into the x-ext section\n */\nexport async function bundle(input: UnknownObject | string, config: Config) {\n  // Cache for storing promises of resolved external references (URLs and local files)\n  // to avoid duplicate fetches/reads of the same resource\n  const cache = config.cache ?? new Map<string, Promise<ResolveResult>>()\n\n  const loaderPlugins = config.plugins.filter((it) => it.type === 'loader')\n  const lifecyclePlugin = config.plugins.filter((it) => it.type === 'lifecycle')\n\n  /**\n   * Resolves the input value by either returning it directly if it's not a string,\n   * or attempting to resolve it using the provided plugins if it is a string.\n   * @returns The resolved input data or throws an error if resolution fails\n   */\n  const resolveInput = async () => {\n    if (typeof input !== 'string') {\n      return input\n    }\n    const result = await resolveContents(input, loaderPlugins)\n\n    if (result.ok && typeof result.data === 'object') {\n      return result.data\n    }\n\n    throw new Error(\n      'Failed to resolve input: Please provide a valid string value or pass a loader to process the input',\n    )\n  }\n\n  // Resolve the input specification, which could be either a direct object or a string URL/path\n  const rawSpecification = await resolveInput()\n\n  // Document root used to write all external documents\n  // We need this when we want to do a partial bundle of a document\n  const documentRoot = config.root ?? rawSpecification\n\n  // Determines if the bundling operation is partial.\n  // Partial bundling occurs when:\n  // - A root document is provided that is different from the raw specification being bundled, or\n  // - A maximum depth is specified in the config.\n  // In these cases, only a subset of the document may be bundled.\n  const isPartialBundling =\n    (config.root !== undefined && config.root !== rawSpecification) || config.depth !== undefined\n\n  // Set of nodes that have already been processed during bundling to prevent duplicate processing\n  const processedNodes = config.visitedNodes ?? new Set()\n\n  // Determines the initial origin path for the bundler based on the input type.\n  // For string inputs that are URLs or file paths, uses the input as the origin.\n  // For non-string inputs or other string types, returns an empty string.\n  const defaultOrigin = () => {\n    if (config.origin) {\n      return config.origin\n    }\n\n    if (typeof input !== 'string') {\n      return ''\n    }\n\n    if (isRemoteUrl(input) || isFilePath(input)) {\n      return input\n    }\n\n    return ''\n  }\n\n  // Create the cache to store the compressed values to their map values\n  if (documentRoot[extensions.externalDocumentsMappings] === undefined) {\n    documentRoot[extensions.externalDocumentsMappings] = {}\n  }\n  const { generate } = uniqueValueGeneratorFactory(\n    config.compress ?? getHash,\n    documentRoot[extensions.externalDocumentsMappings],\n  )\n\n  const bundler = async (\n    root: unknown,\n    origin: string = defaultOrigin(),\n    isChunkParent = false,\n    depth = 0,\n    path: readonly string[] = [],\n    parent: UnknownObject = null,\n  ) => {\n    // If a maximum depth is set in the config, stop bundling when the current depth reaches or exceeds it\n    if (config.depth !== undefined && depth > config.depth) {\n      return\n    }\n\n    if (!isObject(root) && !Array.isArray(root)) {\n      return\n    }\n\n    // Skip if this node has already been processed to prevent infinite recursion\n    // and duplicate processing of the same node\n    if (processedNodes.has(root)) {\n      return\n    }\n    // Mark this node as processed before continuing\n    processedNodes.add(root)\n\n    // Invoke the onBeforeNodeProcess hook for the current node before any further processing\n    await config.hooks?.onBeforeNodeProcess?.(root as UnknownObject, {\n      path,\n      resolutionCache: cache,\n      parentNode: parent,\n      rootNode: documentRoot as UnknownObject,\n      loaders: loaderPlugins,\n    })\n    // Invoke onBeforeNodeProcess hooks from all registered lifecycle plugins\n    for (const plugin of lifecyclePlugin) {\n      await plugin.onBeforeNodeProcess?.(root as UnknownObject, {\n        path,\n        resolutionCache: cache,\n        parentNode: parent,\n        rootNode: documentRoot as UnknownObject,\n        loaders: loaderPlugins,\n      })\n    }\n\n    if (typeof root === 'object' && '$ref' in root && typeof root['$ref'] === 'string') {\n      const ref = root['$ref']\n      const isChunk = '$global' in root && typeof root['$global'] === 'boolean' && root['$global']\n\n      if (isLocalRef(ref)) {\n        if (isPartialBundling) {\n          const segments = getSegmentsFromPath(ref.substring(1))\n          const parent = segments.length > 0 ? getNestedValue(documentRoot, segments.slice(0, -1)) : undefined\n\n          // When doing partial bundling, we need to recursively bundle all dependencies\n          // referenced by this local reference to ensure the partial bundle is complete.\n          // This includes not just the direct reference but also all its dependencies,\n          // creating a complete and self-contained partial bundle.\n          await bundler(getNestedValue(documentRoot, segments), origin, isChunkParent, depth + 1, segments, parent)\n        }\n        return\n      }\n\n      const [prefix, path = ''] = ref.split('#', 2)\n\n      // Combine the current origin with the new path to resolve relative references\n      // correctly within the context of the external file being processed\n      const resolvedPath = resolveReferencePath(origin, prefix)\n\n      // Generate a unique compressed path for the external document\n      // This is used as a key to store and reference the bundled external document\n      // The compression helps reduce the overall file size of the bundled document\n      const compressedPath = await generate(resolvedPath)\n\n      const seen = cache.has(resolvedPath)\n\n      if (!seen) {\n        cache.set(resolvedPath, resolveContents(resolvedPath, loaderPlugins))\n      }\n\n      config?.hooks?.onResolveStart?.(root)\n      lifecyclePlugin.forEach((it) => it.onResolveStart?.(root))\n\n      // Resolve the remote document\n      const result = await cache.get(resolvedPath)\n\n      if (result.ok) {\n        // Process the result only once to avoid duplicate processing and prevent multiple prefixing\n        // of internal references, which would corrupt the reference paths\n        if (!seen) {\n          // Skip prefixing for chunks since they are meant to be self-contained and their\n          // internal references should remain relative to their original location. Chunks\n          // are typically used for modular components that need to maintain their own\n          // reference context without being affected by the main document's structure.\n          if (!isChunk) {\n            // Update internal references in the resolved document to use the correct base path.\n            // When we embed external documents, their internal references need to be updated to\n            // maintain the correct path context relative to the main document. This is crucial\n            // because internal references in the external document are relative to its original\n            // location, but when embedded, they need to be relative to their new location in\n            // the main document's x-ext section. Without this update, internal references\n            // would point to incorrect locations and break the document structure.\n            prefixInternalRefRecursive(result.data, [extensions.externalDocuments, compressedPath])\n          }\n\n          // Recursively process the resolved content\n          // to handle any nested references it may contain. We pass the resolvedPath as the new origin\n          // to ensure any relative references within this content are resolved correctly relative to\n          // their new location in the bundled document.\n          await bundler(result.data, isChunk ? origin : resolvedPath, isChunk, depth + 1, [\n            extensions.externalDocuments,\n            compressedPath,\n            documentRoot[extensions.externalDocumentsMappings],\n          ])\n\n          // Store the mapping between hashed keys and original URLs in x-ext-urls\n          // This allows tracking which external URLs were bundled and their corresponding locations\n          setValueAtPath(\n            documentRoot,\n            `/${extensions.externalDocumentsMappings}/${escapeJsonPointer(compressedPath)}`,\n            resolvedPath,\n          )\n        }\n\n        if (config.treeShake === true) {\n          // Store only the subtree that is actually used\n          // This optimizes the bundle size by only including the parts of the external document\n          // that are referenced, rather than the entire document\n          resolveAndCopyReferences(\n            documentRoot,\n            { [extensions.externalDocuments]: { [compressedPath]: result.data } },\n            prefixInternalRef(`#${path}`, [extensions.externalDocuments, compressedPath]).substring(1),\n            extensions.externalDocuments,\n            compressedPath,\n          )\n        } else if (!seen) {\n          // Store the external document in the main document's x-ext key\n          // When tree shaking is disabled, we include the entire external document\n          // This preserves all content and is faster since we don't need to analyze and copy\n          // specific parts. This approach is ideal when storing the result in memory\n          // as it avoids the overhead of tree shaking operations\n          setValueAtPath(documentRoot, `/${extensions.externalDocuments}/${compressedPath}`, result.data)\n        }\n\n        // Update the $ref to point to the embedded document in x-ext\n        // This is necessary because we need to maintain the correct path context\n        // for the embedded document while preserving its internal structure\n        root.$ref = prefixInternalRef(`#${path}`, [extensions.externalDocuments, compressedPath])\n\n        config?.hooks?.onResolveSuccess?.(root)\n        lifecyclePlugin.forEach((it) => it.onResolveSuccess?.(root))\n\n        return\n      }\n\n      config?.hooks?.onResolveError?.(root)\n      lifecyclePlugin.forEach((it) => it.onResolveError?.(root))\n\n      return console.warn(\n        `Failed to resolve external reference \"${resolvedPath}\". The reference may be invalid, inaccessible, or missing a loader for this type of reference.`,\n      )\n    }\n\n    // Recursively traverse all child properties of the current object to resolve nested $ref references.\n    // This step ensures that any $refs located deeper within the object hierarchy are discovered and processed.\n    // We explicitly skip the extension keys (x-ext and x-ext-urls) to avoid reprocessing already bundled or mapped content.\n    await Promise.all(\n      Object.entries(root).map(async ([key, value]) => {\n        if (key === extensions.externalDocuments || key === extensions.externalDocumentsMappings) {\n          return\n        }\n\n        await bundler(value, origin, isChunkParent, depth + 1, [...path, key], root as UnknownObject)\n      }),\n    )\n\n    // Invoke the optional onAfterNodeProcess hook from the config, if provided.\n    // This allows for custom post-processing logic after a node has been handled by the bundler.\n    await config.hooks?.onAfterNodeProcess?.(root as UnknownObject, {\n      path,\n      resolutionCache: cache,\n      parentNode: parent,\n      rootNode: documentRoot as UnknownObject,\n      loaders: loaderPlugins,\n    })\n\n    // Iterate through all lifecycle plugins and invoke their onAfterNodeProcess hooks, if defined.\n    // This enables plugins to perform additional post-processing or cleanup after the node is processed.\n    for (const plugin of lifecyclePlugin) {\n      await plugin.onAfterNodeProcess?.(root as UnknownObject, {\n        path,\n        resolutionCache: cache,\n        parentNode: parent,\n        rootNode: documentRoot as UnknownObject,\n        loaders: loaderPlugins,\n      })\n    }\n  }\n\n  await bundler(rawSpecification)\n\n  // Keep urlMappings when doing partial bundling to track hash values and handle collisions\n  // For full bundling without urlMap config, remove the mappings to clean up the output\n  if (!config.urlMap && !isPartialBundling) {\n    // Remove the external document mappings from the output when doing a full bundle without urlMap config\n    delete documentRoot[extensions.externalDocumentsMappings]\n  }\n\n  return rawSpecification\n}\n"],
+  "mappings": "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",
   "names": ["path", "parent"]
 }

package/dist/bundle/value-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-generator.d.ts","sourceRoot":"","sources":["../../src/bundle/value-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,mBAe1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EACrD,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,mBAAmB,CAAC,EAAE,MAAM,EAC5B,KAAK,SAAI,mBAoBV;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,2BAA2B,aAC5B,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,qBAClC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMvC;;;;;;;;;;;;OAYG;sBACqB,MAAM;CAqBjC,CAAA"}
+{"version":3,"file":"value-generator.d.ts","sourceRoot":"","sources":["../../src/bundle/value-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,mBAe1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EACrD,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzC,mBAAmB,CAAC,EAAE,MAAM,EAC5B,KAAK,SAAI,mBAoBV;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,2BAA2B,GACtC,UAAU,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,EACrD,mBAAmB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAMvC;;;;;;;;;;;;OAYG;sBACqB,MAAM;CAqBjC,CAAA"}

package/dist/dereference/dereference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dereference.d.ts","sourceRoot":"","sources":["../../src/dereference/dereference.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,KAAK,iBAAiB,GAClB;IACE,OAAO,EAAE,IAAI,CAAA;IACb,IAAI,EAAE,aAAa,CAAA;CACpB,GACD;IACE,OAAO,EAAE,KAAK,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAEL,KAAK,uBAAuB,CAAC,GAAG,SAAS;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,GACnF,iBAAiB,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,SAAS;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,SAClD,aAAa,YACV,IAAI,KACb,uBAAuB,CAAC,IAAI,CAgC9B,CAAA"}
+{"version":3,"file":"dereference.d.ts","sourceRoot":"","sources":["../../src/dereference/dereference.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,KAAK,iBAAiB,GAClB;IACE,OAAO,EAAE,IAAI,CAAA;IACb,IAAI,EAAE,aAAa,CAAA;CACpB,GACD;IACE,OAAO,EAAE,KAAK,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AAEL,KAAK,uBAAuB,CAAC,GAAG,SAAS;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,GACnF,iBAAiB,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,WAAW,GAAI,IAAI,SAAS;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EACzD,OAAO,aAAa,EACpB,UAAU,IAAI,KACb,uBAAuB,CAAC,IAAI,CAgC9B,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/diff/apply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAC3C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAC3B,UAAU,CAAC,CAAC,CAAC,EAAE,KACpB,CAyCF,CAAA"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/diff/apply.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,UAAU,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,UAAU,CAAC,CAAC,CAAC,EAAE,KACpB,CAyCF,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/diff/diff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,KAAK,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,IAAI;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,oBA0C7F,CAAA"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/diff/diff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,KAAK,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,IAAI;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,oBA0C7F,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/diff/merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE;;;CA8FtE,CAAA"}
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/diff/merge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,KAAK,GAAI,CAAC,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE;;;CA8FtE,CAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/diff/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,MAAO,OAAO,KAAK,OAAO,YAsBrD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,YAAY,MAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAe3G,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,EAAE,YAY7C,CAAA"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/diff/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,EAAE,GAAG,OAAO,YAsBrD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;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,CAe3G,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,YAY7C,CAAA"}

package/dist/magic-proxy/proxy.d.ts

@@ -7,6 +7,8 @@ import type { UnknownObject } from '../types.js';
  *   will resolve and return the referenced value from the root object.
  * - All nested objects and arrays are recursively wrapped in proxies, so reference resolution
  *   works at any depth.
+ * - Properties starting with an underscore (_) are hidden and will not be accessible through
+ *   the proxy (returns undefined on access, false on 'in' checks, excluded from enumeration).
  * - Setting, deleting, and enumerating properties works as expected, including for proxied references.
  *
  * @param target - The object or array to wrap in a magic proxy
@@ -18,18 +20,26 @@ import type { UnknownObject } from '../types.js';
  *   definitions: {
  *     foo: { bar: 123 }
  *   },
- *   refObj: { $ref: '#/definitions/foo' }
+ *   refObj: { $ref: '#/definitions/foo' },
+ *   _internal: 'hidden property'
  * }
  * const proxy = createMagicProxy(input)
  *
  * // Accessing proxy.refObj['$ref-value'] will resolve to { bar: 123 }
  * console.log(proxy.refObj['$ref-value']) // { bar: 123 }
  *
+ * // Properties starting with underscore are hidden
+ * console.log(proxy._internal) // undefined
+ * console.log('_internal' in proxy) // false
+ * console.log(Object.keys(proxy)) // ['definitions', 'refObj'] (no '_internal')
+ *
  * // Setting and deleting properties works as expected
  * proxy.refObj.extra = 'hello'
  * delete proxy.refObj.extra
  */
-export declare const createMagicProxy: <T extends Record<keyof T & symbol, unknown>, S extends UnknownObject>(target: T, root?: S | T, cache?: Map<string, unknown>) => T;
+export declare const createMagicProxy: <T extends Record<keyof T & symbol, unknown>, S extends UnknownObject>(target: T, options?: {
+    showInternal?: boolean;
+}, root?: S | T, cache?: Map<string, unknown>, proxyCache?: WeakMap<object, T>) => T;
 /**
  * Gets the raw (non-proxied) version of an object created by createMagicProxy.
  * This is useful when you need to access the original object without the magic proxy wrapper.

package/dist/magic-proxy/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/magic-proxy/proxy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAW5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,aAAa,UAC3F,CAAC,SACH,CAAC,GAAG,CAAC,oCAyIZ,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAUnC"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/magic-proxy/proxy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAW5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,aAAa,EACnG,QAAQ,CAAC,EACT,UAAU;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,EACpC,OAAM,CAAC,GAAG,CAAU,EACpB,4BAAkC,EAClC,+BAAqC,MAgLtC,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAUnC"}

package/dist/magic-proxy/proxy.js

@@ -6,15 +6,19 @@ const isMagicProxy = Symbol("isMagicProxy");
 const magicProxyTarget = Symbol("magicProxyTarget");
 const REF_VALUE = "$ref-value";
 const REF_KEY = "$ref";
-const createMagicProxy = (target, root = target, cache = /* @__PURE__ */ new Map()) => {
+const createMagicProxy = (target, options, root = target, cache = /* @__PURE__ */ new Map(), proxyCache = /* @__PURE__ */ new WeakMap()) => {
   if (!isObject(target) && !Array.isArray(target)) {
     return target;
   }
+  if (proxyCache.has(target)) {
+    return proxyCache.get(target);
+  }
   const handler = {
     /**
      * Proxy "get" trap for magic proxy.
      * - If accessing the special isMagicProxy symbol, return true to identify proxy.
      * - If accessing the magicProxyTarget symbol, return the original target object.
+     * - Hide properties starting with underscore by returning undefined.
      * - If accessing "$ref-value" and the object has a local $ref, resolve and return the referenced value as a new magic proxy.
      * - For all other properties, recursively wrap the returned value in a magic proxy (if applicable).
      */
@@ -26,25 +30,34 @@ const createMagicProxy = (target, root = target, cache = /* @__PURE__ */ new Map
         return target2;
       }
       const ref = Reflect.get(target2, REF_KEY, receiver);
+      if (typeof prop === "string" && prop.startsWith("_") && !options?.showInternal) {
+        return void 0;
+      }
       if (prop === REF_VALUE && typeof ref === "string" && isLocalRef(ref)) {
         if (cache.has(ref)) {
           return cache.get(ref);
         }
         const resolvedValue = getValueByPath(root, parseJsonPointer(ref));
-        const proxiedValue = createMagicProxy(resolvedValue, root, cache);
+        const proxiedValue = createMagicProxy(resolvedValue, options, root, cache);
         cache.set(ref, proxiedValue);
         return proxiedValue;
       }
       const value = Reflect.get(target2, prop, receiver);
-      return createMagicProxy(value, root, cache);
+      return createMagicProxy(value, options, root, cache, proxyCache);
     },
     /**
      * Proxy "set" trap for magic proxy.
      * Allows setting properties on the proxied object.
      * This will update the underlying target object.
+     *
+     * Note: it will not update if the property starts with an underscore (_)
+     * Those will be considered private properties by the proxy
      */
     set(target2, prop, newValue, receiver) {
       const ref = Reflect.get(target2, REF_KEY, receiver);
+      if (typeof prop === "string" && prop.startsWith("_") && !options?.showInternal) {
+        return true;
+      }
       if (prop === REF_VALUE && typeof ref === "string" && isLocalRef(ref)) {
         const segments = getSegmentsFromPath(ref);
         if (segments.length === 0) {
@@ -72,9 +85,13 @@ const createMagicProxy = (target, root = target, cache = /* @__PURE__ */ new Map
      * - Pretend that "$ref-value" exists if "$ref" exists on the target.
      *   This allows expressions like `"$ref-value" in obj` to return true for objects with a $ref,
      *   even though "$ref-value" is a virtual property provided by the proxy.
+     * - Hide properties starting with underscore by returning false.
      * - For all other properties, defer to the default Reflect.has behavior.
      */
     has(target2, prop) {
+      if (typeof prop === "string" && prop.startsWith("_") && !options?.showInternal) {
+        return false;
+      }
       if (prop === REF_VALUE && REF_KEY in target2) {
         return true;
       }
@@ -86,21 +103,29 @@ const createMagicProxy = (target, root = target, cache = /* @__PURE__ */ new Map
      * - If the object has a "$ref" property, ensures that "$ref-value" is also included in the keys,
      *   even though "$ref-value" is a virtual property provided by the proxy.
      *   This allows Object.keys, Reflect.ownKeys, etc. to include "$ref-value" for objects with $ref.
+     * - Filters out properties starting with underscore.
      */
     ownKeys(target2) {
       const keys = Reflect.ownKeys(target2);
-      if (REF_KEY in target2 && !keys.includes(REF_VALUE)) {
-        keys.push(REF_VALUE);
+      const filteredKeys = keys.filter(
+        (key) => typeof key !== "string" || !(key.startsWith("_") && !options?.showInternal)
+      );
+      if (REF_KEY in target2 && !filteredKeys.includes(REF_VALUE)) {
+        filteredKeys.push(REF_VALUE);
       }
-      return keys;
+      return filteredKeys;
     },
     /**
      * Proxy "getOwnPropertyDescriptor" trap for magic proxy.
      * - For the virtual "$ref-value" property, returns a descriptor that makes it appear as a regular property.
+     * - Hide properties starting with underscore by returning undefined.
      * - For all other properties, delegates to the default Reflect.getOwnPropertyDescriptor behavior.
      * - This ensures that Object.getOwnPropertyDescriptor and similar methods work correctly with the virtual property.
      */
     getOwnPropertyDescriptor(target2, prop) {
+      if (typeof prop === "string" && prop.startsWith("_") && !options?.showInternal) {
+        return void 0;
+      }
       const ref = Reflect.get(target2, REF_KEY);
       if (prop === REF_VALUE && typeof ref === "string") {
         return {
@@ -113,7 +138,9 @@ const createMagicProxy = (target, root = target, cache = /* @__PURE__ */ new Map
       return Reflect.getOwnPropertyDescriptor(target2, prop);
     }
   };
-  return new Proxy(target, handler);
+  const proxied = new Proxy(target, handler);
+  proxyCache.set(target, proxied);
+  return proxied;
 };
 function getRaw(obj) {
   if (typeof obj !== "object" || obj === null) {

package/dist/magic-proxy/proxy.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/magic-proxy/proxy.ts"],
-  "sourcesContent": ["import { isLocalRef } from '@/bundle/bundle'\nimport type { UnknownObject } from '@/types'\nimport { getSegmentsFromPath } from '@/utils/get-segments-from-path'\nimport { isObject } from '@/utils/is-object'\nimport { getValueByPath, parseJsonPointer } from '@/utils/json-path-utils'\n\nconst isMagicProxy = Symbol('isMagicProxy')\nconst magicProxyTarget = Symbol('magicProxyTarget')\n\nconst REF_VALUE = '$ref-value'\nconst REF_KEY = '$ref'\n\n/**\n * Creates a \"magic\" proxy for a given object or array, enabling transparent access to\n * JSON Reference ($ref) values as if they were directly present on the object.\n *\n * - If an object contains a `$ref` property, accessing the special `$ref-value` property\n *   will resolve and return the referenced value from the root object.\n * - All nested objects and arrays are recursively wrapped in proxies, so reference resolution\n *   works at any depth.\n * - Setting, deleting, and enumerating properties works as expected, including for proxied references.\n *\n * @param target - The object or array to wrap in a magic proxy\n * @param root - The root object for resolving local JSON references (defaults to target)\n * @returns A proxied version of the input object/array with magic $ref-value support\n *\n * @example\n * const input = {\n *   definitions: {\n *     foo: { bar: 123 }\n *   },\n *   refObj: { $ref: '#/definitions/foo' }\n * }\n * const proxy = createMagicProxy(input)\n *\n * // Accessing proxy.refObj['$ref-value'] will resolve to { bar: 123 }\n * console.log(proxy.refObj['$ref-value']) // { bar: 123 }\n *\n * // Setting and deleting properties works as expected\n * proxy.refObj.extra = 'hello'\n * delete proxy.refObj.extra\n */\nexport const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S extends UnknownObject>(\n  target: T,\n  root: S | T = target,\n  cache = new Map<string, unknown>(),\n) => {\n  if (!isObject(target) && !Array.isArray(target)) {\n    return target\n  }\n\n  const handler: ProxyHandler<T> = {\n    /**\n     * Proxy \"get\" trap for magic proxy.\n     * - If accessing the special isMagicProxy symbol, return true to identify proxy.\n     * - If accessing the magicProxyTarget symbol, return the original target object.\n     * - If accessing \"$ref-value\" and the object has a local $ref, resolve and return the referenced value as a new magic proxy.\n     * - For all other properties, recursively wrap the returned value in a magic proxy (if applicable).\n     */\n    get(target, prop, receiver) {\n      if (prop === isMagicProxy) {\n        // Used to identify if an object is a magic proxy\n        return true\n      }\n\n      if (prop === magicProxyTarget) {\n        // Used to retrieve the original target object from the proxy\n        return target\n      }\n\n      const ref = Reflect.get(target, REF_KEY, receiver)\n\n      // If accessing \"$ref-value\" and $ref is a local reference, resolve and return the referenced value\n      if (prop === REF_VALUE && typeof ref === 'string' && isLocalRef(ref)) {\n        // Check cache first for performance optimization\n        if (cache.has(ref)) {\n          return cache.get(ref)\n        }\n\n        // Resolve the reference and create a new magic proxy\n        const resolvedValue = getValueByPath(root, parseJsonPointer(ref))\n        const proxiedValue = createMagicProxy(resolvedValue, root, cache)\n\n        // Store in cache for future lookups\n        cache.set(ref, proxiedValue)\n        return proxiedValue\n      }\n\n      // For all other properties, recursively wrap the value in a magic proxy\n      const value = Reflect.get(target, prop, receiver)\n      return createMagicProxy(value, root, cache)\n    },\n    /**\n     * Proxy \"set\" trap for magic proxy.\n     * Allows setting properties on the proxied object.\n     * This will update the underlying target object.\n     */\n    set(target, prop, newValue, receiver) {\n      const ref = Reflect.get(target, REF_KEY, receiver)\n\n      if (prop === REF_VALUE && typeof ref === 'string' && isLocalRef(ref)) {\n        const segments = getSegmentsFromPath(ref)\n\n        if (segments.length === 0) {\n          return false // Can not set top level $ref-value\n        }\n\n        const parentNode = getValueByPath(root, segments.slice(0, -1))\n\n        // TODO: Maybe we create the path if it does not exist?\n        // TODO: This can allow for invalid references to not throw errors\n        if (!parentNode || (!isObject(parentNode) && !Array.isArray(parentNode))) {\n          return false // Parent node does not exist, cannot set $ref-value\n        }\n        parentNode[segments.at(-1)] = newValue\n        return true\n      }\n\n      return Reflect.set(target, prop, newValue, receiver)\n    },\n    /**\n     * Proxy \"deleteProperty\" trap for magic proxy.\n     * Allows deleting properties from the proxied object.\n     * This will update the underlying target object.\n     */\n    deleteProperty(target, prop) {\n      return Reflect.deleteProperty(target, prop)\n    },\n    /**\n     * Proxy \"has\" trap for magic proxy.\n     * - Pretend that \"$ref-value\" exists if \"$ref\" exists on the target.\n     *   This allows expressions like `\"$ref-value\" in obj` to return true for objects with a $ref,\n     *   even though \"$ref-value\" is a virtual property provided by the proxy.\n     * - For all other properties, defer to the default Reflect.has behavior.\n     */\n    has(target, prop) {\n      // Pretend that \"$ref-value\" exists if \"$ref\" exists\n      if (prop === REF_VALUE && REF_KEY in target) {\n        return true\n      }\n      return Reflect.has(target, prop)\n    },\n    /**\n     * Proxy \"ownKeys\" trap for magic proxy.\n     * - Returns the list of own property keys for the proxied object.\n     * - If the object has a \"$ref\" property, ensures that \"$ref-value\" is also included in the keys,\n     *   even though \"$ref-value\" is a virtual property provided by the proxy.\n     *   This allows Object.keys, Reflect.ownKeys, etc. to include \"$ref-value\" for objects with $ref.\n     */\n    ownKeys(target) {\n      const keys = Reflect.ownKeys(target)\n      if (REF_KEY in target && !keys.includes(REF_VALUE)) {\n        keys.push(REF_VALUE)\n      }\n      return keys\n    },\n\n    /**\n     * Proxy \"getOwnPropertyDescriptor\" trap for magic proxy.\n     * - For the virtual \"$ref-value\" property, returns a descriptor that makes it appear as a regular property.\n     * - For all other properties, delegates to the default Reflect.getOwnPropertyDescriptor behavior.\n     * - This ensures that Object.getOwnPropertyDescriptor and similar methods work correctly with the virtual property.\n     */\n    getOwnPropertyDescriptor(target, prop) {\n      const ref = Reflect.get(target, REF_KEY)\n\n      if (prop === REF_VALUE && typeof ref === 'string') {\n        return {\n          configurable: true,\n          enumerable: true,\n          value: undefined,\n          writable: false,\n        }\n      }\n\n      // Otherwise, delegate to the default behavior\n      return Reflect.getOwnPropertyDescriptor(target, prop)\n    },\n  }\n\n  return new Proxy<T>(target, handler)\n}\n\n/**\n * Gets the raw (non-proxied) version of an object created by createMagicProxy.\n * This is useful when you need to access the original object without the magic proxy wrapper.\n *\n * @param obj - The magic proxy object to get the raw version of\n * @returns The raw version of the object\n * @example\n * const proxy = createMagicProxy({ foo: { $ref: '#/bar' } })\n * const raw = getRaw(proxy) // { foo: { $ref: '#/bar' } }\n */\nexport function getRaw<T>(obj: T): T {\n  if (typeof obj !== 'object' || obj === null) {\n    return obj\n  }\n\n  if ((obj as T & { [isMagicProxy]: boolean | undefined })[isMagicProxy]) {\n    return (obj as T & { [magicProxyTarget]: T })[magicProxyTarget]\n  }\n\n  return obj\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { isLocalRef } from '@/bundle/bundle'\nimport type { UnknownObject } from '@/types'\nimport { getSegmentsFromPath } from '@/utils/get-segments-from-path'\nimport { isObject } from '@/utils/is-object'\nimport { getValueByPath, parseJsonPointer } from '@/utils/json-path-utils'\n\nconst isMagicProxy = Symbol('isMagicProxy')\nconst magicProxyTarget = Symbol('magicProxyTarget')\n\nconst REF_VALUE = '$ref-value'\nconst REF_KEY = '$ref'\n\n/**\n * Creates a \"magic\" proxy for a given object or array, enabling transparent access to\n * JSON Reference ($ref) values as if they were directly present on the object.\n *\n * - If an object contains a `$ref` property, accessing the special `$ref-value` property\n *   will resolve and return the referenced value from the root object.\n * - All nested objects and arrays are recursively wrapped in proxies, so reference resolution\n *   works at any depth.\n * - Properties starting with an underscore (_) are hidden and will not be accessible through\n *   the proxy (returns undefined on access, false on 'in' checks, excluded from enumeration).\n * - Setting, deleting, and enumerating properties works as expected, including for proxied references.\n *\n * @param target - The object or array to wrap in a magic proxy\n * @param root - The root object for resolving local JSON references (defaults to target)\n * @returns A proxied version of the input object/array with magic $ref-value support\n *\n * @example\n * const input = {\n *   definitions: {\n *     foo: { bar: 123 }\n *   },\n *   refObj: { $ref: '#/definitions/foo' },\n *   _internal: 'hidden property'\n * }\n * const proxy = createMagicProxy(input)\n *\n * // Accessing proxy.refObj['$ref-value'] will resolve to { bar: 123 }\n * console.log(proxy.refObj['$ref-value']) // { bar: 123 }\n *\n * // Properties starting with underscore are hidden\n * console.log(proxy._internal) // undefined\n * console.log('_internal' in proxy) // false\n * console.log(Object.keys(proxy)) // ['definitions', 'refObj'] (no '_internal')\n *\n * // Setting and deleting properties works as expected\n * proxy.refObj.extra = 'hello'\n * delete proxy.refObj.extra\n */\nexport const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S extends UnknownObject>(\n  target: T,\n  options?: { showInternal?: boolean },\n  root: S | T = target,\n  cache = new Map<string, unknown>(),\n  proxyCache = new WeakMap<object, T>(),\n) => {\n  if (!isObject(target) && !Array.isArray(target)) {\n    return target\n  }\n\n  // Return existing proxy for the same target to ensure referential stability\n  if (proxyCache.has(target)) {\n    return proxyCache.get(target)\n  }\n\n  const handler: ProxyHandler<T> = {\n    /**\n     * Proxy \"get\" trap for magic proxy.\n     * - If accessing the special isMagicProxy symbol, return true to identify proxy.\n     * - If accessing the magicProxyTarget symbol, return the original target object.\n     * - Hide properties starting with underscore by returning undefined.\n     * - If accessing \"$ref-value\" and the object has a local $ref, resolve and return the referenced value as a new magic proxy.\n     * - For all other properties, recursively wrap the returned value in a magic proxy (if applicable).\n     */\n    get(target, prop, receiver) {\n      if (prop === isMagicProxy) {\n        // Used to identify if an object is a magic proxy\n        return true\n      }\n\n      if (prop === magicProxyTarget) {\n        // Used to retrieve the original target object from the proxy\n        return target\n      }\n\n      const ref = Reflect.get(target, REF_KEY, receiver)\n\n      // Hide properties starting with underscore - these are considered internal/private properties\n      // and should not be accessible through the magic proxy interface\n      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {\n        return undefined\n      }\n\n      // If accessing \"$ref-value\" and $ref is a local reference, resolve and return the referenced value\n      if (prop === REF_VALUE && typeof ref === 'string' && isLocalRef(ref)) {\n        // Check cache first for performance optimization\n        if (cache.has(ref)) {\n          return cache.get(ref)\n        }\n\n        // Resolve the reference and create a new magic proxy\n        const resolvedValue = getValueByPath(root, parseJsonPointer(ref))\n        const proxiedValue = createMagicProxy(resolvedValue, options, root, cache)\n\n        // Store in cache for future lookups\n        cache.set(ref, proxiedValue)\n        return proxiedValue\n      }\n\n      // For all other properties, recursively wrap the value in a magic proxy\n      const value = Reflect.get(target, prop, receiver)\n      return createMagicProxy(value as T, options, root, cache, proxyCache)\n    },\n    /**\n     * Proxy \"set\" trap for magic proxy.\n     * Allows setting properties on the proxied object.\n     * This will update the underlying target object.\n     *\n     * Note: it will not update if the property starts with an underscore (_)\n     * Those will be considered private properties by the proxy\n     */\n    set(target, prop, newValue, receiver) {\n      const ref = Reflect.get(target, REF_KEY, receiver)\n\n      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {\n        return true\n      }\n\n      if (prop === REF_VALUE && typeof ref === 'string' && isLocalRef(ref)) {\n        const segments = getSegmentsFromPath(ref)\n\n        if (segments.length === 0) {\n          return false // Can not set top level $ref-value\n        }\n\n        const parentNode = getValueByPath(root, segments.slice(0, -1))\n\n        // TODO: Maybe we create the path if it does not exist?\n        // TODO: This can allow for invalid references to not throw errors\n        if (!parentNode || (!isObject(parentNode) && !Array.isArray(parentNode))) {\n          return false // Parent node does not exist, cannot set $ref-value\n        }\n        parentNode[segments.at(-1)] = newValue\n        return true\n      }\n\n      return Reflect.set(target, prop, newValue, receiver)\n    },\n    /**\n     * Proxy \"deleteProperty\" trap for magic proxy.\n     * Allows deleting properties from the proxied object.\n     * This will update the underlying target object.\n     */\n    deleteProperty(target, prop) {\n      return Reflect.deleteProperty(target, prop)\n    },\n    /**\n     * Proxy \"has\" trap for magic proxy.\n     * - Pretend that \"$ref-value\" exists if \"$ref\" exists on the target.\n     *   This allows expressions like `\"$ref-value\" in obj` to return true for objects with a $ref,\n     *   even though \"$ref-value\" is a virtual property provided by the proxy.\n     * - Hide properties starting with underscore by returning false.\n     * - For all other properties, defer to the default Reflect.has behavior.\n     */\n    has(target, prop) {\n      // Hide properties starting with underscore\n      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {\n        return false\n      }\n\n      // Pretend that \"$ref-value\" exists if \"$ref\" exists\n      if (prop === REF_VALUE && REF_KEY in target) {\n        return true\n      }\n      return Reflect.has(target, prop)\n    },\n    /**\n     * Proxy \"ownKeys\" trap for magic proxy.\n     * - Returns the list of own property keys for the proxied object.\n     * - If the object has a \"$ref\" property, ensures that \"$ref-value\" is also included in the keys,\n     *   even though \"$ref-value\" is a virtual property provided by the proxy.\n     *   This allows Object.keys, Reflect.ownKeys, etc. to include \"$ref-value\" for objects with $ref.\n     * - Filters out properties starting with underscore.\n     */\n    ownKeys(target) {\n      const keys = Reflect.ownKeys(target)\n\n      // Filter out properties starting with underscore\n      const filteredKeys = keys.filter(\n        (key) => typeof key !== 'string' || !(key.startsWith('_') && !options?.showInternal),\n      )\n\n      if (REF_KEY in target && !filteredKeys.includes(REF_VALUE)) {\n        filteredKeys.push(REF_VALUE)\n      }\n      return filteredKeys\n    },\n\n    /**\n     * Proxy \"getOwnPropertyDescriptor\" trap for magic proxy.\n     * - For the virtual \"$ref-value\" property, returns a descriptor that makes it appear as a regular property.\n     * - Hide properties starting with underscore by returning undefined.\n     * - For all other properties, delegates to the default Reflect.getOwnPropertyDescriptor behavior.\n     * - This ensures that Object.getOwnPropertyDescriptor and similar methods work correctly with the virtual property.\n     */\n    getOwnPropertyDescriptor(target, prop) {\n      // Hide properties starting with underscore\n      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {\n        return undefined\n      }\n\n      const ref = Reflect.get(target, REF_KEY)\n\n      if (prop === REF_VALUE && typeof ref === 'string') {\n        return {\n          configurable: true,\n          enumerable: true,\n          value: undefined,\n          writable: false,\n        }\n      }\n\n      // Otherwise, delegate to the default behavior\n      return Reflect.getOwnPropertyDescriptor(target, prop)\n    },\n  }\n\n  const proxied = new Proxy<T>(target, handler)\n  proxyCache.set(target, proxied)\n  return proxied\n}\n\n/**\n * Gets the raw (non-proxied) version of an object created by createMagicProxy.\n * This is useful when you need to access the original object without the magic proxy wrapper.\n *\n * @param obj - The magic proxy object to get the raw version of\n * @returns The raw version of the object\n * @example\n * const proxy = createMagicProxy({ foo: { $ref: '#/bar' } })\n * const raw = getRaw(proxy) // { foo: { $ref: '#/bar' } }\n */\nexport function getRaw<T>(obj: T): T {\n  if (typeof obj !== 'object' || obj === null) {\n    return obj\n  }\n\n  if ((obj as T & { [isMagicProxy]: boolean | undefined })[isMagicProxy]) {\n    return (obj as T & { [magicProxyTarget]: T })[magicProxyTarget]\n  }\n\n  return obj\n}\n"],
+  "mappings": "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",
   "names": ["target"]
 }

package/dist/utils/is-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-object.d.ts","sourceRoot":"","sources":["../../src/utils/is-object.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,QAAQ,QAAS,GAAG,KAAG,GAAG,IAAI,MAAwE,CAAA"}
+{"version":3,"file":"is-object.d.ts","sourceRoot":"","sources":["../../src/utils/is-object.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,GAAG,KAAG,GAAG,IAAI,MAAwE,CAAA"}

package/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.3.0",
+  "version": "0.4.0",
   "engines": {
     "node": ">=20"
   },
@@ -50,7 +50,7 @@
   "dependencies": {
     "vue": "^3.5.17",
     "yaml": "2.8.0",
-    "@scalar/helpers": "0.0.8"
+    "@scalar/helpers": "0.0.9"
   },
   "devDependencies": {
     "fastify": "^5.3.3",

package/src/bundle/bundle.test.ts

@@ -1151,7 +1151,7 @@ describe('bundle', () => {
           [await getHash(`${url}/external/document.json`)]: {
             external: 'external',
             someChunk: {
-              $ref: `#/x-ext/${await getHash(`${url}/external/chunk3`)}`,
+              $ref: `#/x-ext/${await getHash(`${url}/chunk3`)}`,
               $global: true,
             },
           },
@@ -1167,14 +1167,14 @@ describe('bundle', () => {
               $ref: '#/c',
             },
           },
-          [await getHash(`${url}/external/chunk3`)]: {
+          [await getHash(`${url}/chunk3`)]: {
             chunk3: 'chunk3',
           },
         },
         'x-ext-urls': {
           [await getHash(`${url}/chunk1`)]: `${url}/chunk1`,
           [await getHash(`${url}/chunk2`)]: `${url}/chunk2`,
-          [await getHash(`${url}/external/chunk3`)]: `${url}/external/chunk3`,
+          [await getHash(`${url}/chunk3`)]: `${url}/chunk3`,
           [await getHash(`${url}/external/document.json`)]: `${url}/external/document.json`,
         },
       })
@@ -1309,7 +1309,7 @@ describe('bundle', () => {
           $ref: '/d#',
         },
       }))
-      server.get('/a/b/d', () => ({
+      server.get('/d', () => ({
         message: 'some resolved external reference',
       }))
       await server.listen({ port: port })
@@ -1321,14 +1321,8 @@ describe('bundle', () => {
       })
 
       expect(result).toEqual({
-        'a': {
-          '$ref': '#/x-ext/fb30100',
-        },
-        'x-ext': {
-          'fb30100': {
-            'message': 'some resolved external reference',
-          },
-        },
+        a: { '$ref': '#/x-ext/e53b62c' },
+        'x-ext': { e53b62c: { message: 'some resolved external reference' } },
       })
     })
   })

package/src/bundle/bundle.ts

@@ -206,6 +206,12 @@ function resolveReferencePath(base: string, relativePath: string) {
   if (isRemoteUrl(base)) {
     const url = new URL(base)
 
+    // If the url stars with a / we want it to resolve from the origin so we replace the pathname
+    if (relativePath.startsWith('/')) {
+      url.pathname = relativePath
+      return url.toString()
+    }
+
     const mergedPath = path.join(path.dirname(url.pathname), relativePath)
     return new URL(mergedPath, base).toString()
   }

package/src/magic-proxy/proxy.test.ts

@@ -1,6 +1,7 @@
-import { createMagicProxy, getRaw } from './proxy'
 import { describe, expect, it } from 'vitest'
 
+import { createMagicProxy, getRaw } from './proxy'
+
 describe('createMagicProxy', () => {
   describe('get', () => {
     it('should correctly proxy internal refs', () => {
@@ -1137,4 +1138,256 @@ describe('createMagicProxy', () => {
       expect(getRaw(proxied)).toEqual(input)
     })
   })
+
+  describe('show underscore properties when specified', () => {
+    it('should not hide properties starting with underscore from direct access', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+        __internal: 'also hidden',
+        normal_underscore: 'visible with underscore in middle',
+      }
+
+      const result = createMagicProxy(input, { showInternal: true })
+
+      expect(result.public).toBe('visible')
+      expect(result._private).toBe('hidden')
+      expect(result.__internal).toBe('also hidden')
+      expect(result.normal_underscore).toBe('visible with underscore in middle')
+    })
+
+    it('should not hide underscore properties from "in" operator', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+        __internal: 'also hidden',
+      }
+
+      const result = createMagicProxy(input, { showInternal: true })
+
+      expect('public' in result).toBe(true)
+      expect('_private' in result).toBe(true)
+      expect('__internal' in result).toBe(true)
+    })
+
+    it('should not exclude underscore properties from Object.keys enumeration', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+        __internal: 'also hidden',
+        another: 'visible',
+      }
+
+      const result = createMagicProxy(input, { showInternal: true })
+      const keys = Object.keys(result)
+
+      expect(keys).toContain('public')
+      expect(keys).toContain('another')
+      expect(keys).toContain('_private')
+      expect(keys).toContain('__internal')
+    })
+
+    it('should not hide underscore properties from getOwnPropertyDescriptor', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+      }
+
+      const result = createMagicProxy(input, { showInternal: true })
+
+      expect(Object.getOwnPropertyDescriptor(result, 'public')).toBeDefined()
+      expect(Object.getOwnPropertyDescriptor(result, '_private')).toBeDefined()
+    })
+
+    it('should not hide underscore properties in nested objects', () => {
+      const input = {
+        nested: {
+          public: 'visible',
+          _private: 'hidden',
+          deeper: {
+            _alsoHidden: 'secret',
+            visible: 'shown',
+          },
+        },
+        _topLevel: 'hidden',
+      }
+
+      const result = createMagicProxy(input, { showInternal: true })
+
+      expect(result._topLevel).toBe('hidden')
+      expect(result.nested.public).toBe('visible')
+      expect(result.nested._private).toBe('hidden')
+      expect(result.nested.deeper._alsoHidden).toBe('secret')
+      expect(result.nested.deeper.visible).toBe('shown')
+    })
+
+    it('should show underscore properties with arrays containing objects with underscore properties', () => {
+      const input = {
+        items: [
+          { public: 'item1', _private: 'hidden1' },
+          { public: 'item2', _private: 'hidden2' },
+        ],
+      }
+
+      const result = createMagicProxy(input, { showInternal: true })
+
+      expect(result.items[0].public).toBe('item1')
+      expect(result.items[0]._private).toBe('hidden1')
+      expect(result.items[1].public).toBe('item2')
+      expect(result.items[1]._private).toBe('hidden2')
+    })
+
+    it('should show underscore ref properties', () => {
+      const input = {
+        definitions: {
+          example: {
+            value: 'hello',
+            _internal: 'hidden',
+          },
+        },
+        _hiddenRef: { $ref: '#/definitions/example' },
+        publicRef: { $ref: '#/definitions/example' },
+      }
+
+      const result = createMagicProxy(input, { showInternal: true })
+
+      // Underscore property should be hidden
+      expect(result._hiddenRef).toEqual({
+        '$ref': '#/definitions/example',
+        '$ref-value': {
+          '_internal': 'hidden',
+          'value': 'hello',
+        },
+      })
+
+      // Public ref should work normally
+      expect(result.publicRef['$ref-value'].value).toBe('hello')
+
+      // Underscore properties in referenced objects should be hidden
+      expect(result.publicRef['$ref-value']._internal).toBe('hidden')
+    })
+  })
+
+  describe('hide underscore properties', () => {
+    it('should hide properties starting with underscore from direct access', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+        __internal: 'also hidden',
+        normal_underscore: 'visible with underscore in middle',
+      }
+
+      const result = createMagicProxy(input)
+
+      expect(result.public).toBe('visible')
+      expect(result._private).toBe(undefined)
+      expect(result.__internal).toBe(undefined)
+      expect(result.normal_underscore).toBe('visible with underscore in middle')
+    })
+
+    it('should hide underscore properties from "in" operator', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+        __internal: 'also hidden',
+      }
+
+      const result = createMagicProxy(input)
+
+      expect('public' in result).toBe(true)
+      expect('_private' in result).toBe(false)
+      expect('__internal' in result).toBe(false)
+    })
+
+    it('should exclude underscore properties from Object.keys enumeration', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+        __internal: 'also hidden',
+        another: 'visible',
+      }
+
+      const result = createMagicProxy(input)
+      const keys = Object.keys(result)
+
+      expect(keys).toContain('public')
+      expect(keys).toContain('another')
+      expect(keys).not.toContain('_private')
+      expect(keys).not.toContain('__internal')
+    })
+
+    it('should hide underscore properties from getOwnPropertyDescriptor', () => {
+      const input = {
+        public: 'visible',
+        _private: 'hidden',
+      }
+
+      const result = createMagicProxy(input)
+
+      expect(Object.getOwnPropertyDescriptor(result, 'public')).toBeDefined()
+      expect(Object.getOwnPropertyDescriptor(result, '_private')).toBe(undefined)
+    })
+
+    it('should hide underscore properties in nested objects', () => {
+      const input = {
+        nested: {
+          public: 'visible',
+          _private: 'hidden',
+          deeper: {
+            _alsoHidden: 'secret',
+            visible: 'shown',
+          },
+        },
+        _topLevel: 'hidden',
+      }
+
+      const result = createMagicProxy(input)
+
+      expect(result._topLevel).toBe(undefined)
+      expect(result.nested.public).toBe('visible')
+      expect(result.nested._private).toBe(undefined)
+      expect(result.nested.deeper._alsoHidden).toBe(undefined)
+      expect(result.nested.deeper.visible).toBe('shown')
+    })
+
+    it('should work with arrays containing objects with underscore properties', () => {
+      const input = {
+        items: [
+          { public: 'item1', _private: 'hidden1' },
+          { public: 'item2', _private: 'hidden2' },
+        ],
+      }
+
+      const result = createMagicProxy(input)
+
+      expect(result.items[0].public).toBe('item1')
+      expect(result.items[0]._private).toBe(undefined)
+      expect(result.items[1].public).toBe('item2')
+      expect(result.items[1]._private).toBe(undefined)
+    })
+
+    it('should still allow refs to work with underscore hiding', () => {
+      const input = {
+        definitions: {
+          example: {
+            value: 'hello',
+            _internal: 'hidden',
+          },
+        },
+        _hiddenRef: { $ref: '#/definitions/example' },
+        publicRef: { $ref: '#/definitions/example' },
+      }
+
+      const result = createMagicProxy(input)
+
+      // Underscore property should be hidden
+      expect(result._hiddenRef).toBe(undefined)
+
+      // Public ref should work normally
+      expect(result.publicRef['$ref-value'].value).toBe('hello')
+
+      // Underscore properties in referenced objects should be hidden
+      expect(result.publicRef['$ref-value']._internal).toBe(undefined)
+    })
+  })
 })

package/src/magic-proxy/proxy.ts

@@ -18,6 +18,8 @@ const REF_KEY = '$ref'
  *   will resolve and return the referenced value from the root object.
  * - All nested objects and arrays are recursively wrapped in proxies, so reference resolution
  *   works at any depth.
+ * - Properties starting with an underscore (_) are hidden and will not be accessible through
+ *   the proxy (returns undefined on access, false on 'in' checks, excluded from enumeration).
  * - Setting, deleting, and enumerating properties works as expected, including for proxied references.
  *
  * @param target - The object or array to wrap in a magic proxy
@@ -29,31 +31,45 @@ const REF_KEY = '$ref'
  *   definitions: {
  *     foo: { bar: 123 }
  *   },
- *   refObj: { $ref: '#/definitions/foo' }
+ *   refObj: { $ref: '#/definitions/foo' },
+ *   _internal: 'hidden property'
  * }
  * const proxy = createMagicProxy(input)
  *
  * // Accessing proxy.refObj['$ref-value'] will resolve to { bar: 123 }
  * console.log(proxy.refObj['$ref-value']) // { bar: 123 }
  *
+ * // Properties starting with underscore are hidden
+ * console.log(proxy._internal) // undefined
+ * console.log('_internal' in proxy) // false
+ * console.log(Object.keys(proxy)) // ['definitions', 'refObj'] (no '_internal')
+ *
  * // Setting and deleting properties works as expected
  * proxy.refObj.extra = 'hello'
  * delete proxy.refObj.extra
  */
 export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S extends UnknownObject>(
   target: T,
+  options?: { showInternal?: boolean },
   root: S | T = target,
   cache = new Map<string, unknown>(),
+  proxyCache = new WeakMap<object, T>(),
 ) => {
   if (!isObject(target) && !Array.isArray(target)) {
     return target
   }
 
+  // Return existing proxy for the same target to ensure referential stability
+  if (proxyCache.has(target)) {
+    return proxyCache.get(target)
+  }
+
   const handler: ProxyHandler<T> = {
     /**
      * Proxy "get" trap for magic proxy.
      * - If accessing the special isMagicProxy symbol, return true to identify proxy.
      * - If accessing the magicProxyTarget symbol, return the original target object.
+     * - Hide properties starting with underscore by returning undefined.
      * - If accessing "$ref-value" and the object has a local $ref, resolve and return the referenced value as a new magic proxy.
      * - For all other properties, recursively wrap the returned value in a magic proxy (if applicable).
      */
@@ -70,6 +86,12 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
 
       const ref = Reflect.get(target, REF_KEY, receiver)
 
+      // Hide properties starting with underscore - these are considered internal/private properties
+      // and should not be accessible through the magic proxy interface
+      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {
+        return undefined
+      }
+
       // If accessing "$ref-value" and $ref is a local reference, resolve and return the referenced value
       if (prop === REF_VALUE && typeof ref === 'string' && isLocalRef(ref)) {
         // Check cache first for performance optimization
@@ -79,7 +101,7 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
 
         // Resolve the reference and create a new magic proxy
         const resolvedValue = getValueByPath(root, parseJsonPointer(ref))
-        const proxiedValue = createMagicProxy(resolvedValue, root, cache)
+        const proxiedValue = createMagicProxy(resolvedValue, options, root, cache)
 
         // Store in cache for future lookups
         cache.set(ref, proxiedValue)
@@ -88,16 +110,23 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
 
       // For all other properties, recursively wrap the value in a magic proxy
       const value = Reflect.get(target, prop, receiver)
-      return createMagicProxy(value, root, cache)
+      return createMagicProxy(value as T, options, root, cache, proxyCache)
     },
     /**
      * Proxy "set" trap for magic proxy.
      * Allows setting properties on the proxied object.
      * This will update the underlying target object.
+     *
+     * Note: it will not update if the property starts with an underscore (_)
+     * Those will be considered private properties by the proxy
      */
     set(target, prop, newValue, receiver) {
       const ref = Reflect.get(target, REF_KEY, receiver)
 
+      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {
+        return true
+      }
+
       if (prop === REF_VALUE && typeof ref === 'string' && isLocalRef(ref)) {
         const segments = getSegmentsFromPath(ref)
 
@@ -131,9 +160,15 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
      * - Pretend that "$ref-value" exists if "$ref" exists on the target.
      *   This allows expressions like `"$ref-value" in obj` to return true for objects with a $ref,
      *   even though "$ref-value" is a virtual property provided by the proxy.
+     * - Hide properties starting with underscore by returning false.
      * - For all other properties, defer to the default Reflect.has behavior.
      */
     has(target, prop) {
+      // Hide properties starting with underscore
+      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {
+        return false
+      }
+
       // Pretend that "$ref-value" exists if "$ref" exists
       if (prop === REF_VALUE && REF_KEY in target) {
         return true
@@ -146,22 +181,35 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
      * - If the object has a "$ref" property, ensures that "$ref-value" is also included in the keys,
      *   even though "$ref-value" is a virtual property provided by the proxy.
      *   This allows Object.keys, Reflect.ownKeys, etc. to include "$ref-value" for objects with $ref.
+     * - Filters out properties starting with underscore.
      */
     ownKeys(target) {
       const keys = Reflect.ownKeys(target)
-      if (REF_KEY in target && !keys.includes(REF_VALUE)) {
-        keys.push(REF_VALUE)
+
+      // Filter out properties starting with underscore
+      const filteredKeys = keys.filter(
+        (key) => typeof key !== 'string' || !(key.startsWith('_') && !options?.showInternal),
+      )
+
+      if (REF_KEY in target && !filteredKeys.includes(REF_VALUE)) {
+        filteredKeys.push(REF_VALUE)
       }
-      return keys
+      return filteredKeys
     },
 
     /**
      * Proxy "getOwnPropertyDescriptor" trap for magic proxy.
      * - For the virtual "$ref-value" property, returns a descriptor that makes it appear as a regular property.
+     * - Hide properties starting with underscore by returning undefined.
      * - For all other properties, delegates to the default Reflect.getOwnPropertyDescriptor behavior.
      * - This ensures that Object.getOwnPropertyDescriptor and similar methods work correctly with the virtual property.
      */
     getOwnPropertyDescriptor(target, prop) {
+      // Hide properties starting with underscore
+      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {
+        return undefined
+      }
+
       const ref = Reflect.get(target, REF_KEY)
 
       if (prop === REF_VALUE && typeof ref === 'string') {
@@ -178,7 +226,9 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
     },
   }
 
-  return new Proxy<T>(target, handler)
+  const proxied = new Proxy<T>(target, handler)
+  proxyCache.set(target, proxied)
+  return proxied
 }
 
 /**