aberdeen 1.12.1 → 1.14.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.
  *
@@ -882,6 +896,20 @@ export declare function partition<IN_K extends string | number | symbol, OUT_K e
  * ```
  */
 export declare function dump<T>(data: T): T;
+/**
+ * When set on an object or its prototype chain, {@link dump} calls this as a render function
+ * (with the object as `this`) instead of its default recursive rendering. When `false` this
+ * inhibits `dump` from rendering object properties.
+ *
+ * @example
+ * ```typescript
+ * class Color {
+ *   constructor(public r: number, public g: number, public b: number) {}
+ *   [CUSTOM_DUMP]() { A(`#rgb(${this.r}, ${this.g}, ${this.b})`); }
+ * }
+ * ```
+ */
+export declare const CUSTOM_DUMP: unique symbol;
 /**
  * The main Aberdeen API. `A` is itself a callable function for building reactive DOM trees
  * (creating elements, setting attributes, adding content). All other Aberdeen functions and
@@ -904,6 +932,7 @@ declare const _default: typeof A & {
     /** {@inheritDoc copy} */ copy: typeof copy;
     /** {@inheritDoc count} */ count: typeof count;
     /** {@inheritDoc cssVars} */ cssVars: Record<string, string>;
+    /** {@inheritDoc CUSTOM_DUMP} */ CUSTOM_DUMP: symbol;
     /** {@inheritDoc darkMode} */ darkMode: typeof darkMode;
     /** {@inheritDoc derive} */ derive: typeof derive;
     /** {@inheritDoc disableCreateDestroy} */ disableCreateDestroy: typeof disableCreateDestroy;
@@ -916,6 +945,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] || value instanceof Date) {
     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);
@@ -1732,26 +1733,49 @@ function partition(source, func) {
   return out;
 }
 function dump(data) {
+  const org = dumpSeen;
+  dumpSeen ||= new Set;
+  try {
+    rawDump(data, dumpSeen);
+  } finally {
+    dumpSeen = org;
+  }
+  return data;
+}
+var dumpSeen;
+function rawDump(data, seen) {
   if (data && typeof data === "object") {
-    const name = data.constructor.name.toLowerCase() || "unknown object";
-    A(`#<${name}>`);
-    if (NO_COPY in data) {
-      A("# [NO_COPY]");
-    } else {
-      A("ul", () => {
-        onEach(data, (value, key) => {
-          A("li", () => {
+    const name = data.constructor.name || "unknown object";
+    if (seen.has(data)) {
+      A(`#<${name}: circular reference>`);
+      return;
+    }
+    seen.add(data);
+    const customDump = data[CUSTOM_DUMP];
+    if (customDump !== undefined) {
+      if (typeof customDump === "function")
+        customDump.call(data, seen);
+      return;
+    }
+    A(`#<${name}>`, "ul", () => {
+      onEach(data, (value, key) => {
+        A("li", () => {
+          if (!(data instanceof Array))
             A(`#${JSON.stringify(key)}: `);
-            dump(value);
-          });
+          rawDump(value, seen);
         });
       });
-    }
-  } else if (data !== undefined) {
+    });
+  } else if (data === undefined) {
+    A("#undefined");
+  } else {
     A("#" + JSON.stringify(data));
   }
-  return data;
 }
+var CUSTOM_DUMP = Symbol("CUSTOM_DUMP");
+Date.prototype[CUSTOM_DUMP] = function() {
+  A("#<Date> " + this.toISOString());
+};
 function internalError(code) {
   throw new Error(`Aberdeen internal error ${code}`);
 }
@@ -1809,6 +1833,7 @@ var aberdeen_default = Object.assign(A, {
   copy,
   count,
   cssVars,
+  CUSTOM_DUMP,
   darkMode,
   derive,
   disableCreateDestroy,
@@ -1821,6 +1846,7 @@ var aberdeen_default = Object.assign(A, {
   merge,
   mount,
   multiMap,
+  OPAQUE,
   NO_COPY,
   onEach,
   partition,
@@ -1865,11 +1891,13 @@ export {
   copy,
   clone,
   clean,
+  OPAQUE,
   NO_COPY,
   MAP_SIZE_SYMBOL,
   EMPTY,
+  CUSTOM_DUMP,
   A
 };
 
-//# debugId=C25FF24CC098C9BC64756E2164756E21
+//# debugId=34A0CA77D4CA212064756E2164756E21
 //# sourceMappingURL=aberdeen.js.map