@scalar/json-magic 0.5.2 → 0.6.1

package/.turbo/turbo-build.log

@@ -1,10 +1,10 @@
 
-> @scalar/json-magic@0.5.2 build /home/runner/work/scalar/scalar/packages/json-magic
+> @scalar/json-magic@0.6.1 build /home/runner/work/scalar/scalar/packages/json-magic
 > scalar-build-esbuild
 
-@scalar/json-magic: Build completed in 29.84ms
+@scalar/json-magic: Build completed in 25.49ms
 
-> @scalar/json-magic@0.5.2 types:build /home/runner/work/scalar/scalar/packages/json-magic
+> @scalar/json-magic@0.6.1 types:build /home/runner/work/scalar/scalar/packages/json-magic
 > scalar-types-build
 
-Types build completed in 1.58s
+Types build completed in 1.86s

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @scalar/json-magic
 
+## 0.6.1
+
+### Patch Changes
+
+- 2089748: chore: add logs when fetching unsupported formats
+- 8a7fb2a: fix: schema properties starting with an underscore are hidden
+- Updated dependencies [3f6d0b9]
+  - @scalar/helpers@0.0.12
+
+## 0.6.0
+
+### Minor Changes
+
+- 4951456: feat: merge yaml aliases for in-mem representation
+
 ## 0.5.2
 
 ### Patch Changes

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAK3D,KAAK,WAAW,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IACtD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC3F,CAAC,CAAA;AAcF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAgCxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG,YAAY,CAShG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/bundle/plugins/fetch-urls/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAK3D,KAAK,WAAW,GAAG,OAAO,CAAC;IACzB,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAA;IACtD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC3F,CAAC,CAAA;AAcF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAyCxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GAAG,YAAY,CAShG"}

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

@@ -25,10 +25,16 @@ async function fetchUrl(url, limiter, config) {
         data: normalize(body)
       };
     }
