aberdeen 1.12.1 → 1.13.0

package/dist/src/aberdeen.d.ts

@@ -237,11 +237,25 @@ export declare function copy<T extends object>(dst: T, dstKey: keyof T, src: T[t
 export declare function merge<T extends object>(dst: T, value: Partial<T>): boolean;
 export declare function merge<T extends object>(dst: T, dstKey: keyof T, value: Partial<T[typeof dstKey]>): boolean;
 /**
- * A symbol that can be added to an object to prevent it from being cloned by {@link clone} or {@link copy}.
- * This is useful for objects that should be shared by reference. That also mean that their contents won't
- * be observed for changes.
+ * A symbol that controls how Aberdeen handles an object in copy operations and proxy wrapping.
+ *
+ * The **presence** of this symbol (regardless of its value) prevents deep-copying: the object is
+ * stored and passed by reference in {@link clone} and {@link copy}.
+ *
+ * The **value** of the symbol controls proxy wrapping when the object is read from reactive state:
+ * - **Truthy** (e.g. `true`): the object is fully opaque — it is not wrapped in a proxy, so its
+ *   properties are not observable. Use this for objects that break when proxied (e.g. class instances
+ *   with internal slots, Promises) or that must be invisible to Aberdeen's reactive system.
+ * - **Falsy** (e.g. `false`): the object is still wrapped in a proxy, so reads on its properties
+ *   create reactive dependencies as normal — only deep-copying is suppressed.
+ */
+export declare const OPAQUE: unique symbol;
+/**
+ * Use {@link OPAQUE} instead. This is an alias kept for backward compatibility.
+ *
+ * @deprecated
  */
-export declare const NO_COPY: unique symbol;
+export declare const NO_COPY: symbol;
 /**
  * A reactive object containing CSS variable definitions.
  *
@@ -916,6 +930,7 @@ declare const _default: typeof A & {
     /** {@inheritDoc merge} */ merge: typeof merge;
     /** {@inheritDoc mount} */ mount: typeof mount;
     /** {@inheritDoc multiMap} */ multiMap: typeof multiMap;
+    /** {@inheritDoc OPAQUE} */ OPAQUE: symbol;
     /** {@inheritDoc NO_COPY} */ NO_COPY: symbol;
     /** {@inheritDoc onEach} */ onEach: typeof onEach;
     /** {@inheritDoc partition} */ partition: typeof partition;

package/dist/src/aberdeen.js

@@ -981,7 +981,7 @@ var setHandler = {
 };
 var proxyMap = new WeakMap;
 function optProxy(value) {
-  if (typeof value !== "object" || !value || value[TARGET_SYMBOL] !== undefined || NO_COPY in value) {
+  if (typeof value !== "object" || !value || value[TARGET_SYMBOL] !== undefined || value[OPAQUE]) {
     return value;
   }
   let proxied = proxyMap.get(value);
@@ -1083,7 +1083,7 @@ function copyRecursive(dst, src, flags) {
         changed = true;
       } else if (dstValue !== srcValue) {
         if (typeof srcValue === "object" && srcValue !== null) {
-          if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(NO_COPY in srcValue)) {
+          if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(OPAQUE in srcValue)) {
             changed = copyRecursive(dstValue, srcValue, flags) || changed;
             continue;
           }
@@ -1117,7 +1117,7 @@ function copyRecursive(dst, src, flags) {
         dstValue = EMPTY;
       if (dstValue !== srcValue) {
         if (typeof srcValue === "object" && srcValue !== null) {
-          if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(NO_COPY in srcValue)) {
+          if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(OPAQUE in srcValue)) {
             changed = copyRecursive(dstValue, srcValue, flags) || changed;
             continue;
           }
@@ -1147,7 +1147,7 @@ function copyRecursive(dst, src, flags) {
       const dstValue = dst.hasOwnProperty(key) ? dst[key] : EMPTY;
       if (dstValue !== srcValue) {
         if (typeof srcValue === "object" && srcValue !== null) {
-          if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(NO_COPY in srcValue)) {
+          if (typeof dstValue === "object" && dstValue !== null && srcValue.constructor === dstValue.constructor && !(OPAQUE in srcValue)) {
             changed = copyRecursive(dstValue, srcValue, flags) || changed;
             continue;
           }
@@ -1179,8 +1179,9 @@ function copyRecursive(dst, src, flags) {
 var MERGE = 1;
 var COPY_SUBSCRIBE = 32;
 var COPY_EMIT = 64;
-var NO_COPY = Symbol("NO_COPY");
-Promise.prototype[NO_COPY] = true;
+var OPAQUE = Symbol("OPAQUE");
+var NO_COPY = OPAQUE;
+Promise.prototype[OPAQUE] = true;
 var cssVars = optProxy({});
 function setSpacingCssVars(base = 1, unit = "rem") {
   for (let i = 0;i <= 12; i++) {
@@ -1211,7 +1212,7 @@ function darkMode() {
   return darkModeState.value;
 }
 function cloneRecursive(src, flags) {
-  if (NO_COPY in src)
+  if (OPAQUE in src)
     return src;
   if (flags & COPY_SUBSCRIBE)
     subscribe(src, ANY_SYMBOL);
@@ -1735,8 +1736,8 @@ function dump(data) {
   if (data && typeof data === "object") {
     const name = data.constructor.name.toLowerCase() || "unknown object";
     A(`#<${name}>`);
-    if (NO_COPY in data) {
-      A("# [NO_COPY]");
+    if (OPAQUE in data) {
+      A("# [OPAQUE]");
     } else {
       A("ul", () => {
         onEach(data, (value, key) => {
@@ -1821,6 +1822,7 @@ var aberdeen_default = Object.assign(A, {
   merge,
   mount,
   multiMap,
+  OPAQUE,
   NO_COPY,
   onEach,
   partition,
@@ -1865,11 +1867,12 @@ export {
   copy,
   clone,
   clean,
+  OPAQUE,
   NO_COPY,
   MAP_SIZE_SYMBOL,
   EMPTY,
   A
 };
 
-//# debugId=C25FF24CC098C9BC64756E2164756E21
+//# debugId=B5E9F155214345E564756E2164756E21
 //# sourceMappingURL=aberdeen.js.map