@ng-org/alien-deepsignals 0.1.2-alpha.5 → 0.1.2-alpha.7

package/dist/deepSignal.js

@@ -17,19 +17,23 @@ exports.getDeepSignalVersion = getDeepSignalVersion;
 exports.shallow = shallow;
 exports.setSetEntrySyntheticId = setSetEntrySyntheticId;
 exports.addWithId = addWithId;
+exports.getRaw = getRaw;
 const core_1 = require("./core");
 const iteratorHelpers_1 = require("./iteratorHelpers");
 /** The current proxy object for the raw object (others might exist but are not the current / clean ones). */
 const rawToProxy = new WeakMap();
 const rawToMeta = new WeakMap();
-// TODO: We can move them to the meta objects.
+/**
+ * Mapping of raw objects to child signals.
+ * We store them globally because the same object can be attached in different locations.
+ */
 const propertiesToSignals = new WeakMap();
 const iterableSignals = new WeakMap();
 const ignored = new WeakSet();
+// TODO: We can just add this to the root directly
 const rootStates = new Map();
 const pendingRoots = new Set();
 const supported = new Set([Object, Array, Set]);
-const descriptor = Object.getOwnPropertyDescriptor;
 let blankNodeCounter = 0;
 let tmpIdCounter = 0;
 const wellKnownSymbols = new Set([
@@ -62,51 +66,89 @@ function shouldProxy(value) {
         !ignored.has(value));
 }
 /**
- * Get or create the map in `proxySignals` for key `proxy`.
+ * Get or create the map in `proxySignals` for raw object to `Map<property key, signal>`
  */
-function ensureSignalMap(rawObj) {
+function getOrCreateSignalMap(rawObj) {
     if (!propertiesToSignals.has(rawObj))
         propertiesToSignals.set(rawObj, new Map());
     return propertiesToSignals.get(rawObj);
 }
 /**
  * Write a new value into a cached signal, creating it if needed.
- * Does nothing computed signals.
+ * Does nothing on computed signals.
  */
-function setSignalValue(signals, key, value) {
+function setSignalValue(meta, key, value) {
+    const signals = propertiesToSignals.get(meta.raw);
     if (!signals.has(key)) {
-        signals.set(key, (0, core_1.signal)(value));
-        return;
+        // Add new signal.
+        signals.set(key, {
+            alienSignal: (0, core_1.alienSignal)(value),
+            // Do not add external subscribers yet, they will be created on first read.
+            externalSubscribers: new Map(),
+        });
     }
-    const existing = signals.get(key);
-    if (typeof existing.set === "function") {
-        existing.set(value);
+    else {
+        // Update existing signal.
+        const existingSignal = signals.get(key);
+        existingSignal.alienSignal(value);
+        existingSignal.externalSubscribers
+            .values()
+            .forEach((subscriber) => subscriber.onSet(value));
     }
 }
-/** Track mutations that affect object iteration order/length. */
-function ensureIterableSignal(target) {
-    if (!iterableSignals.has(target))
-        iterableSignals.set(target, (0, core_1.signal)(0));
-    return iterableSignals.get(target);
+/** Gets the current value of a signal and notifies external subscribers about read. */
+function getValFromSignalRecord(meta, record) {
+    const val = record.alienSignal();
+    // Notify external subscribers (usually frontend frameworks) about property access.
+    meta.options.subscriberFactories?.forEach((createSubscriber) => {
+        let subscriber = record.externalSubscribers.get(createSubscriber);
+        if (!subscriber) {
+            // Create new subscriber
+            subscriber = createSubscriber();
+            record.externalSubscribers.set(createSubscriber, subscriber);
+        }
+        subscriber.onGet();
+    });
+    return val;
+}
+/** Sets the current value of a signal and notifies external subscribers about update. */
+function setValToSignalRecord(record, value) {
+    record.alienSignal(value);
+    // Notify external subscribers (usually frontend frameworks) about property update.
+    record.externalSubscribers.forEach((subscriber) => subscriber.onSet(value));
+}
+/** Track mutations that affect object iteration order/length with a counter signal. */
+function ensureIterableSignal(meta, target) {
+    // Create new one if none exists.
+    if (!iterableSignals.has(target)) {
+        iterableSignals.set(target, {
+            alienSignal: (0, core_1.alienSignal)(0),
+            externalSubscribers: new Map(),
+        });
+    }
+    const signal = iterableSignals.get(target);
+    getValFromSignalRecord(meta, signal);
 }
-/** Notify all iteration-based subscribers that the container changed shape. */
-function touchIterable(target) {
+/** Notify all iteration-based subscribers that the container changed shape, by increasing the counter signal. */
+function touchIterable(meta, target) {
     if (!iterableSignals.has(target))
         return;
-    const sig = iterableSignals.get(target);
-    sig.set(sig() + 1);
-}
-/** True when the target has a getter defined for the provided key. */
-function hasGetter(target, key) {
-    return typeof descriptor(target, key)?.get === "function";
+    const signalRecord = iterableSignals.get(target);
+    const oldCountVal = getValFromSignalRecord(meta, signalRecord);
+    const newVal = oldCountVal + 1;
+    setValToSignalRecord(signalRecord, newVal);
 }
 /**
- * Ensure that `signals` has a computed signal for the property with `key` on target.
- * TODO: Why is this necessary?
+ * Create computed signals for getter functions.
  */
-function ensureComputed(signals, target, key, receiver) {
-    if (!signals.has(key) && hasGetter(target, key)) {
-        signals.set(key, (0, core_1.computed)(() => Reflect.get(target, key, receiver)));
+function ensureProxiedGetter(signals, target, key, receiver) {
+    if (!signals.has(key) &&
+        typeof Object.getOwnPropertyDescriptor(target, key)?.get === "function" // If we have a getter?
+    ) {
+        signals.set(key, {
+            alienSignal: (0, core_1.computed)(() => Reflect.get(target, key, receiver)),
+            externalSubscribers: new Map(),
+        });
     }
 }
 /** Escape JSON-pointer-like path segments so patches remain unambiguous. */
@@ -121,18 +163,23 @@ function isReactiveSymbol(key) {
     return typeof key === "symbol" && !wellKnownSymbols.has(key);
 }
 /**
- * Replaces the old proxy to a raw object with a new one.
+ * Replaces the old rawToProxy object with a proxy object.
  * Used so that we can indicate modifications along the path of a change by equality checks.
+ * All values remain the same.
+ *
+ * Does nothing if the deep signal's options `replaceProxiesInBranchOnChange` is false.
  */
-function replaceProxy(meta) {
-    if (!meta.parent || !meta.key)
+function replaceProxyMaybe(meta) {
+    if (!meta.parent ||
+        !meta.key ||
+        !meta.options.replaceProxiesInBranchOnChange)
         return;
     // Create a new proxy for this raw object -- frontend libs like react need this to recognize changes along this path.
     const handlers = meta.raw instanceof Set ? setHandlers : objectHandlers;
     const proxy = new Proxy(meta.raw, handlers);
     rawToProxy.set(meta.raw, proxy);
-    const signal = propertiesToSignals.get(meta.parent.raw)?.get(meta.key);
-    signal?.(proxy);
+    const signal = getOrCreateSignalMap(meta.parent.raw).get(meta.key);
+    signal?.alienSignal(proxy);
 }
 /**
  * Walk the metadata chain to build the patch path for a property access.
@@ -160,7 +207,7 @@ function buildPath(meta, key, skipEscape = false) {
     let cursor = meta;
     while (cursor && cursor.parent && cursor.key !== undefined) {
         push(cursor.key, !!cursor.isSyntheticId);
-        replaceProxy(cursor);
+        replaceProxyMaybe(cursor);
         cursor = cursor.parent;
     }
     return path;
@@ -169,7 +216,7 @@ function buildPath(meta, key, skipEscape = false) {
 function resolveContainerPath(meta) {
     if (!meta || !meta.parent || meta.key === undefined)
         return [];
-    replaceProxy(meta);
+    replaceProxyMaybe(meta);
     return buildPath(meta.parent, meta.key, !!meta.isSyntheticId);
 }
 /**
@@ -293,16 +340,17 @@ function initializeObjectTreeIfNoListeners(meta, basePath, value, inSet) {
     initializeObjectTree(meta, value, basePath ?? [], inSet);
 }
 /**
- * Return (or create) a proxy for a nested value.
+ * Return (or create) a proxy for a property value.
  * Ensures the linkage between parent and child in metadata.
  * Does not proxy and returns `value` if @see shouldProxy returns false.
- * Returns value if parent has no metadata record.
+ * Assumes parent has proxy.
  */
 function ensureChildProxy(rawChild, parent, key, isSyntheticId = false) {
     if (!shouldProxy(rawChild))
         return rawChild;
     const parentRaw = parent[RAW_KEY] || parent;
-    const parentMeta = rawToMeta?.get(parentRaw);
+    const parentMeta = rawToMeta.get(parentRaw);
+    // Child is already proxied, ensure the linkage from parent to child.
     if (rawToProxy.has(rawChild)) {
         const proxied = rawToProxy.get(rawChild);
         const proxiedMeta = rawToMeta.get(rawChild);
@@ -313,8 +361,6 @@ function ensureChildProxy(rawChild, parent, key, isSyntheticId = false) {
         }
         return proxied;
     }
-    if (!parentMeta)
-        return rawChild;
     // Create proxy if none exists yet.
     const proxy = createProxy(rawChild, parentMeta.root, parentMeta.options, parentMeta, key, isSyntheticId);
     return proxy;
@@ -336,8 +382,8 @@ function ensureSetInfo(meta) {
  * Assign (or reuse) a synthetic identifier for a Set entry, respecting user options:
  * - Use user-provided propGenerator for synthetic ids and add add returned extra properties
  * - Check if the object has a property of `syntheticIdPropertyName` (default `@id`)
- * - Use a blank node id as a fallback.
- * - Add object and id to `idForObject` and `objectForId` maps.
+ * - Use a blank node ID as a fallback.
+ * - Add object and ID to `idForObject` and `objectForId` maps.
  */
 function assignSyntheticId(meta, entry, path, inSet) {
     const rawEntry = entry?.[RAW_KEY] ?? entry;
@@ -410,7 +456,7 @@ function createProxy(target, root, options, parentMeta, key, isSyntheticId) {
         root,
         options,
     };
-    propertiesToSignals.set(target, new Map());
+    getOrCreateSignalMap(target);
     rawToMeta.set(target, meta);
     rawToProxy.set(target, proxy);
     return proxy;
@@ -507,25 +553,22 @@ function emitPatchesForNew(value, meta, basePath, inSet = false) {
  * and dependent effects are notified. Recreates/proxies values for indices < length
  * and clears signals for indices >= length.
  */
-function refreshNumericIndexSignals(target, receiver) {
-    const sigs = propertiesToSignals.get(target);
-    if (!sigs)
-        return;
-    for (const k of Array.from(sigs.keys())) {
+function refreshNumericIndexSignals(meta, target, receiver) {
+    const signals = getOrCreateSignalMap(meta.raw);
+    for (const k of Array.from(signals.keys())) {
         if (typeof k === "string" && /^\d+$/.test(k)) {
             const idx = Number(k);
             if (idx >= target.length) {
-                const existing = sigs.get(k);
-                if (existing &&
-                    typeof existing.set === "function") {
-                    existing.set(undefined);
+                const existing = signals.get(k);
+                if (existing) {
+                    setSignalValue(meta, k, undefined);
                 }
-                sigs.delete(k);
+                signals.delete(k);
             }
             else {
                 const val = target[idx];
                 const proxied = ensureChildProxy(val, receiver, idx);
-                setSignalValue(sigs, k, proxied);
+                setSignalValue(meta, k, proxied);
             }
         }
     }
@@ -559,7 +602,7 @@ const getArrayMutationProxy = (target, key, receiver) => {
             // Update length of proxy explicitly.
             receiver.length = target.length;
             // Refresh numeric index signals so shifted indices don't return stale values.
-            refreshNumericIndexSignals(target, receiver);
+            refreshNumericIndexSignals(meta, target, receiver);
         };
     }
     else if (key === "splice") {
@@ -591,7 +634,7 @@ const getArrayMutationProxy = (target, key, receiver) => {
                 ensureChildProxy(items[i], target, start + i);
             }
             // Refresh numeric index signals so shifted indices don't return stale values.
-            refreshNumericIndexSignals(target, receiver);
+            refreshNumericIndexSignals(meta, target, receiver);
             // Update length of proxy explicitly.
             receiver.length = target.length;
             return deletedItems;
@@ -619,7 +662,7 @@ const getArrayMutationProxy = (target, key, receiver) => {
             // Update length of proxy explicitly.
             receiver.length = target.length;
             // Refresh numeric index signals so shifted indices don't return stale values.
-            refreshNumericIndexSignals(target, receiver);
+            refreshNumericIndexSignals(meta, target, receiver);
             return deletedItems;
         };
     }
@@ -632,13 +675,14 @@ const objectHandlers = {
             return target;
         if (key === META_KEY)
             return rawToMeta.get(target);
-        // TODO: Why are we doing this?
+        const meta = rawToMeta.get(target);
         if (typeof key === "symbol") {
             if (key === Symbol.iterator) {
-                const iterableSig = ensureIterableSignal(target);
-                iterableSig();
+                // Ensure that signal exists tracking iteration-based dependencies.
+                ensureIterableSignal(meta, target);
             }
             if (!isReactiveSymbol(key))
+                // No reactivity for well-known symbols
                 return Reflect.get(target, key, receiver);
         }
         // Array helper handling. We need that because otherwise, every array position change would go as a separate operation through the proxy.
@@ -650,20 +694,20 @@ const objectHandlers = {
             }
         }
         // Get object map from key to signal.
-        const signals = ensureSignalMap(target);
-        // Ensure that target object is signal.
-        ensureComputed(signals, target, key, receiver);
+        const signals = getOrCreateSignalMap(meta.raw);
+        // If the property value is a getter, create a computed signal for it.
+        ensureProxiedGetter(signals, target, key, receiver);
         // Add signal if it does not exist already and did not have a getter.
         if (!signals.has(key)) {
             let rawChild = Reflect.get(target, key, receiver);
             if (typeof rawChild === "function")
                 return rawChild.bind(receiver ?? target);
             const childProxyOrRaw = ensureChildProxy(rawChild, receiver, key);
-            signals.set(key, (0, core_1.signal)(childProxyOrRaw));
+            setSignalValue(meta, key, childProxyOrRaw);
         }
-        // Call and return signal
+        // Call and return signal.
         const sig = signals.get(key);
-        return sig();
+        return getValFromSignalRecord(meta, sig);
     },
     set(target, key, value, receiver) {
         // Skip reactivity for symbols.
@@ -674,9 +718,6 @@ const objectHandlers = {
             throw new Error(`Cannot modify readonly property '${String(key)}'`);
         }
         const path = meta ? buildPath(meta, key) : undefined;
-        const desc = descriptor(target, key);
-        const hasAccessor = !!desc &&
-            (typeof desc.get === "function" || typeof desc.set === "function");
         const proxied = ensureChildProxy(value, target, key);
         const rawValue = value?.[RAW_KEY] ?? value;
         const hadKey = Object.prototype.hasOwnProperty.call(target, key);
@@ -690,12 +731,10 @@ const objectHandlers = {
         }
         // === Set value on actual target ===
         const result = Reflect.set(target, key, rawValue, receiver);
-        if (!hasAccessor) {
-            const signals = ensureSignalMap(target);
-            setSignalValue(signals, key, proxied);
-        }
+        // Set signal value.
+        setSignalValue(meta, key, proxied);
         if (!hadKey)
-            touchIterable(target);
+            touchIterable(meta, target);
         if (meta && path && typeof rawValue === "object") {
             initializeObjectTreeIfNoListeners(meta, path, rawValue, false);
         }
@@ -738,18 +777,15 @@ const objectHandlers = {
         const hadKey = Object.prototype.hasOwnProperty.call(target, key);
         const result = Reflect.deleteProperty(target, key);
         if (hadKey) {
-            if (propertiesToSignals.has(target)) {
-                // Trigger signal
-                const signals = propertiesToSignals.get(target);
-                const existing = signals.get(key);
-                if (existing &&
-                    typeof existing.set === "function") {
-                    existing.set(undefined);
-                }
-                signals.delete(key);
-            }
+            // Trigger signal
+            const signals = getOrCreateSignalMap(meta.raw);
+            const existing = signals.get(key);
+            if (existing)
+                setValToSignalRecord(existing, undefined);
+            signals.delete(key);
             // Notify listeners
-            touchIterable(target);
+            touchIterable(meta, target);
+            // Schedule remove patch.
             schedulePatch(meta, () => ({
                 path: buildPath(meta, key),
                 op: "remove",
@@ -758,30 +794,22 @@ const objectHandlers = {
         return result;
     },
     ownKeys(target) {
-        const sig = ensureIterableSignal(target);
-        sig();
+        const meta = rawToMeta.get(target);
+        const sig = ensureIterableSignal(meta, target);
         return Reflect.ownKeys(target);
     },
 };
-/**
- * Guarantee Set iteration always surfaces proxies, even when raw values were stored.
- */
-function ensureEntryProxy(raw, entry, syntheticKey, meta) {
-    return shouldProxy(entry)
-        ? ensureChildProxy(entry, raw, syntheticKey, true)
-        : entry;
-}
 /** Wrap the underlying Set iterator so each value is proxied before leaving the trap. */
 function createSetIterator(target, receiver, mapValue) {
+    const meta = rawToMeta.get(target);
     const iterator = target.values();
-    const iterableSignal = ensureIterableSignal(target);
-    iterableSignal();
+    ensureIterableSignal(meta, target);
     return (0, iteratorHelpers_1.createIteratorWithHelpers)(() => {
         const next = iterator.next();
         if (next.done)
             return next;
         const meta = rawToMeta.get(target);
-        const proxied = ensureEntryProxy(target, next.value, assignSyntheticId(meta, next.value, [], true), meta);
+        const proxied = ensureChildProxy(next.value, target, assignSyntheticId(meta, next.value, [], true), true);
         return {
             value: mapValue(proxied),
             done: false,
@@ -797,36 +825,33 @@ const setHandlers = {
         if (key === META_KEY)
             return meta;
         if (key === "size") {
-            const sig = ensureIterableSignal(target);
-            sig();
+            ensureIterableSignal(meta, target);
             return target.size;
         }
         if (key === "first") {
             return function first() {
-                const iterableSig = ensureIterableSignal(target);
-                iterableSig();
                 const iterator = target.values().next();
                 if (iterator.done)
                     return undefined;
-                return ensureEntryProxy(target, iterator.value, assignSyntheticId(meta, iterator.value, [], true), meta);
+                const proxy = ensureChildProxy(iterator.value, target, assignSyntheticId(meta, iterator.value, [], true), true);
+                ensureIterableSignal(meta, target);
+                return proxy;
             };
         }
         if (key === "getById") {
             return function getById(id) {
-                const iterableSig = ensureIterableSignal(target);
-                iterableSig();
                 if (!meta?.setInfo)
                     return undefined;
                 const entry = meta.setInfo.objectForId.get(String(id));
                 if (!entry)
                     return undefined;
-                return ensureEntryProxy(target, entry, String(id), meta);
+                const proxy = ensureChildProxy(entry, target, String(id));
+                ensureIterableSignal(meta, target);
+                return proxy;
             };
         }
         if (key === "getBy") {
             return function getBy(graphIri, subjectIri) {
-                const iterableSig = ensureIterableSignal(target);
-                iterableSig();
                 return this.getById(`${graphIri}|${subjectIri}`);
             };
         }
@@ -834,26 +859,30 @@ const setHandlers = {
             return function add(value) {
                 const containerPath = resolveContainerPath(meta);
                 const rawValue = value[RAW_KEY] ?? value;
-                const sizeBefore = target.size;
-                const result = target.add(rawValue);
-                if (target.size !== sizeBefore) {
-                    touchIterable(target);
-                    if (rawValue && typeof rawValue === "object") {
-                        const synthetic = assignSyntheticId(meta, rawValue, containerPath, true);
-                        initializeObjectTreeIfNoListeners(meta, [...containerPath, synthetic], rawValue, true);
-                        ensureEntryProxy(target, rawValue, synthetic, meta);
-                        schedulePatch(meta, () => emitPatchesForNew(rawValue, meta, [...containerPath, synthetic], true));
-                    }
-                    else {
-                        const literal = snapshotLiteral(rawValue);
-                        if (literal !== undefined) {
-                            schedulePatch(meta, () => ({
-                                path: containerPath,
-                                op: "add",
-                                type: "set",
-                                value: [literal],
-                            }));
-                        }
+                if (target.has(rawValue)) {
+                    // Nothing to do.
+                    return receiver;
+                }
+                target.add(rawValue);
+                if (rawValue && typeof rawValue === "object") {
+                    // Case: Object in set
+                    const synthetic = assignSyntheticId(meta, rawValue, containerPath, true);
+                    initializeObjectTreeIfNoListeners(meta, [...containerPath, synthetic], rawValue, true);
+                    ensureChildProxy(rawValue, target, synthetic, true);
+                    touchIterable(meta, target);
+                    schedulePatch(meta, () => emitPatchesForNew(rawValue, meta, [...containerPath, synthetic], true));
+                }
+                else {
+                    // Case: Literal in set
+                    touchIterable(meta, target);
+                    const literal = snapshotLiteral(rawValue);
+                    if (literal !== undefined) {
+                        schedulePatch(meta, () => ({
+                            path: containerPath,
+                            op: "add",
+                            type: "set",
+                            value: [literal],
+                        }));
                     }
                 }
                 return receiver;
@@ -861,14 +890,16 @@ const setHandlers = {
         }
         if (key === "delete") {
             return function deleteEntry(value) {
-                const containerPath = resolveContainerPath(meta);
                 const rawValue = value?.[RAW_KEY] ?? value;
                 const synthetic = rawValue && typeof rawValue === "object"
                     ? ensureSetInfo(meta).idForObject.get(rawValue)
                     : rawValue;
                 const existed = target.delete(rawValue);
+                if (existed) {
+                    touchIterable(meta, target);
+                }
                 if (existed && synthetic !== undefined) {
-                    touchIterable(target);
+                    const containerPath = resolveContainerPath(meta);
                     if (rawValue && typeof rawValue === "object") {
                         schedulePatch(meta, () => ({
                             path: [...containerPath, synthetic],
@@ -893,13 +924,16 @@ const setHandlers = {
         }
         if (key === "clear") {
             return function clear() {
+                // Nothing to do.
+                if (target.size === 0)
+                    return;
                 const containerPath = resolveContainerPath(meta);
                 if (meta.setInfo) {
                     meta.setInfo.objectForId.clear();
                     meta.setInfo.idForObject = new WeakMap();
                 }
                 target.clear();
-                touchIterable(target);
+                touchIterable(meta, target);
                 schedulePatch(meta, () => ({
                     path: containerPath,
                     op: "add",
@@ -938,13 +972,12 @@ const setHandlers = {
         }
         if (key === "forEach") {
             return function forEach(callback, thisArg) {
-                const iterableSig = ensureIterableSignal(target);
-                iterableSig();
+                ensureIterableSignal(meta, target);
                 let index = 0;
                 const expectsIteratorSignature = callback.length <= 2;
                 const iteratorCallback = callback;
                 target.forEach((entry) => {
-                    const proxied = ensureEntryProxy(target, entry, assignSyntheticId(meta, entry, [], true), meta);
+                    const proxied = ensureChildProxy(entry, target, assignSyntheticId(meta, entry, [], true), true);
                     if (expectsIteratorSignature) {
                         iteratorCallback.call(thisArg, proxied, index++);
                     }
@@ -956,10 +989,23 @@ const setHandlers = {
         }
         if (key === "has") {
             return function has(value) {
+                ensureIterableSignal(meta, target);
                 return target.has(value?.[RAW_KEY] ?? value);
             };
         }
-        return Reflect.get(target, key, receiver);
+        // All other cases:
+        const res = target[key];
+        if (typeof res === "function") {
+            // For all other functions on sets, return a wrapped function
+            // that calls ensureIterableSignal() before.
+            return (...props) => {
+                ensureIterableSignal(meta, target);
+                return res.bind(target)(...props);
+            };
+        }
+        else {
+            return res;
+        }
     },
 };
 /** Runtime guard that checks whether a value is a deepSignal proxy. */
@@ -967,13 +1013,27 @@ function isDeepSignal(value) {
     return !!value?.[RAW_KEY];
 }
 /**
- * Create a deep reactive proxy for objects, arrays or Sets.
- * Returns the input itself, if it's a deepSignal already.
- * Throws if provided with unsupported input types.
+ * MAIN ENTRY POINT to create a deep reactive proxy for objects, arrays or Sets.
+ *
+ * If input is a deepSignal already and options are provided,
+ * the added subscriberFactories are joined with the existing ones
+ * and `replaceProxiesInBranchOnChange` is or-ed with the current value.
+ *
+ *
+ * @throws if provided with unsupported input types.
  */
 function deepSignal(input, options) {
-    if (isDeepSignal(input))
+    // Is the input already a signal?
+    if (isDeepSignal(input)) {
+        // Add possibly new external subscribers to existing ones.
+        const meta = rawToMeta.get(input[RAW_KEY]);
+        meta.options.subscriberFactories =
+            meta.options.subscriberFactories.union(options?.subscriberFactories ?? new Set());
+        meta.options.replaceProxiesInBranchOnChange =
+            meta?.options.replaceProxiesInBranchOnChange ||
+                options?.replaceProxiesInBranchOnChange;
         return input;
+    }
     if (!shouldProxy(input))
         throw new Error("deepSignal() expects an object, array, or Set");
     if (rawToProxy.has(input))
@@ -982,6 +1042,8 @@ function deepSignal(input, options) {
     const rootState = {
         options: {
             syntheticIdPropertyName: DEFAULT_SYNTHETIC_ID_PROPERTY_NAME,
+            replaceProxiesInBranchOnChange: false,
+            subscriberFactories: new Set(),
             ...options,
         },
         version: 0,
@@ -1030,7 +1092,14 @@ function getDeepSignalVersion(root) {
         return undefined;
     return rootStates.get(rootId)?.version;
 }
-/** Mark an object so deepSignal skips proxying it (shallow boundary). */
+/** Mark an object so deepSignal skips proxying it (shallow boundary).
+ *
+ * @example
+ * ```ts
+ * import { shallow } from "alien-deepsignals";
+ * state.config = shallow({ huge: { blob: true } });
+ * ```
+ */
 function shallow(obj) {
     ignored.add(obj);
     return obj;
@@ -1058,3 +1127,7 @@ function addWithId(set, entry, id) {
     }
     return entry;
 }
+/** Get the original, raw value of a deep signal. */
+function getRaw(value) {
+    return value?.[RAW_KEY] ?? value;
+}

package/dist/effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAKA,KAAK,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAErD,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,EAAE,eAAe,KAAK,IAAI,cA2BtE"}
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAYA,KAAK,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAErD,sEAAsE;AACtE,wBAAgB,MAAM,CAAC,GAAG,EAAE,CAAC,eAAe,CAAC,EAAE,eAAe,KAAK,IAAI,cA2BtE"}