+    const contentType = result.headers.get("Content-Type") ?? "";
+    if (["text/html", "application/xml"].includes(contentType)) {
+      console.warn(`[WARN] We only support JSON/YAML formats, received ${contentType}`);
+    }
+    console.warn(`[WARN] Fetch failed with status ${result.status} ${result.statusText} for URL: ${url}`);
     return {
       ok: false
     };
   } catch {
+    console.warn(`[WARN] Failed to parse JSON/YAML from URL: ${url}`);
     return {
       ok: false
     };

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/bundle/plugins/fetch-urls/index.ts"],
-  "sourcesContent": ["import type { LoaderPlugin, ResolveResult } from '@/bundle'\nimport { isRemoteUrl } from '@/bundle/bundle'\nimport { createLimiter } from '@/bundle/create-limiter'\nimport { normalize } from '@/helpers/normalize'\n\ntype FetchConfig = Partial<{\n  headers: { headers: HeadersInit; domains: string[] }[]\n  fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>\n}>\n\n/**\n * Safely checks for host from a URL\n * Needed because we cannot create a URL from a relative remote URL ex: examples/openapi.json\n */\nconst getHost = (url: string): string | null => {\n  try {\n    return new URL(url).host\n  } catch {\n    return null\n  }\n}\n\n/**\n * Fetches and normalizes data from a remote URL\n * @param url - The URL to fetch data from\n * @returns A promise that resolves to either the normalized data or an error result\n * @example\n * ```ts\n * const result = await fetchUrl('https://api.example.com/data.json')\n * if (result.ok) {\n *   console.log(result.data) // The normalized data\n * } else {\n *   console.log('Failed to fetch data')\n * }\n * ```\n */\nexport async function fetchUrl(\n  url: string,\n  limiter: <T>(fn: () => Promise<T>) => Promise<T>,\n  config?: FetchConfig,\n): Promise<ResolveResult> {\n  try {\n    const host = getHost(url)\n\n    // Get the headers that match the domain\n    const headers = config?.headers?.find((a) => a.domains.find((d) => d === host) !== undefined)?.headers\n\n    const exec = config?.fetch ?? fetch\n\n    const result = await limiter(() =>\n      exec(url, {\n        headers,\n      }),\n    )\n\n    if (result.ok) {\n      const body = await result.text()\n\n      return {\n        ok: true,\n        data: normalize(body),\n      }\n    }\n\n    return {\n      ok: false,\n    }\n  } catch {\n    return {\n      ok: false,\n    }\n  }\n}\n\n/**\n * Creates a plugin for handling remote URL references.\n * This plugin validates and fetches data from HTTP/HTTPS URLs.\n *\n * @returns A plugin object with validate and exec functions\n * @example\n * const urlPlugin = fetchUrls()\n * if (urlPlugin.validate('https://example.com/schema.json')) {\n *   const result = await urlPlugin.exec('https://example.com/schema.json')\n * }\n */\nexport function fetchUrls(config?: FetchConfig & Partial<{ limit: number | null }>): LoaderPlugin {\n  // If there is a limit specified we limit the number of concurrent calls\n  const limiter = config?.limit ? createLimiter(config.limit) : <T>(fn: () => Promise<T>) => fn()\n\n  return {\n    type: 'loader',\n    validate: isRemoteUrl,\n    exec: (value) => fetchUrl(value, limiter, config),\n  }\n}\n"],
-  "mappings": "AACA,SAAS,mBAAmB;AAC5B,SAAS,qBAAqB;AAC9B,SAAS,iBAAiB;AAW1B,MAAM,UAAU,CAAC,QAA+B;AAC9C,MAAI;AACF,WAAO,IAAI,IAAI,GAAG,EAAE;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAgBA,eAAsB,SACpB,KACA,SACA,QACwB;AACxB,MAAI;AACF,UAAM,OAAO,QAAQ,GAAG;AAGxB,UAAM,UAAU,QAAQ,SAAS,KAAK,CAAC,MAAM,EAAE,QAAQ,KAAK,CAAC,MAAM,MAAM,IAAI,MAAM,MAAS,GAAG;AAE/F,UAAM,OAAO,QAAQ,SAAS;AAE9B,UAAM,SAAS,MAAM;AAAA,MAAQ,MAC3B,KAAK,KAAK;AAAA,QACR;AAAA,MACF,CAAC;AAAA,IACH;AAEA,QAAI,OAAO,IAAI;AACb,YAAM,OAAO,MAAM,OAAO,KAAK;AAE/B,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,MAAM,UAAU,IAAI;AAAA,MACtB;AAAA,IACF;AAEA,WAAO;AAAA,MACL,IAAI;AAAA,IACN;AAAA,EACF,QAAQ;AACN,WAAO;AAAA,MACL,IAAI;AAAA,IACN;AAAA,EACF;AACF;AAaO,SAAS,UAAU,QAAwE;AAEhG,QAAM,UAAU,QAAQ,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAI,OAAyB,GAAG;AAE9F,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU;AAAA,IACV,MAAM,CAAC,UAAU,SAAS,OAAO,SAAS,MAAM;AAAA,EAClD;AACF;",
+  "sourcesContent": ["import type { LoaderPlugin, ResolveResult } from '@/bundle'\nimport { isRemoteUrl } from '@/bundle/bundle'\nimport { createLimiter } from '@/bundle/create-limiter'\nimport { normalize } from '@/helpers/normalize'\n\ntype FetchConfig = Partial<{\n  headers: { headers: HeadersInit; domains: string[] }[]\n  fetch: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>\n}>\n\n/**\n * Safely checks for host from a URL\n * Needed because we cannot create a URL from a relative remote URL ex: examples/openapi.json\n */\nconst getHost = (url: string): string | null => {\n  try {\n    return new URL(url).host\n  } catch {\n    return null\n  }\n}\n\n/**\n * Fetches and normalizes data from a remote URL\n * @param url - The URL to fetch data from\n * @returns A promise that resolves to either the normalized data or an error result\n * @example\n * ```ts\n * const result = await fetchUrl('https://api.example.com/data.json')\n * if (result.ok) {\n *   console.log(result.data) // The normalized data\n * } else {\n *   console.log('Failed to fetch data')\n * }\n * ```\n */\nexport async function fetchUrl(\n  url: string,\n  limiter: <T>(fn: () => Promise<T>) => Promise<T>,\n  config?: FetchConfig,\n): Promise<ResolveResult> {\n  try {\n    const host = getHost(url)\n\n    // Get the headers that match the domain\n    const headers = config?.headers?.find((a) => a.domains.find((d) => d === host) !== undefined)?.headers\n\n    const exec = config?.fetch ?? fetch\n\n    const result = await limiter(() =>\n      exec(url, {\n        headers,\n      }),\n    )\n\n    if (result.ok) {\n      const body = await result.text()\n\n      return {\n        ok: true,\n        data: normalize(body),\n      }\n    }\n\n    const contentType = result.headers.get('Content-Type') ?? ''\n\n    // Warn if the content type is HTML or XML as we only support JSON/YAML\n    if (['text/html', 'application/xml'].includes(contentType)) {\n      console.warn(`[WARN] We only support JSON/YAML formats, received ${contentType}`)\n    }\n\n    console.warn(`[WARN] Fetch failed with status ${result.status} ${result.statusText} for URL: ${url}`)\n    return {\n      ok: false,\n    }\n  } catch {\n    console.warn(`[WARN] Failed to parse JSON/YAML from URL: ${url}`)\n    return {\n      ok: false,\n    }\n  }\n}\n\n/**\n * Creates a plugin for handling remote URL references.\n * This plugin validates and fetches data from HTTP/HTTPS URLs.\n *\n * @returns A plugin object with validate and exec functions\n * @example\n * const urlPlugin = fetchUrls()\n * if (urlPlugin.validate('https://example.com/schema.json')) {\n *   const result = await urlPlugin.exec('https://example.com/schema.json')\n * }\n */\nexport function fetchUrls(config?: FetchConfig & Partial<{ limit: number | null }>): LoaderPlugin {\n  // If there is a limit specified we limit the number of concurrent calls\n  const limiter = config?.limit ? createLimiter(config.limit) : <T>(fn: () => Promise<T>) => fn()\n\n  return {\n    type: 'loader',\n    validate: isRemoteUrl,\n    exec: (value) => fetchUrl(value, limiter, config),\n  }\n}\n"],
+  "mappings": "AACA,SAAS,mBAAmB;AAC5B,SAAS,qBAAqB;AAC9B,SAAS,iBAAiB;AAW1B,MAAM,UAAU,CAAC,QAA+B;AAC9C,MAAI;AACF,WAAO,IAAI,IAAI,GAAG,EAAE;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAgBA,eAAsB,SACpB,KACA,SACA,QACwB;AACxB,MAAI;AACF,UAAM,OAAO,QAAQ,GAAG;AAGxB,UAAM,UAAU,QAAQ,SAAS,KAAK,CAAC,MAAM,EAAE,QAAQ,KAAK,CAAC,MAAM,MAAM,IAAI,MAAM,MAAS,GAAG;AAE/F,UAAM,OAAO,QAAQ,SAAS;AAE9B,UAAM,SAAS,MAAM;AAAA,MAAQ,MAC3B,KAAK,KAAK;AAAA,QACR;AAAA,MACF,CAAC;AAAA,IACH;AAEA,QAAI,OAAO,IAAI;AACb,YAAM,OAAO,MAAM,OAAO,KAAK;AAE/B,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,MAAM,UAAU,IAAI;AAAA,MACtB;AAAA,IACF;AAEA,UAAM,cAAc,OAAO,QAAQ,IAAI,cAAc,KAAK;AAG1D,QAAI,CAAC,aAAa,iBAAiB,EAAE,SAAS,WAAW,GAAG;AAC1D,cAAQ,KAAK,sDAAsD,WAAW,EAAE;AAAA,IAClF;AAEA,YAAQ,KAAK,mCAAmC,OAAO,MAAM,IAAI,OAAO,UAAU,aAAa,GAAG,EAAE;AACpG,WAAO;AAAA,MACL,IAAI;AAAA,IACN;AAAA,EACF,QAAQ;AACN,YAAQ,KAAK,8CAA8C,GAAG,EAAE;AAChE,WAAO;AAAA,MACL,IAAI;AAAA,IACN;AAAA,EACF;AACF;AAaO,SAAS,UAAU,QAAwE;AAEhG,QAAM,UAAU,QAAQ,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAI,OAAyB,GAAG;AAE9F,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU;AAAA,IACV,MAAM,CAAC,UAAU,SAAS,OAAO,SAAS,MAAM;AAAA,EAClD;AACF;",
   "names": []
 }

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

