@scalar/json-magic 0.4.3 → 0.5.0

package/src/magic-proxy/proxy.ts

@@ -1,8 +1,9 @@
-import { isLocalRef } from '@/bundle/bundle'
+import { convertToLocalRef } from '@/helpers/convert-to-local-ref'
+import { getId, getSchemas } from '@/helpers/get-schemas'
+import { getValueByPath } from '@/helpers/get-value-by-path'
+import { isObject } from '@/helpers/is-object'
+import { createPathFromSegments, parseJsonPointer } from '@/helpers/json-path-utils'
 import type { UnknownObject } from '@/types'
-import { getSegmentsFromPath } from '@/utils/get-segments-from-path'
-import { isObject } from '@/utils/is-object'
-import { createPathFromSegments, getValueByPath, parseJsonPointer } from '@/utils/json-path-utils'
 
 const isMagicProxy = Symbol('isMagicProxy')
 const magicProxyTarget = Symbol('magicProxyTarget')
@@ -14,16 +15,16 @@ const REF_KEY = '$ref'
  * Creates a "magic" proxy for a given object or array, enabling transparent access to
  * JSON Reference ($ref) values as if they were directly present on the object.
  *
- * - 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 hidden and will not be accessible through
- *   the proxy (returns undefined on access, false on 'in' checks, excluded from enumeration).
+ * 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.
  * - Setting, deleting, and enumerating properties works as expected, including for proxied references.
+ * - Ensures referential stability by caching proxies for the same target object.
  *
  * @param target - The object or array to wrap in a magic proxy
- * @param root - The root object for resolving local JSON references (defaults to target)
+ * @param options - Optional settings (e.g., showInternal to expose internal properties)
+ * @param args - Internal arguments for advanced usage (root object, proxy/cache maps, current context)
  * @returns A proxied version of the input object/array with magic $ref-value support
  *
  * @example
@@ -50,18 +51,47 @@ const REF_KEY = '$ref'
  */
 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>(),
+  options?: Partial<{ showInternal: boolean }>,
+  args: {
+    /**
+     * The root object for resolving local JSON references.
+     */
+    root: S | T
+    /**
+     * Cache to store already created proxies for target objects to ensure referential stability.
+     *
+     * It is helpful when dealing with reactive frameworks like Vue,
+     */
+    proxyCache: WeakMap<object, T>
+    /**
+     * Cache to store resolved JSON references.
+     */
+    cache: Map<string, unknown>
+    /**
+     * Map of all schemas by their $id or $anchor for cross-document reference resolution.
+     */
+    schemas: Map<string, string>
+    /**
+     * The current JSON path context within the root object.
+     *
+     * Used to resolve $anchor references correctly.
+     */
+    currentContext: string
+  } = {
+    root: target,
+    proxyCache: new WeakMap(),
+    cache: new Map(),
+    schemas: getSchemas(target),
+    currentContext: '',
+  },
 ) => {
   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)
+  if (args.proxyCache.has(target)) {
+    return args.proxyCache.get(target)
   }
 
   const handler: ProxyHandler<T> = {
@@ -84,33 +114,45 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
         return target
       }
 
-      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
       }
 
+      // Get the $ref value of the current target (if any)
+      const ref = Reflect.get(target, REF_KEY, receiver)
+      // Get the identifier ($id) of the current target for context tracking
+      const id = getId(target)
+
       // 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)) {
