@scalar/workspace-store 0.40.2 → 0.40.4

package/dist/helpers/overrides-proxy.js

@@ -1,63 +1,103 @@
-import { isObject } from "@scalar/helpers/object/is-object";
-const isOverridesProxy = Symbol("isOverridesProxy");
-const getOverridesTarget = Symbol("getOverridesTarget");
-const createOverridesProxy = (target, options, args = {
-  cache: /* @__PURE__ */ new WeakMap()
+import { isObject } from '@scalar/helpers/object/is-object';
+const isOverridesProxy = Symbol('isOverridesProxy');
+export const getOverridesTarget = Symbol('getOverridesTarget');
+/**
+ * Creates a proxy object that overlays "overrides" on top of a target object.
+ *
+ * - When reading a property, if an override exists, it is returned; otherwise, the original value is returned.
+ * - When writing to a property, if an override exists, it is updated; otherwise, the original object is updated.
+ * - This works recursively for nested objects, so overrides can be deeply partial.
+ * - Special symbols are used to identify the proxy and to access the original target.
+ *
+ * @template T - The type of the target object.
+ * @param target - The original object to proxy.
+ * @param overrides - An optional object containing override values (deeply partial).
+ * @returns A proxy object that reflects overrides on top of the target.
+ *
+ * @example
+ * const original = { a: 1, b: { c: 2 } }
+ * const overrides = { b: { c: 42 } }
+ * const proxy = createOverridesProxy(original, { overrides })
+ *
+ * console.log(proxy.a) // 1 (from original)
+ * console.log(proxy.b.c) // 42 (from overrides)
+ *
+ * proxy.a = 100
+ * console.log(original.a) // 100
+ *
+ * proxy.b.c = 99
+ * console.log(overrides.b.c) // 99
+ */
+export const createOverridesProxy = (target, options, args = {
+    cache: new WeakMap(),
 }) => {
-  if (!target || typeof target !== "object") {
-    return target;
-  }
-  if (args.cache.has(target)) {
-    return args.cache.get(target);
-  }
-  const { overrides } = options ?? {};
-  const handler = {
-    get(target2, prop, receiver) {
-      if (prop === isOverridesProxy) {
-        return true;
-      }
-      if (prop === getOverridesTarget) {
-        return target2;
-      }
-      const value = Reflect.get(target2, prop, receiver);
-      if (isOverridesProxyObject(value)) {
-        return value;
-      }
-      if (!isObject(value)) {
-        return Reflect.get(overrides ?? {}, prop) ?? value;
-      }
-      return createOverridesProxy(value, { overrides: Reflect.get(overrides ?? {}, prop) }, args);
-    },
-    set(target2, prop, value, receiver) {
-      if (prop === isOverridesProxy || prop === getOverridesTarget) {
-        return false;
-      }
-      const hasOverride = overrides && Reflect.has(overrides, prop);
-      if (hasOverride && overrides && typeof overrides === "object") {
-        ;
-        overrides[prop] = value;
-        return true;
-      }
-      return Reflect.set(target2, prop, value, receiver);
+    if (!target || typeof target !== 'object') {
+        return target;
     }
-  };
-  const proxy = new Proxy(target, handler);
-  args.cache.set(target, proxy);
-  return proxy;
+    // Return existing proxy for the same target to ensure referential stability
+    if (args.cache.has(target)) {
+        return args.cache.get(target);
+    }
+    const { overrides } = options ?? {};
+    // Proxy handler to intercept get/set operations
+    const handler = {
+        get(target, prop, receiver) {
+            // Special symbol to identify this as an overrides proxy
+            if (prop === isOverridesProxy) {
+                return true;
+            }
+            // Special symbol to access the original target object
+            if (prop === getOverridesTarget) {
+                return target;
+            }
+            const value = Reflect.get(target, prop, receiver);
+            // Return early if the value is already an overrides proxy
+            if (isOverridesProxyObject(value)) {
+                return value;
+            }
+            // If the value is not an object, return the override if it exists, else the original value
+            if (!isObject(value)) {
+                return Reflect.get(overrides ?? {}, prop) ?? value;
+            }
+            // For nested objects, recursively create a proxy with the corresponding overrides
+            return createOverridesProxy(value, { overrides: Reflect.get(overrides ?? {}, prop) }, args);
+        },
+        set(target, prop, value, receiver) {
+            // Prevent setting special symbols
+            if (prop === isOverridesProxy || prop === getOverridesTarget) {
+                return false;
+            }
+            // If an override exists for this property, update it
+            const hasOverride = overrides && Reflect.has(overrides, prop);
+            if (hasOverride && overrides && typeof overrides === 'object') {
+                ;
+                overrides[prop] = value;
+                return true;
+            }
+            // Otherwise, update the original target
+            return Reflect.set(target, prop, value, receiver);
+        },
+    };
+    // Return the proxy object
+    const proxy = new Proxy(target, handler);
+    args.cache.set(target, proxy);
+    return proxy;
 };
-const isOverridesProxyObject = (obj) => {
-  return typeof obj === "object" && obj !== null && obj[isOverridesProxy] === true;
+export const isOverridesProxyObject = (obj) => {
+    return typeof obj === 'object' && obj !== null && obj[isOverridesProxy] === true;
 };
-function unpackOverridesProxy(input) {
-  if (typeof input === "object" && input !== null && input[isOverridesProxy]) {
-    return input[getOverridesTarget];
-  }
-  return input;
+/**
+ * Unpacks an object from the overrides proxy, returning the original (unproxied) target object.
+ * If the input is not an overrides proxy, returns the object as-is.
+ *
+ * @param input - The potentially proxied object
+ * @returns The original unproxied target object or the input object
+ */
+export function unpackOverridesProxy(input) {
+    if (typeof input === 'object' &&
+        input !== null &&
+        input[isOverridesProxy]) {
+        return input[getOverridesTarget];
+    }
+    return input;
 }
-export {
-  createOverridesProxy,
-  getOverridesTarget,
-  isOverridesProxyObject,
-  unpackOverridesProxy
-};
-//# sourceMappingURL=overrides-proxy.js.map

package/dist/helpers/unpack-proxy.js

@@ -1,59 +1,61 @@
-import { getRaw } from "@scalar/json-magic/magic-proxy";
-import { toRaw } from "vue";
-import { unpackDetectChangesProxy } from "../helpers/detect-changes-proxy.js";
-import { unpackOverridesProxy } from "../helpers/overrides-proxy.js";
-const unpackProxyObject = (input, { depth = 0 } = {}) => {
-  const dfs = (value, currentDepth = 0) => {
-    if (typeof value !== "object" || value === null) {
-      return value;
-    }
-    const raw = unpackDetectChangesProxy(toRaw(getRaw(unpackOverridesProxy(value))));
-    if (depth !== null && currentDepth >= depth) {
-      return raw;
-    }
-    if (currentDepth !== 0 && raw !== value) {
-      console.warn(
-        "%c\u26A0 Warning:%c You tried to assign a proxied object (depth: %d).\n%c\u{1F4A1} Tip:%c Pass a plain object instead \u2014 wrapping a proxy inside another proxy may cause weird bugs.\n%c\u{1F50D} Debug Info:%c The problematic value is shown below:",
-        // styles
-        "background: #fdd835; color: #000; font-weight: bold; padding: 2px 4px; border-radius: 3px;",
-        "color: inherit;",
-        currentDepth,
-        "color: #00bfa5; font-weight: bold;",
-        "color: inherit;",
-        "color: #03a9f4; font-weight: bold;",
-        "color: inherit;",
-        value,
-        input
-      );
-      console.groupCollapsed("%c\u{1F4DC} Proxy assignment trace", "color: #9c27b0; font-weight: bold;");
-      console.trace({ value, raw });
-      console.groupEnd();
-    }
-    Object.entries(raw).forEach(([key, value2]) => {
-      const propertyResult = dfs(value2, currentDepth + 1);
-      const result = Reflect.set(raw, key, propertyResult);
-      if (!result) {
-        console.warn(
-          '%c\u{1F6AB} Readonly Property Error:%c Failed to set property "%s" on object.\n%c\u{1F4A1} Tip:%c This property is readonly or non-configurable. You cannot unpack a readonly property \u2014 the value was not updated.\n%c\u{1F50D} Debug Info:%c Property: %s | Value: %o | Object: %o',
-          // styles
-          "background: #f44336; color: #fff; font-weight: bold; padding: 2px 4px; border-radius: 3px;",
-          "color: inherit;",
-          key,
-          "color: #00bfa5; font-weight: bold;",
-          "color: inherit;",
-          "color: #03a9f4; font-weight: bold;",
-          "color: inherit;",
-          key,
-          propertyResult,
-          raw
-        );
-      }
-    });
-    return raw;
-  };
-  return dfs(input);
+import { getRaw } from '@scalar/json-magic/magic-proxy';
+import { toRaw } from 'vue';
+import { unpackDetectChangesProxy } from '../helpers/detect-changes-proxy.js';
+import { unpackOverridesProxy } from '../helpers/overrides-proxy.js';
+/**
+ * Unpacks special vue reactivity & override & detect-changes & magic proxy from an input object or array,
+ * returning the "raw" plain object or array.
+ *
+ * This function recursively traverses the input object or array, removing any proxies
+ * (e.g. Vue reactivity proxies, magic proxies, override proxies, detect-changes proxies)
+ * to obtain and return the underlying "raw" plain object or array.
+ *
+ * The recursion is controlled by the `depth` parameter. If `depth` is `null`, unlimited depth is allowed.
+ * If a proxied object is detected and unwrapped at non-root level, a warning is logged.
+ *
+ * @param input - The object or array (possibly deeply nested or proxied) to recursively unwrap.
+ * @param depth - Optional, limits recursion depth. `null` means unlimited depth (default is 1).
+ * @returns - A plain object or array with all proxies removed up to the specified depth.
+ */
+export const unpackProxyObject = (input, { depth = 0 } = {}) => {
+    // Internal DFS helper to recursively strip all known proxies (Vue, overrides, detect-changes, magic proxies)
+    const dfs = (value, currentDepth = 0) => {
+        // Base case: non-objects (primitives, null) are returned as-is
+        if (typeof value !== 'object' || value === null) {
+            return value;
+        }
+        // Compose all the proxy unwraps in order
+        const raw = unpackDetectChangesProxy(toRaw(getRaw(unpackOverridesProxy(value))));
+        // If we have reached the maximum depth, return the value (potentially still partially proxied)
+        if (depth !== null && currentDepth >= depth) {
+            return raw;
+        }
+        // Show a warning if a nested value was a proxy (usually undesired, can cause subtle bugs)
+        if (currentDepth !== 0 && raw !== value) {
+            console.warn('%c⚠ Warning:%c You tried to assign a proxied object (depth: %d).\n' +
+                '%c💡 Tip:%c Pass a plain object instead — wrapping a proxy inside another proxy may cause weird bugs.\n' +
+                '%c🔍 Debug Info:%c The problematic value is shown below:', 
+            // styles
+            'background: #fdd835; color: #000; font-weight: bold; padding: 2px 4px; border-radius: 3px;', 'color: inherit;', currentDepth, 'color: #00bfa5; font-weight: bold;', 'color: inherit;', 'color: #03a9f4; font-weight: bold;', 'color: inherit;', value, input);
+            // Collapsed trace group for cleaner output
+            console.groupCollapsed('%c📜 Proxy assignment trace', 'color: #9c27b0; font-weight: bold;');
+            console.trace({ value, raw });
+            console.groupEnd();
+        }
+        // Recursively process all properties/entries to make sure we are not assigning proxies directly,
+        // but are always assigning plain objects at any level.
+        Object.entries(raw).forEach(([key, value]) => {
+            const propertyResult = dfs(value, currentDepth + 1);
+            const result = Reflect.set(raw, key, propertyResult);
+            if (!result) {
+                console.warn('%c🚫 Readonly Property Error:%c Failed to set property "%s" on object.\n' +
+                    '%c💡 Tip:%c This property is readonly or non-configurable. You cannot unpack a readonly property — the value was not updated.\n' +
+                    '%c🔍 Debug Info:%c Property: %s | Value: %o | Object: %o', 
+                // styles
+                'background: #f44336; color: #fff; font-weight: bold; padding: 2px 4px; border-radius: 3px;', 'color: inherit;', key, 'color: #00bfa5; font-weight: bold;', 'color: inherit;', 'color: #03a9f4; font-weight: bold;', 'color: inherit;', key, propertyResult, raw);
+            }
+        });
+        return raw;
+    };
+    return dfs(input);
 };
-export {
-  unpackProxyObject
-};
-//# sourceMappingURL=unpack-proxy.js.map