@@ -8,7 +8,7 @@ function parseYaml() {
       try {
         return {
           ok: true,
-          data: YAML.parse(value)
+          data: YAML.parse(value, { merge: true, maxAliasCount: 1e4 })
         };
       } catch {
         return {

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/bundle/plugins/parse-yaml/index.ts"],
-  "sourcesContent": ["import YAML from 'yaml'\n\nimport type { LoaderPlugin, ResolveResult } from '@/bundle'\nimport { isYaml } from '@/helpers/is-yaml'\n\n/**\n * Creates a plugin that parses YAML strings into JavaScript objects.\n * @returns A plugin object with validate and exec functions\n * @example\n * ```ts\n * const yamlPlugin = parseYaml()\n * const result = yamlPlugin.exec('name: John\\nage: 30')\n * // result = { name: 'John', age: 30 }\n * ```\n */\nexport function parseYaml(): LoaderPlugin {\n  return {\n    type: 'loader',\n    validate: isYaml,\n    exec: async (value): Promise<ResolveResult> => {\n      try {\n        return {\n          ok: true,\n          data: YAML.parse(value),\n        }\n      } catch {\n        return {\n          ok: false,\n        }\n      }\n    },\n  }\n}\n"],
-  "mappings": "AAAA,OAAO,UAAU;AAGjB,SAAS,cAAc;AAYhB,SAAS,YAA0B;AACxC,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU;AAAA,IACV,MAAM,OAAO,UAAkC;AAC7C,UAAI;AACF,eAAO;AAAA,UACL,IAAI;AAAA,UACJ,MAAM,KAAK,MAAM,KAAK;AAAA,QACxB;AAAA,MACF,QAAQ;AACN,eAAO;AAAA,UACL,IAAI;AAAA,QACN;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;",
+  "sourcesContent": ["import YAML from 'yaml'\n\nimport type { LoaderPlugin, ResolveResult } from '@/bundle'\nimport { isYaml } from '@/helpers/is-yaml'\n\n/**\n * Creates a plugin that parses YAML strings into JavaScript objects.\n * @returns A plugin object with validate and exec functions\n * @example\n * ```ts\n * const yamlPlugin = parseYaml()\n * const result = yamlPlugin.exec('name: John\\nage: 30')\n * // result = { name: 'John', age: 30 }\n * ```\n */\nexport function parseYaml(): LoaderPlugin {\n  return {\n    type: 'loader',\n    validate: isYaml,\n    exec: async (value): Promise<ResolveResult> => {\n      try {\n        return {\n          ok: true,\n          data: YAML.parse(value, { merge: true, maxAliasCount: 10000 }),\n        }\n      } catch {\n        return {\n          ok: false,\n        }\n      }\n    },\n  }\n}\n"],
+  "mappings": "AAAA,OAAO,UAAU;AAGjB,SAAS,cAAc;AAYhB,SAAS,YAA0B;AACxC,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU;AAAA,IACV,MAAM,OAAO,UAAkC;AAC7C,UAAI;AACF,eAAO;AAAA,UACL,IAAI;AAAA,UACJ,MAAM,KAAK,MAAM,OAAO,EAAE,OAAO,MAAM,eAAe,IAAM,CAAC;AAAA,QAC/D;AAAA,MACF,QAAQ;AACN,eAAO;AAAA,UACL,IAAI;AAAA,QACN;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;",
   "names": []
 }

package/dist/helpers/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/helpers/normalize.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,GAAG,OA4BrC"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/helpers/normalize.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,GAAG,OA6BrC"}

package/dist/helpers/normalize.js

@@ -16,7 +16,8 @@ function normalize(content) {
         return void 0;
       }
       return parse(content, {
-        maxAliasCount: 1e4
+        maxAliasCount: 1e4,
+        merge: true
       });
     }
   }