+      if (prop === REF_VALUE && typeof ref === 'string') {
         // Check cache first for performance optimization
-        if (cache.has(ref)) {
-          return cache.get(ref)
+        if (args.cache.has(ref)) {
+          return args.cache.get(ref)
+        }
+
+        const path = convertToLocalRef(ref, id ?? args.currentContext, args.schemas)
+
+        if (path === undefined) {
+          return undefined
         }
 
         // Resolve the reference and create a new magic proxy
-        const resolvedValue = getValueByPath(root, parseJsonPointer(ref))
-        const proxiedValue = createMagicProxy(resolvedValue, options, root, cache)
+        const resolvedValue = getValueByPath(args.root, parseJsonPointer(`#/${path}`))
+        const proxiedValue = createMagicProxy(resolvedValue.value, options, {
+          ...args,
+          currentContext: resolvedValue.context,
+        })
 
         // Store in cache for future lookups
-        cache.set(ref, proxiedValue)
+        args.cache.set(ref, proxiedValue)
         return proxiedValue
       }
 
       // For all other properties, recursively wrap the value in a magic proxy
       const value = Reflect.get(target, prop, receiver)
-      return createMagicProxy(value as T, options, root, cache, proxyCache)
+      return createMagicProxy(value as T, options, { ...args, currentContext: id ?? args.currentContext })
     },
     /**
      * Proxy "set" trap for magic proxy.
@@ -127,18 +169,25 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
         return true
       }
 
-      if (prop === REF_VALUE && typeof ref === 'string' && isLocalRef(ref)) {
-        const segments = getSegmentsFromPath(ref)
+      if (prop === REF_VALUE && typeof ref === 'string') {
+        const id = getId(target)
+        const path = convertToLocalRef(ref, id ?? args.currentContext, args.schemas)
+
+        if (path === undefined) {
+          return undefined
+        }
+
+        const segments = parseJsonPointer(`#/${path}`)
 
         if (segments.length === 0) {
           return false // Can not set top level $ref-value
         }
 
         // Get the parent node or create it if it does not exist
-        const getParentNode = () => getValueByPath(root, segments.slice(0, -1))
+        const getParentNode = () => getValueByPath(args.root, segments.slice(0, -1)).value
 
         if (getParentNode() === undefined) {
-          createPathFromSegments(root, segments.slice(0, -1))
+          createPathFromSegments(args.root, segments.slice(0, -1))
 
           // In this case the ref is pointing to an invalid path, so we warn the user
           console.warn(
@@ -233,7 +282,7 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
   }
 
   const proxied = new Proxy<T>(target, handler)
-  proxyCache.set(target, proxied)
+  args.proxyCache.set(target, proxied)
   return proxied
 }
 

package/dist/utils/escape-json-pointer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"escape-json-pointer.d.ts","sourceRoot":"","sources":["../../src/utils/escape-json-pointer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,UAE5C"}

package/dist/utils/get-segments-from-path.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"get-segments-from-path.d.ts","sourceRoot":"","sources":["../../src/utils/get-segments-from-path.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,YAW/C"}

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

@@ -1 +0,0 @@
-{"version":3,"file":"is-json-object.d.ts","sourceRoot":"","sources":["../../src/utils/is-json-object.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,WAYzC"}

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

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/utils/is-json-object.ts"],
-  "sourcesContent": ["import { isObject } from '@/utils/is-object'\n\n/**\n * Determines if a string represents a valid JSON object (i.e., a plain object, not an array, primitive, or null).\n * The function first checks if the string appears to start with an opening curly brace (ignoring leading whitespace),\n * which is a quick heuristic to rule out arrays, primitives, and most invalid JSON. If this check passes,\n * it attempts to parse the string with JSON.parse. The result is then checked to ensure it is a plain object\n * (not an array, null, or primitive) using the isObject utility.\n *\n * @param value - The string to evaluate\n * @returns true if the string is valid JSON and parses to a plain object, false otherwise\n *\n * @example\n * isJsonObject('{\"foo\": \"bar\"}') // true\n * isJsonObject('[1,2,3]') // false\n * isJsonObject('not json') // false\n * isJsonObject('42') // false\n */\nexport function isJsonObject(value: string) {\n  // Quickly rule out anything that doesn't start with an object brace\n  if (!/^\\s*(\\{)/.test(value.slice(0, 500))) {\n    return false\n  }\n\n  try {\n    const val = JSON.parse(value)\n    return isObject(val)\n  } catch {\n    return false\n  }\n}\n"],
-  "mappings": "AAAA,SAAS,gBAAgB;AAkBlB,SAAS,aAAa,OAAe;AAE1C,MAAI,CAAC,WAAW,KAAK,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG;AACzC,WAAO;AAAA,EACT;AAEA,MAAI;AACF,UAAM,MAAM,KAAK,MAAM,KAAK;AAC5B,WAAO,SAAS,GAAG;AAAA,EACrB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;",
-  "names": []
-}

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

