v1.13.0: add OPAQUE symbol, deprecate NO_COPY

Author: Frank van Viegen

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 1.13.0 (2026-05-20)
+
+**New features:**
+- Added `OPAQUE` symbol. Set to `true` to make an object fully opaque (not proxied, not deep-copied); set to `false` to suppress deep-copying while still allowing reactive observation.
+- `NO_COPY` is now a deprecated alias for `OPAQUE`.
+
 ### 1.12.1 (2026-04-24)
 
 **Fixes:**

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aberdeen",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "author": "Frank van Viegen",
   "main": "dist/src/aberdeen.js",
   "devDependencies": {

src/aberdeen.ts

@@ -1423,7 +1423,7 @@ function optProxy(value: any): any {
 		typeof value !== "object" ||
 		!value ||
 		value[TARGET_SYMBOL] !== undefined ||
-		NO_COPY in value
+		value[OPAQUE]
 	) {
 		return value;
 	}
@@ -1721,7 +1721,7 @@ function copyRecursive<T extends object>(dst: T, src: T, flags: number): boolean
 			}
 			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;
 					}
@@ -1757,7 +1757,7 @@ function copyRecursive<T extends object>(dst: T, src: T, flags: number): boolean
 			if (dstValue === undefined && !dst.has(key)) 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;
 					}
@@ -1789,7 +1789,7 @@ function copyRecursive<T extends object>(dst: T, src: T, flags: number): boolean
 			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 as typeof srcValue, srcValue, flags) || changed;
 						continue;
 					}
@@ -1826,14 +1826,29 @@ const COPY_SUBSCRIBE = 32;
 const COPY_EMIT = 64;
 
 /**
- * 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 const OPAQUE = Symbol("OPAQUE");
+
+/**
+ * Use {@link OPAQUE} instead. This is an alias kept for backward compatibility.
+ * 
+ * @deprecated
  */
-export const NO_COPY = Symbol("NO_COPY");
+export const NO_COPY = OPAQUE;
 
-// Promises break when proxied, so we'll just mark them as NO_COPY
-(Promise.prototype as any)[NO_COPY] = true;
+// Promises break when proxied, so mark them as fully opaque
+(Promise.prototype as any)[OPAQUE] = true;
 
 /**
  * A reactive object containing CSS variable definitions.
@@ -1961,7 +1976,7 @@ export function darkMode(): boolean {
 
 // Simple recursive clone - no destination checking needed
 function cloneRecursive<T extends object>(src: T, flags: number): T {
-	if (NO_COPY in src) return src;
+	if (OPAQUE in src) return src;
 	if (flags & COPY_SUBSCRIBE) subscribe(src, ANY_SYMBOL);
 
 	if (src instanceof Array) {
@@ -3299,8 +3314,8 @@ export function dump<T>(data: T): T {
 	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 as any, (value, key) => {
@@ -3422,6 +3437,7 @@ export default Object.assign(A, {
 	/** {@inheritDoc merge} */ merge,
 	/** {@inheritDoc mount} */ mount,
 	/** {@inheritDoc multiMap} */ multiMap,
+	/** {@inheritDoc OPAQUE} */ OPAQUE,
 	/** {@inheritDoc NO_COPY} */ NO_COPY,
 	/** {@inheritDoc onEach} */ onEach,
 	/** {@inheritDoc partition} */ partition,

tests/copy.test.ts

@@ -137,3 +137,47 @@ test('A.clone subscribes to all deeply nested values', async () => {
     expect(cnt).toBe(2); // Should have re-run because we subscribed to the nested value
 });
 
+test('OPAQUE=true prevents proxying and reactive tracking', async () => {
+    const inner = { x: 1 } as any;
+    inner[A.OPAQUE] = true;
+    const state = A.proxy({ obj: inner });
+
+    // state.obj should be the raw object — not wrapped in a proxy
+    expect(state.obj).toBe(inner);
+
+    // Reading state.obj.x should NOT create a reactive dependency
+    let cnt = 0;
+    A(() => { (state.obj as any).x; cnt++; });
+    expect(cnt).toBe(1);
+    inner.x = 2;
+    await passTime();
+    expect(cnt).toBe(1); // scope did not re-run
+
+    // A.clone returns the same reference, not a deep copy
+    expect((A.clone(state) as any).obj).toBe(inner);
+});
+
+test('OPAQUE=false prevents deep-copy but still allows reactive tracking', async () => {
+    const inner = { x: 1 } as any;
+    inner[A.OPAQUE] = false;
+    const state = A.proxy({ obj: inner });
+
+    // state.obj should be a proxy wrapping inner
+    expect(A.unproxy(state.obj)).toBe(inner);
+
+    // Reading state.obj.x SHOULD create a reactive dependency
+    let result = 0;
+    let cnt = 0;
+    A(() => { result = (state.obj as any).x; cnt++; });
+    expect(cnt).toBe(1);
+    expect(result).toBe(1);
+
+    (state.obj as any).x = 2;
+    await passTime();
+    expect(cnt).toBe(2); // scope re-ran
+    expect(result).toBe(2);
+
+    // A.clone still returns the inner object by reference (not deep-copied)
+    expect((A.clone(state) as any).obj).toBe(inner);
+});
+