package/dist/helpers/normalize.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/helpers/normalize.ts"],
-  "sourcesContent": ["import { parse } from 'yaml'\n\n/**\n * Normalize a string (YAML, JSON, object) to a JavaScript datatype.\n */\nexport function normalize(content: any) {\n  if (content === null) {\n    return undefined\n  }\n\n  if (typeof content === 'string') {\n    if (content.trim() === '') {\n      return undefined\n    }\n\n    try {\n      return JSON.parse(content)\n    } catch (_error) {\n      // Does it look like YAML?\n      const hasColon = /^[^:]+:/.test(content)\n      const isJson = content.slice(0, 50).trimStart().startsWith('{')\n\n      if (!hasColon || isJson) {\n        return undefined\n      }\n\n      return parse(content, {\n        maxAliasCount: 10000,\n      })\n    }\n  }\n\n  return content\n}\n"],
-  "mappings": "AAAA,SAAS,aAAa;AAKf,SAAS,UAAU,SAAc;AACtC,MAAI,YAAY,MAAM;AACpB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,YAAY,UAAU;AAC/B,QAAI,QAAQ,KAAK,MAAM,IAAI;AACzB,aAAO;AAAA,IACT;AAEA,QAAI;AACF,aAAO,KAAK,MAAM,OAAO;AAAA,IAC3B,SAAS,QAAQ;AAEf,YAAM,WAAW,UAAU,KAAK,OAAO;AACvC,YAAM,SAAS,QAAQ,MAAM,GAAG,EAAE,EAAE,UAAU,EAAE,WAAW,GAAG;AAE9D,UAAI,CAAC,YAAY,QAAQ;AACvB,eAAO;AAAA,MACT;AAEA,aAAO,MAAM,SAAS;AAAA,QACpB,eAAe;AAAA,MACjB,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;",
+  "sourcesContent": ["import { parse } from 'yaml'\n\n/**\n * Normalize a string (YAML, JSON, object) to a JavaScript datatype.\n */\nexport function normalize(content: any) {\n  if (content === null) {\n    return undefined\n  }\n\n  if (typeof content === 'string') {\n    if (content.trim() === '') {\n      return undefined\n    }\n\n    try {\n      return JSON.parse(content)\n    } catch (_error) {\n      // Does it look like YAML?\n      const hasColon = /^[^:]+:/.test(content)\n      const isJson = content.slice(0, 50).trimStart().startsWith('{')\n\n      if (!hasColon || isJson) {\n        return undefined\n      }\n\n      return parse(content, {\n        maxAliasCount: 10000,\n        merge: true,\n      })\n    }\n  }\n\n  return content\n}\n"],
+  "mappings": "AAAA,SAAS,aAAa;AAKf,SAAS,UAAU,SAAc;AACtC,MAAI,YAAY,MAAM;AACpB,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,YAAY,UAAU;AAC/B,QAAI,QAAQ,KAAK,MAAM,IAAI;AACzB,aAAO;AAAA,IACT;AAEA,QAAI;AACF,aAAO,KAAK,MAAM,OAAO;AAAA,IAC3B,SAAS,QAAQ;AAEf,YAAM,WAAW,UAAU,KAAK,OAAO;AACvC,YAAM,SAAS,QAAQ,MAAM,GAAG,EAAE,EAAE,UAAU,EAAE,WAAW,GAAG;AAE9D,UAAI,CAAC,YAAY,QAAQ;AACvB,eAAO;AAAA,MACT;AAEA,aAAO,MAAM,SAAS;AAAA,QACpB,eAAe;AAAA,QACf,OAAO;AAAA,MACT,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;",
   "names": []
 }

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

@@ -6,7 +6,7 @@ import type { UnknownObject } from '../types.js';
  * Features:
  * - If an object contains a `$ref` property, accessing the special `$ref-value` property 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 considered internal and are hidden by default: they return undefined on access, are excluded from enumeration, and `'in'` checks return false. This can be overridden with the `showInternal` option.
+ * - Properties starting with `__scalar_` are considered internal and are hidden by default: they return undefined on access, are excluded from enumeration, and `'in'` checks return false. This can be overridden with the `showInternal` option.
  * - Setting, deleting, and enumerating properties works as expected, including for proxied references.
  * - Ensures referential stability by caching proxies for the same target object.
  *
@@ -21,17 +21,17 @@ import type { UnknownObject } from '../types.js';
  *     foo: { bar: 123 }
  *   },
  *   refObj: { $ref: '#/definitions/foo' },
- *   _internal: 'hidden property'
+ *   __scalar_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')
+ * // Properties starting with __scalar_ are hidden
+ * console.log(proxy.__scalar_internal) // undefined
+ * console.log('__scalar_internal' in proxy) // false
+ * console.log(Object.keys(proxy)) // ['definitions', 'refObj'] (no '__scalar_internal')
  *
  * // Setting and deleting properties works as expected
  * proxy.refObj.extra = 'hello'

package/dist/magic-proxy/proxy.js