@@ -1 +0,0 @@
-{"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/dist/utils/is-yaml.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-yaml.d.ts","sourceRoot":"","sources":["../../src/utils/is-yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE7C"}

package/dist/utils/json-path-utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"json-path-utils.d.ts","sourceRoot":"","sources":["../../src/utils/json-path-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAO1E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAWlE"}

package/dist/utils/json-path-utils.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/utils/json-path-utils.ts"],
-  "sourcesContent": ["/**\n * Parses a JSON Pointer string into an array of path segments\n *\n * @example\n * ```ts\n * parseJsonPointer('#/components/schemas/User')\n *\n * ['components', 'schemas', 'User']\n * ```\n */\nexport function parseJsonPointer(pointer: string): string[] {\n  return (\n    pointer\n      // Split on '/'\n      .split('/')\n      // Remove the leading '#' if present\n      .filter((segment, index) => (index !== 0 || segment !== '#') && segment)\n  )\n}\n\n/**\n * Retrieves a nested value from the source document using a path array\n *\n * @example\n * ```ts\n * getValueByPath(document, ['components', 'schemas', 'User'])\n *\n * { id: '123', name: 'John Doe' }\n * ```\n */\nexport function getValueByPath<R = unknown>(obj: any, pointer: string[]): R {\n  return pointer.reduce((acc, part) => {\n    if (acc === undefined || acc === null) {\n      return undefined\n    }\n    return acc[part]\n  }, obj)\n}\n\n/**\n * Creates a nested path in an object from an array of path segments.\n * Only creates intermediate objects/arrays if they don't already exist.\n *\n * @param obj - The target object to create the path in\n * @param segments - Array of path segments to create\n * @returns The final nested object/array at the end of the path\n *\n * @example\n * ```ts\n * const obj = {}\n * createPathFromSegments(obj, ['components', 'schemas', 'User'])\n * // Creates: { components: { schemas: { User: {} } } }\n *\n * createPathFromSegments(obj, ['items', '0', 'name'])\n * // Creates: { items: [{ name: {} }] }\n * ```\n */\nexport function createPathFromSegments(obj: any, segments: string[]) {\n  return segments.reduce((acc, part) => {\n    if (acc[part] === undefined) {\n      if (isNaN(Number(part))) {\n        acc[part] = {}\n      } else {\n        acc[part] = []\n      }\n    }\n    return acc[part]\n  }, obj)\n}\n"],
-  "mappings": "AAUO,SAAS,iBAAiB,SAA2B;AAC1D,SACE,QAEG,MAAM,GAAG,EAET,OAAO,CAAC,SAAS,WAAW,UAAU,KAAK,YAAY,QAAQ,OAAO;AAE7E;AAYO,SAAS,eAA4B,KAAU,SAAsB;AAC1E,SAAO,QAAQ,OAAO,CAAC,KAAK,SAAS;AACnC,QAAI,QAAQ,UAAa,QAAQ,MAAM;AACrC,aAAO;AAAA,IACT;AACA,WAAO,IAAI,IAAI;AAAA,EACjB,GAAG,GAAG;AACR;AAoBO,SAAS,uBAAuB,KAAU,UAAoB;AACnE,SAAO,SAAS,OAAO,CAAC,KAAK,SAAS;AACpC,QAAI,IAAI,IAAI,MAAM,QAAW;AAC3B,UAAI,MAAM,OAAO,IAAI,CAAC,GAAG;AACvB,YAAI,IAAI,IAAI,CAAC;AAAA,MACf,OAAO;AACL,YAAI,IAAI,IAAI,CAAC;AAAA,MACf;AAAA,IACF;AACA,WAAO,IAAI,IAAI;AAAA,EACjB,GAAG,GAAG;AACR;",
-  "names": []
-}

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

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

package/dist/utils/unescape-json-pointer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"unescape-json-pointer.d.ts","sourceRoot":"","sources":["../../src/utils/unescape-json-pointer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,UAE9C"}