@scalar/json-magic 0.1.0 → 0.3.0

package/dist/magic-proxy/proxy.js

@@ -1,107 +1,130 @@
-import { isReactive, toRaw } from "vue";
 import { isLocalRef } from "../bundle/bundle.js";
+import { getSegmentsFromPath } from "../utils/get-segments-from-path.js";
 import { isObject } from "../utils/is-object.js";
 import { getValueByPath, parseJsonPointer } from "../utils/json-path-utils.js";
 const isMagicProxy = Symbol("isMagicProxy");
-function createProxyHandler(sourceDocument, resolvedProxyCache) {
-  return {
-    get(target, property, receiver) {
-      if (property === TARGET_SYMBOL) {
-        return target;
-      }
-      if (property === isMagicProxy) {
+const magicProxyTarget = Symbol("magicProxyTarget");
+const REF_VALUE = "$ref-value";
+const REF_KEY = "$ref";
+const createMagicProxy = (target, root = target, cache = /* @__PURE__ */ new Map()) => {
+  if (!isObject(target) && !Array.isArray(target)) {
+    return 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.
+     * - 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).
+     */
+    get(target2, prop, receiver) {
+      if (prop === isMagicProxy) {
         return true;
       }
-      const value = Reflect.get(target, property, receiver);
-      const deepResolveNestedRefs = (value2, originalRef) => {
-        if (!isObject(value2) && !Array.isArray(value2)) {
-          return value2;
-        }
-        if (typeof value2 === "object" && "$ref" in value2) {
-          const ref = value2.$ref;
-          if (isLocalRef(ref)) {
-            const referencePath = parseJsonPointer(ref);
-            const resolvedValue = getValueByPath(sourceDocument, referencePath);
-            return deepResolveNestedRefs(resolvedValue, originalRef ?? ref);
-          }
-        }
-        if (originalRef && typeof value2 === "object") {
-          return createMagicProxy({ ...value2, "x-original-ref": originalRef }, sourceDocument, resolvedProxyCache);
+      if (prop === magicProxyTarget) {
+        return target2;
+      }
+      const ref = Reflect.get(target2, REF_KEY, receiver);
+      if (prop === REF_VALUE && typeof ref === "string" && isLocalRef(ref)) {
+        if (cache.has(ref)) {
+          return cache.get(ref);
         }
-        return createMagicProxy(value2, sourceDocument, resolvedProxyCache);
-      };
-      return deepResolveNestedRefs(value);
+        const resolvedValue = getValueByPath(root, parseJsonPointer(ref));
+        const proxiedValue = createMagicProxy(resolvedValue, root, cache);
+        cache.set(ref, proxiedValue);
+        return proxiedValue;
+      }
+      const value = Reflect.get(target2, prop, receiver);
+      return createMagicProxy(value, root, cache);
     },
-    set(target, property, newValue, receiver) {
-      const rawTarget = isReactive(target) ? toRaw(target) : target;
-      const currentValue = rawTarget[property];
-      if (typeof currentValue === "object" && isObject(currentValue) && "$ref" in currentValue && typeof currentValue.$ref === "string" && isLocalRef(currentValue.$ref)) {
-        const referencePath = parseJsonPointer(currentValue.$ref);
-        const targetObject = getValueByPath(sourceDocument, referencePath.slice(0, -1));
-        const lastPathSegment = referencePath[referencePath.length - 1];
-        if (targetObject && lastPathSegment) {
-          targetObject[lastPathSegment] = newValue;
+    /**
+     * Proxy "set" trap for magic proxy.
+     * Allows setting properties on the proxied object.
+     * This will update the underlying target object.
+     */
+    set(target2, prop, newValue, receiver) {
+      const ref = Reflect.get(target2, REF_KEY, receiver);
+      if (prop === REF_VALUE && typeof ref === "string" && isLocalRef(ref)) {
+        const segments = getSegmentsFromPath(ref);
+        if (segments.length === 0) {
+          return false;
+        }
+        const parentNode = getValueByPath(root, segments.slice(0, -1));
+        if (!parentNode || !isObject(parentNode) && !Array.isArray(parentNode)) {
+          return false;
         }
-      } else {
-        Reflect.set(rawTarget, property, newValue, receiver);
+        parentNode[segments.at(-1)] = newValue;
+        return true;
       }
-      return true;
+      return Reflect.set(target2, prop, newValue, receiver);
     },
-    has(target, key) {
-      if (typeof key === "string" && key !== "$ref" && typeof target.$ref === "string" && isLocalRef(target.$ref)) {
-        const referencePath = parseJsonPointer(target["$ref"]);
-        const resolvedValue = getValueByPath(sourceDocument, referencePath);
-        return resolvedValue ? key in resolvedValue : false;
+    /**
+     * Proxy "deleteProperty" trap for magic proxy.
+     * Allows deleting properties from the proxied object.
+     * This will update the underlying target object.
+     */
+    deleteProperty(target2, prop) {
+      return Reflect.deleteProperty(target2, prop);
+    },
+    /**
+     * Proxy "has" trap for magic proxy.
+     * - 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.
+     * - For all other properties, defer to the default Reflect.has behavior.
+     */
+    has(target2, prop) {
+      if (prop === REF_VALUE && REF_KEY in target2) {
+        return true;
       }
-      return key in target;
+      return Reflect.has(target2, prop);
     },
-    ownKeys(target) {
-      if ("$ref" in target && typeof target.$ref === "string" && isLocalRef(target.$ref)) {
-        const referencePath = parseJsonPointer(target["$ref"]);
-        const resolvedValue = getValueByPath(sourceDocument, referencePath);
-        return resolvedValue ? Reflect.ownKeys(resolvedValue) : [];
+    /**
+     * Proxy "ownKeys" trap for magic proxy.
+     * - Returns the list of own property keys for the proxied object.
+     * - 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.
+     */
+    ownKeys(target2) {
+      const keys = Reflect.ownKeys(target2);
+      if (REF_KEY in target2 && !keys.includes(REF_VALUE)) {
+        keys.push(REF_VALUE);
       }
-      return Reflect.ownKeys(target);
+      return keys;
     },
-    getOwnPropertyDescriptor(target, key) {
-      if ("$ref" in target && key !== "$ref" && typeof target.$ref === "string" && isLocalRef(target.$ref)) {
-        const referencePath = parseJsonPointer(target["$ref"]);
-        const resolvedValue = getValueByPath(sourceDocument, referencePath);
-        if (resolvedValue) {
-          return Object.getOwnPropertyDescriptor(resolvedValue, key);
-        }
+    /**
+     * Proxy "getOwnPropertyDescriptor" trap for magic proxy.
+     * - For the virtual "$ref-value" property, returns a descriptor that makes it appear as a regular property.
+     * - 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) {
+      const ref = Reflect.get(target2, REF_KEY);
+      if (prop === REF_VALUE && typeof ref === "string") {
+        return {
+          configurable: true,
+          enumerable: true,
+          value: void 0,
+          writable: false
+        };
       }
-      return Object.getOwnPropertyDescriptor(target, key);
+      return Reflect.getOwnPropertyDescriptor(target2, prop);
     }
   };
-}
-function createMagicProxy(targetObject, sourceDocument = targetObject, resolvedProxyCache) {
-  if (!isObject(targetObject) && !Array.isArray(targetObject)) {
-    return targetObject;
-  }
-  const rawTarget = isReactive(targetObject) ? toRaw(targetObject) : targetObject;
-  if (resolvedProxyCache?.has(rawTarget)) {
-    const cachedValue = resolvedProxyCache.get(rawTarget);
-    if (cachedValue) {
-      return cachedValue;
-    }
-  }
-  const handler = createProxyHandler(sourceDocument, resolvedProxyCache);
-  const proxy = new Proxy(rawTarget, handler);
-  if (resolvedProxyCache) {
-    resolvedProxyCache.set(rawTarget, proxy);
-  }
-  return proxy;
-}
-const TARGET_SYMBOL = Symbol("magicProxyTarget");
+  return new Proxy(target, handler);
+};
 function getRaw(obj) {
+  if (typeof obj !== "object" || obj === null) {
+    return obj;
+  }
   if (obj[isMagicProxy]) {
-    return obj[TARGET_SYMBOL];
+    return obj[magicProxyTarget];
   }
   return obj;
 }
 export {
-  TARGET_SYMBOL,
   createMagicProxy,
   getRaw
 };

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/magic-proxy/proxy.ts"],
-  "sourcesContent": ["import { isReactive, toRaw } from 'vue'\nimport { isLocalRef } from '@/bundle/bundle'\nimport type { UnknownObject } from '@/types'\nimport { isObject } from '@/utils/is-object'\nimport { getValueByPath, parseJsonPointer } from '@/utils/json-path-utils'\n\nconst isMagicProxy = Symbol('isMagicProxy')\n\n/**\n * Creates a proxy handler that automatically resolves JSON references ($ref) in an object.\n * The handler intercepts property access, assignment, and property enumeration to automatically\n * resolve any $ref references to their target values in the source document.\n *\n * @param sourceDocument - The source document containing the reference targets\n * @param resolvedProxyCache - Optional cache to store resolved proxies and prevent duplicate proxies\n * @returns A proxy handler that automatically resolves $ref references\n */\nfunction createProxyHandler(\n  sourceDocument: UnknownObject | UnknownObject[],\n  resolvedProxyCache?: WeakMap<object, UnknownObject | UnknownObject[]>,\n): ProxyHandler<UnknownObject | UnknownObject[]> {\n  return {\n    get(target, property, receiver) {\n      if (property === TARGET_SYMBOL) {\n        return target\n      }\n\n      if (property === isMagicProxy) {\n        return true\n      }\n\n      const value = Reflect.get(target, property, receiver)\n\n      /**\n       * Recursively resolves nested references in an object.\n       * If the value is not an object, returns it as is.\n       * If the value has a $ref property:\n       *   - For local references: resolves the reference and continues resolving nested refs\n       *   - For all other objects: creates a proxy for lazy resolution\n       */\n      const deepResolveNestedRefs = (value: unknown, originalRef?: string) => {\n        if (!isObject(value) && !Array.isArray(value)) {\n          return value\n        }\n\n        if (typeof value === 'object' && '$ref' in value) {\n          const ref = value.$ref as string\n\n          if (isLocalRef(ref)) {\n            const referencePath = parseJsonPointer(ref)\n            const resolvedValue = getValueByPath(sourceDocument, referencePath)\n\n            // preserve the first $ref to maintain the original reference\n            return deepResolveNestedRefs(resolvedValue, originalRef ?? ref)\n          }\n        }\n\n        if (originalRef && typeof value === 'object') {\n          return createMagicProxy({ ...value, 'x-original-ref': originalRef }, sourceDocument, resolvedProxyCache)\n        }\n\n        return createMagicProxy(value as UnknownObject, sourceDocument, resolvedProxyCache)\n      }\n\n      return deepResolveNestedRefs(value)\n    },\n\n    set(target: UnknownObject, property: string, newValue: unknown, receiver: UnknownObject) {\n      const rawTarget = isReactive(target) ? toRaw(target) : target\n      const currentValue = rawTarget[property]\n\n      if (\n        typeof currentValue === 'object' &&\n        isObject(currentValue) &&\n        '$ref' in currentValue &&\n        typeof currentValue.$ref === 'string' &&\n        isLocalRef(currentValue.$ref)\n      ) {\n        const referencePath = parseJsonPointer(currentValue.$ref)\n        const targetObject = getValueByPath(sourceDocument, referencePath.slice(0, -1)) as UnknownObject\n        const lastPathSegment = referencePath[referencePath.length - 1]\n\n        if (targetObject && lastPathSegment) {\n          targetObject[lastPathSegment] = newValue\n        }\n      } else {\n        Reflect.set(rawTarget, property, newValue, receiver)\n      }\n      return true\n    },\n\n    has(target: UnknownObject, key: string) {\n      if (typeof key === 'string' && key !== '$ref' && typeof target.$ref === 'string' && isLocalRef(target.$ref)) {\n        const referencePath = parseJsonPointer(target['$ref'])\n        const resolvedValue = getValueByPath(sourceDocument, referencePath) as UnknownObject\n\n        return resolvedValue ? key in resolvedValue : false\n      }\n\n      return key in target\n    },\n\n    ownKeys(target: UnknownObject) {\n      if ('$ref' in target && typeof target.$ref === 'string' && isLocalRef(target.$ref)) {\n        const referencePath = parseJsonPointer(target['$ref'])\n        const resolvedValue = getValueByPath<UnknownObject>(sourceDocument, referencePath)\n\n        return resolvedValue ? Reflect.ownKeys(resolvedValue) : []\n      }\n\n      return Reflect.ownKeys(target)\n    },\n\n    getOwnPropertyDescriptor(target: UnknownObject, key: string) {\n      if ('$ref' in target && key !== '$ref' && typeof target.$ref === 'string' && isLocalRef(target.$ref)) {\n        const referencePath = parseJsonPointer(target['$ref'])\n        const resolvedValue = getValueByPath(sourceDocument, referencePath)\n\n        if (resolvedValue) {\n          return Object.getOwnPropertyDescriptor(resolvedValue, key)\n        }\n      }\n\n      return Object.getOwnPropertyDescriptor(target, key)\n    },\n  }\n}\n\n/**\n * Creates a proxy that automatically resolves JSON references ($ref) in an object.\n * The proxy intercepts property access and automatically resolves any $ref references\n * to their target values in the source document.\n *\n * @param targetObject - The object to create a proxy for\n * @param sourceDocument - The source document containing the reference targets (defaults to targetObject)\n * @param resolvedProxyCache - Optional cache to store resolved proxies and prevent duplicate proxies\n * @returns A proxy that automatically resolves $ref references\n *\n * @example\n * // Basic usage with local references\n * const doc = {\n *   components: {\n *     schemas: {\n *       User: { type: 'object', properties: { name: { type: 'string' } } }\n *     }\n *   },\n *   paths: {\n *     '/users': {\n *       get: {\n *         responses: {\n *           200: {\n *             content: {\n *               'application/json': {\n *                 schema: { $ref: '#/components/schemas/User' }\n *               }\n *             }\n *           }\n *         }\n *       }\n *     }\n *   }\n * }\n *\n * const proxy = createMagicProxy(doc)\n * // Accessing the schema will automatically resolve the $ref\n * console.log(proxy.paths['/users'].get.responses[200].content['application/json'].schema)\n * // Output: { type: 'object', properties: { name: { type: 'string' } } }\n *\n * @example\n * // Using with a cache to prevent duplicate proxies\n * const cache = new WeakMap()\n * const proxy1 = createMagicProxy(doc, doc, cache)\n * const proxy2 = createMagicProxy(doc, doc, cache)\n * // proxy1 and proxy2 are the same instance due to caching\n * console.log(proxy1 === proxy2) // true\n */\nexport function createMagicProxy<T extends UnknownObject | UnknownObject[]>(\n  targetObject: T,\n  sourceDocument: T = targetObject,\n  resolvedProxyCache?: WeakMap<object, T>,\n): T {\n  if (!isObject(targetObject) && !Array.isArray(targetObject)) {\n    return targetObject\n  }\n\n  const rawTarget = isReactive(targetObject) ? toRaw(targetObject) : targetObject\n\n  // check for cached results\n  if (resolvedProxyCache?.has(rawTarget)) {\n    const cachedValue = resolvedProxyCache.get(rawTarget)\n\n    if (cachedValue) {\n      return cachedValue\n    }\n  }\n\n  // Create a handler with the correct context\n  const handler = createProxyHandler(sourceDocument, resolvedProxyCache)\n  const proxy = new Proxy<T>(rawTarget, handler)\n\n  if (resolvedProxyCache) {\n    resolvedProxyCache.set(rawTarget, proxy)\n  }\n\n  return proxy\n}\n\nexport const TARGET_SYMBOL = Symbol('magicProxyTarget')\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 extends UnknownObject>(obj: T): T {\n  if ((obj as T & { [isMagicProxy]: boolean | undefined })[isMagicProxy]) {\n    return (obj as T & { [TARGET_SYMBOL]: T })[TARGET_SYMBOL]\n  }\n\n  return obj\n}\n"],
-  "mappings": "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",
-  "names": ["value"]
+  "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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",
+  "names": ["target"]
 }

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

@@ -1,5 +1,5 @@
 /**
  * Check if the given value is an object
  */
-export declare const isObject: (obj: any) => boolean;
+export declare const isObject: (obj: any) => obj is object;
 //# sourceMappingURL=is-object.d.ts.map

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,YAAmE,CAAA"}
+{"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"}

package/dist/utils/is-object.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/utils/is-object.ts"],
-  "sourcesContent": ["/**\n * Check if the given value is an object\n */\nexport const isObject = (obj: any) => typeof obj === 'object' && !Array.isArray(obj) && obj !== null\n"],
-  "mappings": "AAGO,MAAM,WAAW,CAAC,QAAa,OAAO,QAAQ,YAAY,CAAC,MAAM,QAAQ,GAAG,KAAK,QAAQ;",
+  "sourcesContent": ["/**\n * Check if the given value is an object\n */\nexport const isObject = (obj: any): obj is object => typeof obj === 'object' && !Array.isArray(obj) && obj !== null\n"],
+  "mappings": "AAGO,MAAM,WAAW,CAAC,QAA4B,OAAO,QAAQ,YAAY,CAAC,MAAM,QAAQ,GAAG,KAAK,QAAQ;",
   "names": []
 }

package/package.json

@@ -10,20 +10,11 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.1.0",
+  "version": "0.3.0",
   "engines": {
     "node": ">=20"
   },
   "type": "module",
-  "dependencies": {
-    "yaml": "2.8.0",
-    "vue": "^3.5.17"
-  },
-  "devDependencies": {
-    "vite": "6.1.6",
-    "fastify": "^5.3.3",
-    "@scalar/build-tooling": "0.2.4"
-  },
   "exports": {
     "./bundle": {
       "import": "./dist/bundle/index.js",
@@ -56,6 +47,16 @@
       "default": "./dist/magic-proxy/index.js"
     }
   },
+  "dependencies": {
+    "vue": "^3.5.17",
+    "yaml": "2.8.0",
+    "@scalar/helpers": "0.0.8"
+  },
+  "devDependencies": {
+    "fastify": "^5.3.3",
+    "vite": "6.1.6",
+    "@scalar/build-tooling": "0.2.6"
+  },
   "scripts": {
     "build": "scalar-build-esbuild",
     "test": "vitest test",