@@ -25,7 +25,7 @@ const createMagicProxy = (target, options, args = {
      * 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.
+     * - Hide properties starting with __scalar_ 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).
      */
@@ -36,7 +36,7 @@ const createMagicProxy = (target, options, args = {
       if (prop === magicProxyTarget) {
         return target2;
       }
-      if (typeof prop === "string" && prop.startsWith("_") && !options?.showInternal) {
+      if (typeof prop === "string" && prop.startsWith("__scalar_") && !options?.showInternal) {
         return void 0;
       }
       const ref = Reflect.get(target2, REF_KEY, receiver);
@@ -65,12 +65,12 @@ const createMagicProxy = (target, options, args = {
      * 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 (_)
+     * Note: it will not update if the property starts with __scalar_
      * 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) {
+      if (typeof prop === "string" && prop.startsWith("__scalar_") && !options?.showInternal) {
         return true;
       }
       if (prop === REF_VALUE && typeof ref === "string") {
@@ -110,11 +110,11 @@ Please fix your input file to fix this issue.`
      * - 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.
+     * - Hide properties starting with __scalar_ 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) {
+      if (typeof prop === "string" && prop.startsWith("__scalar_") && !options?.showInternal) {
         return false;
       }
       if (prop === REF_VALUE && REF_KEY in target2) {
@@ -128,12 +128,12 @@ Please fix your input file to fix this issue.`
      * - 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.
+     * - Filters out properties starting with __scalar_.
      */
     ownKeys(target2) {
       const keys = Reflect.ownKeys(target2);
       const filteredKeys = keys.filter(
-        (key) => typeof key !== "string" || !(key.startsWith("_") && !options?.showInternal)
+        (key) => typeof key !== "string" || !(key.startsWith("__scalar_") && !options?.showInternal)
       );
       if (REF_KEY in target2 && !filteredKeys.includes(REF_VALUE)) {
         filteredKeys.push(REF_VALUE);
@@ -143,12 +143,12 @@ Please fix your input file to fix this issue.`
     /**
      * 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.
+     * - Hide properties starting with __scalar_ 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) {
+      if (typeof prop === "string" && prop.startsWith("__scalar_") && !options?.showInternal) {
         return void 0;
       }
       const ref = Reflect.get(target2, REF_KEY);

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/magic-proxy/proxy.ts"],
-  "sourcesContent": ["import { convertToLocalRef } from '@/helpers/convert-to-local-ref'\nimport { getId, getSchemas } from '@/helpers/get-schemas'\nimport { getValueByPath } from '@/helpers/get-value-by-path'\nimport { isObject } from '@/helpers/is-object'\nimport { createPathFromSegments, parseJsonPointer } from '@/helpers/json-path-utils'\nimport type { UnknownObject } from '@/types'\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 * Features:\n * - If an object contains a `$ref` property, accessing the special `$ref-value` property 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 works at any depth.\n * - Properties starting with an underscore (_) are considered internal and are hidden by default: they return undefined on access, are excluded from enumeration, and `'in'` checks return false. This can be overridden with the `showInternal` option.\n * - Setting, deleting, and enumerating properties works as expected, including for proxied references.\n * - Ensures referential stability by caching proxies for the same target object.\n *\n * @param target - The object or array to wrap in a magic proxy\n * @param options - Optional settings (e.g., showInternal to expose internal properties)\n * @param args - Internal arguments for advanced usage (root object, proxy/cache maps, current context)\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?: Partial<{ showInternal: boolean }>,\n  args: {\n    /**\n     * The root object for resolving local JSON references.\n     */\n    root: S | T\n    /**\n     * Cache to store already created proxies for target objects to ensure referential stability.\n     *\n     * It is helpful when dealing with reactive frameworks like Vue,\n     */\n    proxyCache: WeakMap<object, T>\n    /**\n     * Cache to store resolved JSON references.\n     */\n    cache: Map<string, unknown>\n    /**\n     * Map of all schemas by their $id or $anchor for cross-document reference resolution.\n     */\n    schemas: Map<string, string>\n    /**\n     * The current JSON path context within the root object.\n     *\n     * Used to resolve $anchor references correctly.\n     */\n    currentContext: string\n  } = {\n    root: target,\n    proxyCache: new WeakMap(),\n    cache: new Map(),\n    schemas: getSchemas(target),\n    currentContext: '',\n  },\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 (args.proxyCache.has(target)) {\n    return args.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      // 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      // Get the $ref value of the current target (if any)\n      const ref = Reflect.get(target, REF_KEY, receiver)\n      // Get the identifier ($id) of the current target for context tracking\n      const id = getId(target)\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') {\n        // Check cache first for performance optimization\n        if (args.cache.has(ref)) {\n          return args.cache.get(ref)\n        }\n\n        const path = convertToLocalRef(ref, id ?? args.currentContext, args.schemas)\n\n        if (path === undefined) {\n          return undefined\n        }\n\n        // Resolve the reference and create a new magic proxy\n        const resolvedValue = getValueByPath(args.root, parseJsonPointer(`#/${path}`))\n        const proxiedValue = createMagicProxy(resolvedValue.value, options, {\n          ...args,\n          currentContext: resolvedValue.context,\n        })\n\n        // Store in cache for future lookups\n        args.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, { ...args, currentContext: id ?? args.currentContext })\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') {\n        const id = getId(target)\n        const path = convertToLocalRef(ref, id ?? args.currentContext, args.schemas)\n\n        if (path === undefined) {\n          return undefined\n        }\n\n        const segments = parseJsonPointer(`#/${path}`)\n\n        if (segments.length === 0) {\n          return false // Can not set top level $ref-value\n        }\n\n        // Get the parent node or create it if it does not exist\n        const getParentNode = () => getValueByPath(args.root, segments.slice(0, -1)).value\n\n        if (getParentNode() === undefined) {\n          createPathFromSegments(args.root, segments.slice(0, -1))\n\n          // In this case the ref is pointing to an invalid path, so we warn the user\n          console.warn(\n            `Trying to set $ref-value for invalid reference: ${ref}\\n\\nPlease fix your input file to fix this issue.`,\n          )\n        }\n\n        // Set the value on the parent node\n        getParentNode()[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  args.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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",
+  "sourcesContent": ["import { convertToLocalRef } from '@/helpers/convert-to-local-ref'\nimport { getId, getSchemas } from '@/helpers/get-schemas'\nimport { getValueByPath } from '@/helpers/get-value-by-path'\nimport { isObject } from '@/helpers/is-object'\nimport { createPathFromSegments, parseJsonPointer } from '@/helpers/json-path-utils'\nimport type { UnknownObject } from '@/types'\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 * Features:\n * - If an object contains a `$ref` property, accessing the special `$ref-value` property 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 works at any depth.\n * - Properties starting with `__scalar_` are considered internal and are hidden by default: they return undefined on access, are excluded from enumeration, and `'in'` checks return false. This can be overridden with the `showInternal` option.\n * - Setting, deleting, and enumerating properties works as expected, including for proxied references.\n * - Ensures referential stability by caching proxies for the same target object.\n *\n * @param target - The object or array to wrap in a magic proxy\n * @param options - Optional settings (e.g., showInternal to expose internal properties)\n * @param args - Internal arguments for advanced usage (root object, proxy/cache maps, current context)\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 *   __scalar_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 __scalar_ are hidden\n * console.log(proxy.__scalar_internal) // undefined\n * console.log('__scalar_internal' in proxy) // false\n * console.log(Object.keys(proxy)) // ['definitions', 'refObj'] (no '__scalar_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?: Partial<{ showInternal: boolean }>,\n  args: {\n    /**\n     * The root object for resolving local JSON references.\n     */\n    root: S | T\n    /**\n     * Cache to store already created proxies for target objects to ensure referential stability.\n     *\n     * It is helpful when dealing with reactive frameworks like Vue,\n     */\n    proxyCache: WeakMap<object, T>\n    /**\n     * Cache to store resolved JSON references.\n     */\n    cache: Map<string, unknown>\n    /**\n     * Map of all schemas by their $id or $anchor for cross-document reference resolution.\n     */\n    schemas: Map<string, string>\n    /**\n     * The current JSON path context within the root object.\n     *\n     * Used to resolve $anchor references correctly.\n     */\n    currentContext: string\n  } = {\n    root: target,\n    proxyCache: new WeakMap(),\n    cache: new Map(),\n    schemas: getSchemas(target),\n    currentContext: '',\n  },\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 (args.proxyCache.has(target)) {\n    return args.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 __scalar_ 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      // Hide properties starting with __scalar_ - these are considered internal/private properties\n      // and should not be accessible through the magic proxy interface\n      if (typeof prop === 'string' && prop.startsWith('__scalar_') && !options?.showInternal) {\n        return undefined\n      }\n\n      // Get the $ref value of the current target (if any)\n      const ref = Reflect.get(target, REF_KEY, receiver)\n      // Get the identifier ($id) of the current target for context tracking\n      const id = getId(target)\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') {\n        // Check cache first for performance optimization\n        if (args.cache.has(ref)) {\n          return args.cache.get(ref)\n        }\n\n        const path = convertToLocalRef(ref, id ?? args.currentContext, args.schemas)\n\n        if (path === undefined) {\n          return undefined\n        }\n\n        // Resolve the reference and create a new magic proxy\n        const resolvedValue = getValueByPath(args.root, parseJsonPointer(`#/${path}`))\n        const proxiedValue = createMagicProxy(resolvedValue.value, options, {\n          ...args,\n          currentContext: resolvedValue.context,\n        })\n\n        // Store in cache for future lookups\n        args.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, { ...args, currentContext: id ?? args.currentContext })\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 __scalar_\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('__scalar_') && !options?.showInternal) {\n        return true\n      }\n\n      if (prop === REF_VALUE && typeof ref === 'string') {\n        const id = getId(target)\n        const path = convertToLocalRef(ref, id ?? args.currentContext, args.schemas)\n\n        if (path === undefined) {\n          return undefined\n        }\n\n        const segments = parseJsonPointer(`#/${path}`)\n\n        if (segments.length === 0) {\n          return false // Can not set top level $ref-value\n        }\n\n        // Get the parent node or create it if it does not exist\n        const getParentNode = () => getValueByPath(args.root, segments.slice(0, -1)).value\n\n        if (getParentNode() === undefined) {\n          createPathFromSegments(args.root, segments.slice(0, -1))\n\n          // In this case the ref is pointing to an invalid path, so we warn the user\n          console.warn(\n            `Trying to set $ref-value for invalid reference: ${ref}\\n\\nPlease fix your input file to fix this issue.`,\n          )\n        }\n\n        // Set the value on the parent node\n        getParentNode()[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 __scalar_ 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 __scalar_\n      if (typeof prop === 'string' && prop.startsWith('__scalar_') && !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 __scalar_.\n     */\n    ownKeys(target) {\n      const keys = Reflect.ownKeys(target)\n\n      // Filter out properties starting with __scalar_\n      const filteredKeys = keys.filter(\n        (key) => typeof key !== 'string' || !(key.startsWith('__scalar_') && !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 __scalar_ 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 __scalar_\n      if (typeof prop === 'string' && prop.startsWith('__scalar_') && !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  args.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/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.5.2",
+  "version": "0.6.1",
   "engines": {
     "node": ">=20"
   },
@@ -54,7 +54,7 @@
   },
   "dependencies": {
     "yaml": "2.8.0",
-    "@scalar/helpers": "0.0.11"
+    "@scalar/helpers": "0.0.12"
   },
   "devDependencies": {
     "fastify": "^5.3.3",

package/src/bundle/plugins/fetch-urls/index.ts

@@ -62,10 +62,19 @@ export async function fetchUrl(
       }
     }
 
+    const contentType = result.headers.get('Content-Type') ?? ''
+
+    // Warn if the content type is HTML or XML as we only support JSON/YAML
+    if (['text/html', 'application/xml'].includes(contentType)) {
+      console.warn(`[WARN] We only support JSON/YAML formats, received ${contentType}`)
+    }
+
+    console.warn(`[WARN] Fetch failed with status ${result.status} ${result.statusText} for URL: ${url}`)
     return {
       ok: false,
     }
   } catch {
+    console.warn(`[WARN] Failed to parse JSON/YAML from URL: ${url}`)
     return {
       ok: false,
     }

package/src/bundle/plugins/parse-yaml/index.ts

@@ -21,7 +21,7 @@ export function parseYaml(): LoaderPlugin {
       try {
         return {
           ok: true,
-          data: YAML.parse(value),
+          data: YAML.parse(value, { merge: true, maxAliasCount: 10000 }),
         }
       } catch {
         return {

package/src/helpers/normalize.ts

@@ -26,6 +26,7 @@ export function normalize(content: any) {
 
       return parse(content, {
         maxAliasCount: 10000,
+        merge: true,
       })
     }
   }

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

@@ -1154,41 +1154,41 @@ describe('createMagicProxy', () => {
   })
 
   describe('show underscore properties when specified', () => {
-    it('should not hide properties starting with underscore from direct access', () => {
+    it('should not hide properties starting with __scalar_ from direct access', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
-        __internal: 'also hidden',
+        __scalar_private: 'hidden',
+        __scalar_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.__scalar_private).toBe('hidden')
+      expect(result.__scalar_internal).toBe('also hidden')
       expect(result.normal_underscore).toBe('visible with underscore in middle')
     })
 
-    it('should not hide underscore properties from "in" operator', () => {
+    it('should not hide __scalar_ properties from "in" operator', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
-        __internal: 'also hidden',
+        __scalar_private: 'hidden',
+        __scalar_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)
+      expect('__scalar_private' in result).toBe(true)
+      expect('__scalar_internal' in result).toBe(true)
     })
 
-    it('should not exclude underscore properties from Object.keys enumeration', () => {
+    it('should not exclude __scalar_ properties from Object.keys enumeration', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
-        __internal: 'also hidden',
+        __scalar_private: 'hidden',
+        __scalar_internal: 'also hidden',
         another: 'visible',
       }
 
@@ -1197,79 +1197,79 @@ describe('createMagicProxy', () => {
 
       expect(keys).toContain('public')
       expect(keys).toContain('another')
-      expect(keys).toContain('_private')
-      expect(keys).toContain('__internal')
+      expect(keys).toContain('__scalar_private')
+      expect(keys).toContain('__scalar_internal')
     })
 
-    it('should not hide underscore properties from getOwnPropertyDescriptor', () => {
+    it('should not hide __scalar_ properties from getOwnPropertyDescriptor', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
+        __scalar_private: 'hidden',
       }
 
       const result = createMagicProxy(input, { showInternal: true })
 
       expect(Object.getOwnPropertyDescriptor(result, 'public')).toBeDefined()
-      expect(Object.getOwnPropertyDescriptor(result, '_private')).toBeDefined()
+      expect(Object.getOwnPropertyDescriptor(result, '__scalar_private')).toBeDefined()
     })
 
-    it('should not hide underscore properties in nested objects', () => {
+    it('should not hide __scalar_ properties in nested objects', () => {
       const input = {
         nested: {
           public: 'visible',
-          _private: 'hidden',
+          __scalar_private: 'hidden',
           deeper: {
-            _alsoHidden: 'secret',
+            __scalar_alsoHidden: 'secret',
             visible: 'shown',
           },
         },
-        _topLevel: 'hidden',
+        __scalar_topLevel: 'hidden',
       }
 
       const result = createMagicProxy(input, { showInternal: true })
 
-      expect(result._topLevel).toBe('hidden')
+      expect(result.__scalar_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.__scalar_private).toBe('hidden')
+      expect(result.nested.deeper.__scalar_alsoHidden).toBe('secret')
       expect(result.nested.deeper.visible).toBe('shown')
     })
 
-    it('should show underscore properties with arrays containing objects with underscore properties', () => {
+    it('should show __scalar_ properties with arrays containing objects with __scalar_ properties', () => {
       const input = {
         items: [
-          { public: 'item1', _private: 'hidden1' },
-          { public: 'item2', _private: 'hidden2' },
+          { public: 'item1', __scalar_private: 'hidden1' },
+          { public: 'item2', __scalar_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[0].__scalar_private).toBe('hidden1')
       expect(result.items[1].public).toBe('item2')
-      expect(result.items[1]._private).toBe('hidden2')
+      expect(result.items[1].__scalar_private).toBe('hidden2')
     })
 
-    it('should show underscore ref properties', () => {
+    it('should show __scalar_ ref properties', () => {
       const input = {
         definitions: {
           example: {
             value: 'hello',
-            _internal: 'hidden',
+            __scalar_internal: 'hidden',
           },
         },
-        _hiddenRef: { $ref: '#/definitions/example' },
+        __scalar_hiddenRef: { $ref: '#/definitions/example' },
         publicRef: { $ref: '#/definitions/example' },
       }
 
       const result = createMagicProxy(input, { showInternal: true })
 
-      // Underscore property should be hidden
-      expect(result._hiddenRef).toEqual({
+      // __scalar_ property should be hidden
+      expect(result.__scalar_hiddenRef).toEqual({
         '$ref': '#/definitions/example',
         '$ref-value': {
-          '_internal': 'hidden',
+          '__scalar_internal': 'hidden',
           'value': 'hello',
         },
       })
@@ -1277,8 +1277,8 @@ describe('createMagicProxy', () => {
       // 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')
+      // __scalar_ properties in referenced objects should be hidden
+      expect(result.publicRef['$ref-value'].__scalar_internal).toBe('hidden')
     })
   })
 
@@ -1830,42 +1830,46 @@ describe('createMagicProxy', () => {
     })
   })
 
-  describe('hide underscore properties', () => {
-    it('should hide properties starting with underscore from direct access', () => {
+  describe('hide __scalar_ properties', () => {
+    it('should hide properties starting with __scalar_ from direct access', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
-        __internal: 'also hidden',
+        __scalar_private: 'hidden',
+        __scalar_internal: 'also hidden',
         normal_underscore: 'visible with underscore in middle',
+        _id: 'legitimate user property', // This should NOT be hidden
+        _type: 'another legitimate property', // This should NOT be hidden
       }
 
       const result = createMagicProxy(input)
 
       expect(result.public).toBe('visible')
-      expect(result._private).toBe(undefined)
-      expect(result.__internal).toBe(undefined)
+      expect(result.__scalar_private).toBe(undefined)
+      expect(result.__scalar_internal).toBe(undefined)
       expect(result.normal_underscore).toBe('visible with underscore in middle')
+      expect(result._id).toBe('legitimate user property') // Should be visible
+      expect(result._type).toBe('another legitimate property') // Should be visible
     })
 
-    it('should hide underscore properties from "in" operator', () => {
+    it('should hide __scalar_ properties from "in" operator', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
-        __internal: 'also hidden',
+        __scalar_private: 'hidden',
+        __scalar_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)
+      expect('__scalar_private' in result).toBe(false)
+      expect('__scalar_internal' in result).toBe(false)
     })
 
-    it('should exclude underscore properties from Object.keys enumeration', () => {
+    it('should exclude __scalar_ properties from Object.keys enumeration', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
-        __internal: 'also hidden',
+        __scalar_private: 'hidden',
+        __scalar_internal: 'also hidden',
         another: 'visible',
       }
 
@@ -1874,82 +1878,110 @@ describe('createMagicProxy', () => {
 
       expect(keys).toContain('public')
       expect(keys).toContain('another')
-      expect(keys).not.toContain('_private')
-      expect(keys).not.toContain('__internal')
+      expect(keys).not.toContain('__scalar_private')
+      expect(keys).not.toContain('__scalar_internal')
     })
 
-    it('should hide underscore properties from getOwnPropertyDescriptor', () => {
+    it('should hide __scalar_ properties from getOwnPropertyDescriptor', () => {
       const input = {
         public: 'visible',
-        _private: 'hidden',
+        __scalar_private: 'hidden',
       }
 
       const result = createMagicProxy(input)
 
       expect(Object.getOwnPropertyDescriptor(result, 'public')).toBeDefined()
-      expect(Object.getOwnPropertyDescriptor(result, '_private')).toBe(undefined)
+      expect(Object.getOwnPropertyDescriptor(result, '__scalar_private')).toBe(undefined)
     })
 
-    it('should hide underscore properties in nested objects', () => {
+    it('should hide __scalar_ properties in nested objects', () => {
       const input = {
         nested: {
           public: 'visible',
-          _private: 'hidden',
+          __scalar_private: 'hidden',
           deeper: {
-            _alsoHidden: 'secret',
+            __scalar_alsoHidden: 'secret',
             visible: 'shown',
           },
         },
-        _topLevel: 'hidden',
+        __scalar_topLevel: 'hidden',
       }
 
       const result = createMagicProxy(input)
 
-      expect(result._topLevel).toBe(undefined)
+      expect(result.__scalar_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.__scalar_private).toBe(undefined)
+      expect(result.nested.deeper.__scalar_alsoHidden).toBe(undefined)
       expect(result.nested.deeper.visible).toBe('shown')
     })
 
-    it('should work with arrays containing objects with underscore properties', () => {
+    it('should work with arrays containing objects with __scalar_ properties', () => {
       const input = {
         items: [
-          { public: 'item1', _private: 'hidden1' },
-          { public: 'item2', _private: 'hidden2' },
+          { public: 'item1', __scalar_private: 'hidden1' },
+          { public: 'item2', __scalar_private: 'hidden2' },
         ],
       }
 
       const result = createMagicProxy(input)
 
       expect(result.items[0].public).toBe('item1')
-      expect(result.items[0]._private).toBe(undefined)
+      expect(result.items[0].__scalar_private).toBe(undefined)
       expect(result.items[1].public).toBe('item2')
-      expect(result.items[1]._private).toBe(undefined)
+      expect(result.items[1].__scalar_private).toBe(undefined)
     })
 
-    it('should still allow refs to work with underscore hiding', () => {
+    it('should still allow refs to work with __scalar_ hiding', () => {
       const input = {
         definitions: {
           example: {
             value: 'hello',
-            _internal: 'hidden',
+            __scalar_internal: 'hidden',
           },
         },
-        _hiddenRef: { $ref: '#/definitions/example' },
+        __scalar_hiddenRef: { $ref: '#/definitions/example' },
         publicRef: { $ref: '#/definitions/example' },
       }
 
       const result = createMagicProxy(input)
 
-      // Underscore property should be hidden
-      expect(result._hiddenRef).toBe(undefined)
+      // __scalar_ property should be hidden
+      expect(result.__scalar_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)
+      // __scalar_ properties in referenced objects should be hidden
+      expect(result.publicRef['$ref-value'].__scalar_internal).toBe(undefined)
+    })
+
+    it('preserves regular underscore properties', () => {
+      const input = {
+        _id: 'user123',
+        user_name: 'john',
+        __version: '1.0',
+        normal_property: 'visible',
+      }
+
+      const result = createMagicProxy(input)
+
+      // Regular underscore properties should be visible
+      expect(result._id).toBe('user123')
+      expect(result.user_name).toBe('john')
+      expect(result.__version).toBe('1.0')
+      expect(result.normal_property).toBe('visible')
+
+      // Should be included in enumeration and "in" checks
+      expect('_id' in result).toBe(true)
+      expect('user_name' in result).toBe(true)
+      expect('__version' in result).toBe(true)
+
+      const keys = Object.keys(result)
+      expect(keys).toContain('_id')
+      expect(keys).toContain('user_name')
+      expect(keys).toContain('__version')
+      expect(keys).toContain('normal_property')
     })
   })
 })

package/src/magic-proxy/proxy.ts

@@ -18,7 +18,7 @@ const REF_KEY = '$ref'
  * Features:
  * - If an object contains a `$ref` property, accessing the special `$ref-value` property 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 considered internal and are hidden by default: they return undefined on access, are excluded from enumeration, and `'in'` checks return false. This can be overridden with the `showInternal` option.
+ * - Properties starting with `__scalar_` are considered internal and are hidden by default: they return undefined on access, are excluded from enumeration, and `'in'` checks return false. This can be overridden with the `showInternal` option.
  * - Setting, deleting, and enumerating properties works as expected, including for proxied references.
  * - Ensures referential stability by caching proxies for the same target object.
  *
@@ -33,17 +33,17 @@ const REF_KEY = '$ref'
  *     foo: { bar: 123 }
  *   },
  *   refObj: { $ref: '#/definitions/foo' },
- *   _internal: 'hidden property'
+ *   __scalar_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')
+ * // Properties starting with __scalar_ are hidden
+ * console.log(proxy.__scalar_internal) // undefined
+ * console.log('__scalar_internal' in proxy) // false
+ * console.log(Object.keys(proxy)) // ['definitions', 'refObj'] (no '__scalar_internal')
  *
  * // Setting and deleting properties works as expected
  * proxy.refObj.extra = 'hello'
@@ -99,7 +99,7 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
      * 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.
+     * - Hide properties starting with __scalar_ 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).
      */
@@ -114,9 +114,9 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
         return target
       }
 
-      // Hide properties starting with underscore - these are considered internal/private properties
+      // Hide properties starting with __scalar_ - these are considered internal/private properties
       // and should not be accessible through the magic proxy interface
-      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {
+      if (typeof prop === 'string' && prop.startsWith('__scalar_') && !options?.showInternal) {
         return undefined
       }
 
@@ -159,13 +159,13 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
      * 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 (_)
+     * Note: it will not update if the property starts with __scalar_
      * 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) {
+      if (typeof prop === 'string' && prop.startsWith('__scalar_') && !options?.showInternal) {
         return true
       }
 
@@ -215,12 +215,12 @@ 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.
+     * - Hide properties starting with __scalar_ 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) {
+      // Hide properties starting with __scalar_
+      if (typeof prop === 'string' && prop.startsWith('__scalar_') && !options?.showInternal) {
         return false
       }
 
@@ -236,14 +236,14 @@ 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.
+     * - Filters out properties starting with __scalar_.
      */
     ownKeys(target) {
       const keys = Reflect.ownKeys(target)
 
-      // Filter out properties starting with underscore
+      // Filter out properties starting with __scalar_
       const filteredKeys = keys.filter(
-        (key) => typeof key !== 'string' || !(key.startsWith('_') && !options?.showInternal),
+        (key) => typeof key !== 'string' || !(key.startsWith('__scalar_') && !options?.showInternal),
       )
 
       if (REF_KEY in target && !filteredKeys.includes(REF_VALUE)) {
@@ -255,13 +255,13 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
     /**
      * 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.
+     * - Hide properties starting with __scalar_ 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) {
+      // Hide properties starting with __scalar_
+      if (typeof prop === 'string' && prop.startsWith('__scalar_') && !options?.showInternal) {
         return undefined
       }