@scalar/json-magic 0.3.1 → 0.4.1

package/.turbo/turbo-build.log

@@ -1,10 +1,10 @@
 
-> @scalar/json-magic@0.3.1 build /home/runner/work/scalar/scalar/packages/json-magic
+> @scalar/json-magic@0.4.1 build /home/runner/work/scalar/scalar/packages/json-magic
 > scalar-build-esbuild
 
-@scalar/json-magic: Build completed in 59.61ms
+@scalar/json-magic: Build completed in 33.98ms
 
-> @scalar/json-magic@0.3.1 types:build /home/runner/work/scalar/scalar/packages/json-magic
+> @scalar/json-magic@0.4.1 types:build /home/runner/work/scalar/scalar/packages/json-magic
 > scalar-types-build
 
-Types build completed in 1.55s
+Types build completed in 1.54s

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @scalar/json-magic
 
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [821717b]
+  - @scalar/helpers@0.0.10
+
+## 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

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.1",
+  "version": "0.4.1",
   "engines": {
     "node": ">=20"
   },
@@ -50,12 +50,12 @@
   "dependencies": {
     "vue": "^3.5.17",
     "yaml": "2.8.0",
-    "@scalar/helpers": "0.0.8"
+    "@scalar/helpers": "0.0.10"
   },
   "devDependencies": {
     "fastify": "^5.3.3",
     "vite": "6.1.6",
-    "@scalar/build-tooling": "0.2.6"
+    "@scalar/build-tooling": "0.2.7"
   },
   "scripts": {
     "build": "scalar-build-esbuild",

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
 }
 
 /**