@scalar/json-magic 0.4.1 → 0.4.3

package/.turbo/turbo-build.log

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

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @scalar/json-magic
 
+## 0.4.3
+
+### Patch Changes
+
+- Updated dependencies [bff46e5]
+  - @scalar/helpers@0.0.11
+
+## 0.4.2
+
+### Patch Changes
+
+- 3bd1209: fix: do not throw when we set on an invalid ref
+- 1943b99: chore: emit warning when trying to set an invalid ref
+
 ## 0.4.1
 
 ### Patch Changes

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"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,MAsLtC,CAAA;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAUnC"}

package/dist/magic-proxy/proxy.js

@@ -1,7 +1,7 @@
 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";
+import { createPathFromSegments, getValueByPath, parseJsonPointer } from "../utils/json-path-utils.js";
 const isMagicProxy = Symbol("isMagicProxy");
 const magicProxyTarget = Symbol("magicProxyTarget");
 const REF_VALUE = "$ref-value";
@@ -63,11 +63,16 @@ const createMagicProxy = (target, options, root = target, cache = /* @__PURE__ *
         if (segments.length === 0) {
           return false;
         }
-        const parentNode = getValueByPath(root, segments.slice(0, -1));
-        if (!parentNode || !isObject(parentNode) && !Array.isArray(parentNode)) {
-          return false;
+        const getParentNode = () => getValueByPath(root, segments.slice(0, -1));
+        if (getParentNode() === void 0) {
+          createPathFromSegments(root, segments.slice(0, -1));
+          console.warn(
+            `Trying to set $ref-value for invalid reference: ${ref}
+
+Please fix your input file to fix this issue.`
+          );
         }
-        parentNode[segments.at(-1)] = newValue;
+        getParentNode()[segments.at(-1)] = newValue;
         return true;
       }
       return Reflect.set(target2, prop, newValue, receiver);

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 * - 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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",
+  "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 { createPathFromSegments, 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        // Get the parent node or create it if it does not exist\n        const getParentNode = () => getValueByPath(root, segments.slice(0, -1))\n\n        if (getParentNode() === undefined) {\n          createPathFromSegments(root, segments.slice(0, -1))\n\n          // In this case the ref is pointing to an invalid path, so we warn the user\n          console.warn(\n            `Trying to set $ref-value for invalid reference: ${ref}\\n\\nPlease fix your input file to fix this issue.`,\n          )\n        }\n\n        // Set the value on the parent node\n        getParentNode()[segments.at(-1)] = newValue\n        return true\n      }\n\n      return Reflect.set(target, prop, newValue, receiver)\n    },\n    /**\n     * Proxy \"deleteProperty\" trap for magic proxy.\n     * Allows deleting properties from the proxied object.\n     * This will update the underlying target object.\n     */\n    deleteProperty(target, prop) {\n      return Reflect.deleteProperty(target, prop)\n    },\n    /**\n     * Proxy \"has\" trap for magic proxy.\n     * - Pretend that \"$ref-value\" exists if \"$ref\" exists on the target.\n     *   This allows expressions like `\"$ref-value\" in obj` to return true for objects with a $ref,\n     *   even though \"$ref-value\" is a virtual property provided by the proxy.\n     * - Hide properties starting with underscore by returning false.\n     * - For all other properties, defer to the default Reflect.has behavior.\n     */\n    has(target, prop) {\n      // Hide properties starting with underscore\n      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {\n        return false\n      }\n\n      // Pretend that \"$ref-value\" exists if \"$ref\" exists\n      if (prop === REF_VALUE && REF_KEY in target) {\n        return true\n      }\n      return Reflect.has(target, prop)\n    },\n    /**\n     * Proxy \"ownKeys\" trap for magic proxy.\n     * - Returns the list of own property keys for the proxied object.\n     * - If the object has a \"$ref\" property, ensures that \"$ref-value\" is also included in the keys,\n     *   even though \"$ref-value\" is a virtual property provided by the proxy.\n     *   This allows Object.keys, Reflect.ownKeys, etc. to include \"$ref-value\" for objects with $ref.\n     * - Filters out properties starting with underscore.\n     */\n    ownKeys(target) {\n      const keys = Reflect.ownKeys(target)\n\n      // Filter out properties starting with underscore\n      const filteredKeys = keys.filter(\n        (key) => typeof key !== 'string' || !(key.startsWith('_') && !options?.showInternal),\n      )\n\n      if (REF_KEY in target && !filteredKeys.includes(REF_VALUE)) {\n        filteredKeys.push(REF_VALUE)\n      }\n      return filteredKeys\n    },\n\n    /**\n     * Proxy \"getOwnPropertyDescriptor\" trap for magic proxy.\n     * - For the virtual \"$ref-value\" property, returns a descriptor that makes it appear as a regular property.\n     * - Hide properties starting with underscore by returning undefined.\n     * - For all other properties, delegates to the default Reflect.getOwnPropertyDescriptor behavior.\n     * - This ensures that Object.getOwnPropertyDescriptor and similar methods work correctly with the virtual property.\n     */\n    getOwnPropertyDescriptor(target, prop) {\n      // Hide properties starting with underscore\n      if (typeof prop === 'string' && prop.startsWith('_') && !options?.showInternal) {\n        return undefined\n      }\n\n      const ref = Reflect.get(target, REF_KEY)\n\n      if (prop === REF_VALUE && typeof ref === 'string') {\n        return {\n          configurable: true,\n          enumerable: true,\n          value: undefined,\n          writable: false,\n        }\n      }\n\n      // Otherwise, delegate to the default behavior\n      return Reflect.getOwnPropertyDescriptor(target, prop)\n    },\n  }\n\n  const proxied = new Proxy<T>(target, handler)\n  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/json-path-utils.d.ts

@@ -20,4 +20,23 @@ export declare function parseJsonPointer(pointer: string): string[];
  * ```
  */
 export declare function getValueByPath<R = unknown>(obj: any, pointer: string[]): R;
+/**
+ * Creates a nested path in an object from an array of path segments.
+ * Only creates intermediate objects/arrays if they don't already exist.
+ *
+ * @param obj - The target object to create the path in
+ * @param segments - Array of path segments to create
+ * @returns The final nested object/array at the end of the path
+ *
+ * @example
+ * ```ts
+ * const obj = {}
+ * createPathFromSegments(obj, ['components', 'schemas', 'User'])
+ * // Creates: { components: { schemas: { User: {} } } }
+ *
+ * createPathFromSegments(obj, ['items', '0', 'name'])
+ * // Creates: { items: [{ name: {} }] }
+ * ```
+ */
+export declare function createPathFromSegments(obj: any, segments: string[]): any;
 //# sourceMappingURL=json-path-utils.d.ts.map

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

@@ -1 +1 @@
-{"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"}
+{"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

@@ -9,7 +9,20 @@ function getValueByPath(obj, pointer) {
     return acc[part];
   }, obj);
 }
+function createPathFromSegments(obj, segments) {
+  return segments.reduce((acc, part) => {
+    if (acc[part] === void 0) {
+      if (isNaN(Number(part))) {
+        acc[part] = {};
+      } else {
+        acc[part] = [];
+      }
+    }
+    return acc[part];
+  }, obj);
+}
 export {
+  createPathFromSegments,
   getValueByPath,
   parseJsonPointer
 };

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

@@ -1,7 +1,7 @@
 {
   "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"],
-  "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;",
+  "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/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "packages/json-magic"
   },
-  "version": "0.4.1",
+  "version": "0.4.3",
   "engines": {
     "node": ">=20"
   },
@@ -50,11 +50,11 @@
   "dependencies": {
     "vue": "^3.5.17",
     "yaml": "2.8.0",
-    "@scalar/helpers": "0.0.10"
+    "@scalar/helpers": "0.0.11"
   },
   "devDependencies": {
     "fastify": "^5.3.3",
-    "vite": "6.1.6",
+    "vite": "7.1.5",
     "@scalar/build-tooling": "0.2.7"
   },
   "scripts": {

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

@@ -386,9 +386,7 @@ describe('createMagicProxy', () => {
       }).toThrowError("'set' on proxy: trap returned falsish for property '$ref-value'")
     })
 
-    // TODO: might change this behavior in the future
-    // so we allow setting the $ref-value for invalid refs by creating the path
-    it('throws when trying to update an invalid ref where the parent node does not exists', () => {
+    it('does not throw when trying to update an invalid ref where the parent node does not exists', () => {
       const input = {
         a: {
           $ref: '#/non-existent/some-path',
@@ -404,7 +402,23 @@ describe('createMagicProxy', () => {
 
       expect(() => {
         proxied.a['$ref-value'] = 'new value'
-      }).toThrowError("'set' on proxy: trap returned falsish for property '$ref-value'")
+      }).not.toThrowError("'set' on proxy: trap returned falsish for property '$ref-value'")
+
+      expect(proxied.a['$ref-value']).toBe('new value')
+
+      expect(input).toEqual({
+        'a': {
+          '$ref': '#/non-existent/some-path',
+        },
+        'b': {
+          'c': {
+            'hello': 'world',
+          },
+        },
+        'non-existent': {
+          'some-path': 'new value',
+        },
+      })
     })
   })
 

package/src/magic-proxy/proxy.ts

@@ -2,7 +2,7 @@ import { isLocalRef } from '@/bundle/bundle'
 import type { UnknownObject } from '@/types'
 import { getSegmentsFromPath } from '@/utils/get-segments-from-path'
 import { isObject } from '@/utils/is-object'
-import { getValueByPath, parseJsonPointer } from '@/utils/json-path-utils'
+import { createPathFromSegments, getValueByPath, parseJsonPointer } from '@/utils/json-path-utils'
 
 const isMagicProxy = Symbol('isMagicProxy')
 const magicProxyTarget = Symbol('magicProxyTarget')
@@ -134,14 +134,20 @@ export const createMagicProxy = <T extends Record<keyof T & symbol, unknown>, S
           return false // Can not set top level $ref-value
         }
 
-        const parentNode = getValueByPath(root, segments.slice(0, -1))
+        // Get the parent node or create it if it does not exist
+        const getParentNode = () => getValueByPath(root, segments.slice(0, -1))
 
-        // TODO: Maybe we create the path if it does not exist?
-        // TODO: This can allow for invalid references to not throw errors
-        if (!parentNode || (!isObject(parentNode) && !Array.isArray(parentNode))) {
-          return false // Parent node does not exist, cannot set $ref-value
+        if (getParentNode() === undefined) {
+          createPathFromSegments(root, segments.slice(0, -1))
+
+          // In this case the ref is pointing to an invalid path, so we warn the user
+          console.warn(
+            `Trying to set $ref-value for invalid reference: ${ref}\n\nPlease fix your input file to fix this issue.`,
+          )
         }
-        parentNode[segments.at(-1)] = newValue
+
+        // Set the value on the parent node
+        getParentNode()[segments.at(-1)] = newValue
         return true
       }
 

package/src/utils/json-path-utils.test.ts

@@ -1,6 +1,7 @@
-import { parseJsonPointer } from './json-path-utils'
 import { describe, expect, test } from 'vitest'
 
+import { createPathFromSegments, parseJsonPointer } from './json-path-utils'
+
 describe('parseJsonPointer', () => {
   test.each([
     ['#/users/name', ['users', 'name']],
@@ -11,3 +12,46 @@ describe('parseJsonPointer', () => {
     expect(parseJsonPointer(a)).toEqual(b)
   })
 })
+
+describe('createPathFromSegments', () => {
+  test('creates nested objects for non-numeric segments', () => {
+    const obj: any = {}
+    const leaf = createPathFromSegments(obj, ['components', 'schemas', 'User'])
+
+    expect(obj).toEqual({ components: { schemas: { User: {} } } })
+    expect(leaf).toBe(obj.components.schemas.User)
+  })
+
+  test('creates arrays for numeric segments', () => {
+    const obj: any = {}
+    const arr = createPathFromSegments(obj, ['items', '0'])
+
+    expect(Array.isArray(obj.items['0'])).toBe(true)
+    expect(arr).toBe(obj.items['0'])
+  })
+
+  test('does not overwrite existing values along the path', () => {
+    const obj: any = { a: { b: { c: { existing: true } } } }
+    const leaf = createPathFromSegments(obj, ['a', 'b', 'c'])
+
+    expect(leaf).toEqual({ existing: true })
+    expect(obj.a.b.c).toEqual({ existing: true })
+  })
+
+  test('returns root object when segments array is empty', () => {
+    const obj: any = { pre: true }
+    const result = createPathFromSegments(obj, [])
+
+    expect(result).toBe(obj)
+    expect(obj).toEqual({ pre: true })
+  })
+
+  test('creates nested arrays for consecutive numeric segments', () => {
+    const obj: any = {}
+    const leaf = createPathFromSegments(obj, ['arr', '0', '1'])
+
+    expect(Array.isArray(obj.arr['0'])).toBe(true)
+    expect(Array.isArray(obj.arr['0']['1'])).toBe(true)
+    expect(leaf).toBe(obj.arr['0']['1'])
+  })
+})

package/src/utils/json-path-utils.ts

@@ -36,3 +36,34 @@ export function getValueByPath<R = unknown>(obj: any, pointer: string[]): R {
     return acc[part]
   }, obj)
 }
+
+/**
+ * Creates a nested path in an object from an array of path segments.
+ * Only creates intermediate objects/arrays if they don't already exist.
+ *
+ * @param obj - The target object to create the path in
+ * @param segments - Array of path segments to create
+ * @returns The final nested object/array at the end of the path
+ *
+ * @example
+ * ```ts
+ * const obj = {}
+ * createPathFromSegments(obj, ['components', 'schemas', 'User'])
+ * // Creates: { components: { schemas: { User: {} } } }
+ *
+ * createPathFromSegments(obj, ['items', '0', 'name'])
+ * // Creates: { items: [{ name: {} }] }
+ * ```
+ */
+export function createPathFromSegments(obj: any, segments: string[]) {
+  return segments.reduce((acc, part) => {
+    if (acc[part] === undefined) {
+      if (isNaN(Number(part))) {
+        acc[part] = {}
+      } else {
+        acc[part] = []
+      }
+    }
+    return acc[part]
+  }, obj)
+}