feat(forms): implement deepSignal and structuralSignal

These are new signal variants that optimize the way updates are written in
large chains of `deepSignal`s. This optimization primarily avoids
invalidating `deepSignal`s that aren't affected by writes, even if they
derive from parents whose values are changed. See the added `README.md` for
details.

Author: alxhub

packages/core/src/core_reactivity_export_internal.ts

@@ -10,6 +10,14 @@ export {SIGNAL as ɵSIGNAL} from '../primitives/signals';
 
 export {isSignal, Signal, ValueEqualityFn} from './render3/reactivity/api';
 export {computed, CreateComputedOptions} from './render3/reactivity/computed';
+export {
+  deepSignal as ɵdeepSignal,
+  DeepSignalOptions as ɵDeepSignalOptions,
+} from './render3/reactivity/deep_signal/deep_signal';
+export {
+  structuralSignal as ɵstructuralSignal,
+  StructuralSignalOptions as ɵStructuralSignalOptions,
+} from './render3/reactivity/deep_signal/structural_signal';
 export {
   CreateSignalOptions,
   signal,

packages/core/src/render3/reactivity/deep_signal/README.md

@@ -0,0 +1,81 @@
+# Deep signals
+
+A "deep signal" is a `WritableSignal` whose value comes from a specific property in a parent `WritableSignal`. Its value is always the value from the parent, and updating its value updates the value within the parent. This table shows the behavior of deep signals compared to other signal flavors when deriving a value from a parent property in this way.
+
+| Signal Type    | Reading                                         | Writing                                  |
+| -------------- | ----------------------------------------------- | ---------------------------------------- |
+| `computed`     | Value derived from parent                       | 🚫 Not allowed                           |
+| `linkedSignal` | Value derived from parent OR local value if set | Does not change parent, only local value |
+| `deepSignal`   | Value derived from parent                       | Updates value in parent                  |
+
+As a code example:
+
+```ts
+// Parent signal with complex object value.
+const model = signal({user: {name: 'Alex'}, company: 'Google'});
+
+// Deep signal for `user` property of the model.
+const user = deepSignal(model, 'user');
+
+console.log(user()); // {name: 'Alex'}
+
+// Updating `user` updates the parent.
+user.set({name: 'Bob'});
+console.log(model()); // {user: {name: 'Bob'}, company: 'Google'}
+```
+
+Deep signals combine the derivation of a value with the ability to update that value in the parent, making them an excellent tool for modeling hierarchical state.
+
+## Performance
+
+A key aspect of deep signals is their performance advantage over other methods of derivation.
+
+Consider a similar setup as the example above, in plain signals:
+
+```ts
+// Parent signal with complex object value.
+const model = signal({user: {name: 'Alex'}, company: 'Google'});
+
+const user = computed(() => model().user);
+const company = computed(() => model().company);
+
+effect(() => console.log(user())); // {name: 'Alex'}
+
+// Update the company to 'Waymo':
+model.update(value => {...value, company: 'Waymo'});
+```
+
+The update to `model` replaces its object value with a new one that stores the new `company` value. Even though `model` changes, `user`'s value is unaffected: the update to `model` does not touch the value of its `user` property.
+
+In ordinary signal operations, the `user` computed would be marked "maybe dirty" from its dependency on `model`, as would the effect which depends on `user`. Eventually, rerunning the `user` derivation would detect that its value didn't actually change, and so the effect would short-circuit and not actually run. Semantically, this is correct behavior.
+
+In a large graph, however, changing the signal at the top which is the source of truth for the entire graph would schedule _all_ effects depending on any part of the model this way. This is still a non-trivial cost, even with the short-circuiting.
+
+Deep signals address this issue by leveraging their knowledge about _what_ is changing in the parent's value. Since a deep signal only changes its own property in the parent, other deep signals deriving other properties are guaranteed to be unaffected and do not need to be notified. When a deep signal write occurs in a large graph, only those signals which _actually observe the write_ are notified, meaning only effects that could potentially need to rerun are marked dirty.
+
+## Algorithm
+
+`deepSignal` is a hybrid, building on the `computed` reactive node type but in some ways behaving like a plain `signal`. It has a computation function that reads `parent()[ property ]` (where `property` is optionally reactive).
+
+`deepSignal`'s write path is deeply specialized. The algorithm is as follows:
+
+1. When a `deepSignal` write occurs, the `deepSignal` marks itself dirty and notifies its consumers of its change, as if it were a plain `signal`. A difference here is that it temporarily uses the value of `COMPUTING` for its value, which guards against `deepSignal` cycles.
+
+2. It then pushes its own reactive node to a global stack of `deepSignal` writers.
+
+3. It updates the `parent` writable signal, building a new value based on the `parent`'s current value and the `deepSignal`'s `property`.
+
+4. It updates its own value and marks itself clean.
+
+5. It pops itself from the `deepSignal` writer stack.
+
+The `deepSignal` writer stack is used to implement the dirty notification short-circuiting mechanism described in the Performance section. The `DEEP_SIGNAL_NODE` type overrides the behavior of `node.dirty`, and will additionally report itself dirty when there is an active `deepSignal` writer that meets the criteria:
+
+- When the active `deepSignal` writer shares its same parent (they're both derived from the same parent signal).
+- The active `deepSignal` writer is writing to a _different_ key than the current signal is monitoring.
+
+If both of these conditions are true, the `deepSignal`'s node will report itself as `dirty`, which short circuits any dirty notifications being sent when the active writer updates the parent.
+
+# Structural signals
+
+The `deepSignal` mechanism allows the construction of another useful type of signal, which we call `structuralSignal`. A `structuralSignal` is derived from another `WritableSignal` and returns the same value. It behaves like `computed(() => parent())` with one exception: it does not get notified when the parent changes via a `deepSignal` write. Since a `deepSignal` write only changes an existing property, a `structuralSignal` can be used when a consumer is only interested in values that might have different shapes.

packages/core/src/render3/reactivity/deep_signal/deep_signal.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {untracked} from '../untracked';
+import {isSignal, type Signal} from '../api';
+import {type WritableSignal, signalAsReadonlyFn} from '../signal';
+
+import {
+  ERRORED,
+  producerAccessed,
+  producerIncrementEpoch,
+  producerMarkClean,
+  producerNotifyConsumers,
+  producerUpdatesAllowed,
+  producerUpdateValueVersion,
+  type ReactiveNode,
+  runPostProducerCreatedFn,
+  throwInvalidWriteToSignalError,
+  SIGNAL,
+  COMPUTING,
+} from '../../../../primitives/signals';
+
+import {DEEP_SIGNAL_NODE, type DeepSignalNode, setDeepSignalWriter} from './internal';
+
+export interface DeepSignalOptions {
+  debugName?: string;
+}
+
+export function deepSignal<T extends {}, K extends keyof T>(
+  parent: WritableSignal<T>,
+  key: K | Signal<K>,
+  options?: DeepSignalOptions,
+): WritableSignal<T[K]> {
+  type V = T[K];
+
+  let keySignal: Signal<K> | undefined;
+
+  // Create our `DEEP_SIGNAL_NODE` and initialize it.
+  const node: DeepSignalNode = Object.create(DEEP_SIGNAL_NODE);
+  if (isSignal(key)) {
+    keySignal = key;
+    node.propertyNode = keySignal[SIGNAL] as ReactiveNode;
+  } else {
+    node.lastProperty = key;
+  }
+
+  node.parentNode = parent[SIGNAL] as ReactiveNode;
+  // Our value derives from the parent's value at our specific key.
+  node.computation = () => {
+    // Save the key we observe here as `lastKey`. We can short circuit later notifications as long
+    // as the write was not to this key.
+    if (keySignal) {
+      node.lastProperty = keySignal();
+      node.lastPropertyValueVersion = node.propertyNode!.version;
+    }
+
+    return parent()[node.lastProperty as K];
+  };
+  if (options?.debugName) {
+    node.debugName = options.debugName;
+  }
+
+  // Next define the signal getter, which uses the same flow as `computed`.
+  const getter = (() => {
+    // Check if the value needs updating before returning it.
+    producerUpdateValueVersion(node);
+
+    // Record that someone looked at this signal.
+    producerAccessed(node);
+
+    if (node.value === ERRORED) {
+      throw node.error;
+    }
+
+    return node.value;
+  }) as WritableSignal<V>;
+  getter[SIGNAL] = node;
+
+  // The deep signal specific write path.
+  getter.set = (value: V) => {
+    if (!producerUpdatesAllowed()) {
+      throwInvalidWriteToSignalError(node);
+    }
+
+    if (node.equal(node.value, value)) {
+      return;
+    }
+
+    node.version++;
+    // We record a value of `COMPUTING` during the write to the parent, in case somehow the parent
+    // depends on us.
+    node.value = COMPUTING;
+
+    // Temporarily mark ourselves dirty during the write. Later on, we'll mark ourselves clean.
+    // This prevents the notification when we write to our parent from marking our children dirty.
+    node.rawDirty = true;
+
+    producerIncrementEpoch();
+    producerNotifyConsumers(node);
+
+    // Update the name of the property we're writing to, if it's reactive.
+    if (keySignal) {
+      node.lastProperty = untracked(keySignal);
+      node.lastPropertyValueVersion = node.propertyNode!.version;
+    }
+
+    const current = untracked(parent);
+
+    // We make one concession to `structuralSignal` here: if we're adding a property that does not
+    // exist, we don't use the `deepSignal` write path. This ensures any `structuralSignal`s will
+    // get notified of this change.
+    let prevWriter: DeepSignalNode | null;
+    if ((node.lastProperty as K) in current) {
+      prevWriter = setDeepSignalWriter(node);
+    } else {
+      prevWriter = setDeepSignalWriter(null);
+    }
+
+    try {
+      if (isArray<T, V>(current)) {
+        const newSource = [...current] as unknown as T & Array<V>;
+        newSource[node.lastProperty as number] = value;
+        parent.set(newSource);
+      } else {
+        parent.set({...current, [node.lastProperty as K]: value});
+      }
+      // TODO: today, `postSignalSetFn` happens when the top-most `parent` in a write path of
+      // `deepSignal`s is updated. We probably want to delay that until we come back up the stack
+      // and finish the write path of every `deepSignal` along the way (marking clean, etc).
+
+      // Unlike normal computed nodes, deep signals handle updating their own value. Therefore, once
+      // we set the value we can consider ourselves clean. We could set our value earlier.
+      node.value = value;
+      producerMarkClean(node);
+    } finally {
+      setDeepSignalWriter(prevWriter);
+    }
+  };
+
+  getter.update = (fn: (value: V) => V): void => {
+    getter.set(fn(untracked(getter)));
+  };
+
+  getter.asReadonly = signalAsReadonlyFn;
+
+  if (typeof ngDevMode !== 'undefined' && ngDevMode) {
+    const debugName = node.debugName ? ' (' + node.debugName + ')' : '';
+    getter.toString = () => `[DeepSignal${debugName}: ${node.value}]`;
+  }
+
+  runPostProducerCreatedFn(node);
+  return getter;
+}
+
+function isArray<T extends {}, V>(value: T): value is T & Array<V> {
+  return Array.isArray(value);
+}

packages/core/src/render3/reactivity/deep_signal/internal.ts

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {ReactiveNode, COMPUTED_NODE, ComputedNode, Version} from '../../../../primitives/signals';
+
+export interface DeepSignalNode extends ComputedNode<unknown> {
+  rawDirty: boolean;
+  propertyNode: ReactiveNode | undefined;
+  parentNode: ReactiveNode;
+  lastProperty: PropertyKey | undefined;
+  lastPropertyValueVersion: Version;
+}
+
+export const DEEP_SIGNAL_NODE: Omit<DeepSignalNode, 'computation' | 'parentNode'> =
+  /* @__PURE__ */ (() => {
+    return {
+      ...COMPUTED_NODE,
+      kind: 'deepSignal',
+      propertyNode: undefined,
+      lastProperty: undefined,
+      rawDirty: false,
+      get dirty(): boolean {
+        if (isSafeToShortCircuitNotifications(this as DeepSignalNode)) {
+          // Short-circuit notifications by reporting ourself as already dirty.
+          return true;
+        }
+
+        return this.rawDirty;
+      },
+      set dirty(value: boolean) {
+        this.rawDirty = value;
+      },
+      lastPropertyValueVersion: 0 as Version,
+    };
+  })();
+
+/**
+ * Determines whether `node` is definitely not affected by whatever write is currently ongoing and
+ * generating signal graph notifications.
+ */
+function isSafeToShortCircuitNotifications(node: DeepSignalNode): boolean {
+  // If the current write path doesn't involve any deep signal writes, then we're potentially affected.
+  if (deepSignalWriter === null) {
+    return false;
+  }
+
+  // `deepParentNode` is the most recent deep signal being written. If this node isn't also a child
+  // of that parent, then we can't guarantee we're not impacted by the write.
+  if (deepSignalWriter.parentNode !== node.parentNode) {
+    return false;
+  }
+
+  // Check whether the property signal we're interested in has potentially changed since we last
+  // read it. If it's dirty, or its version has been updated since our last read, then there's a
+  // chance our property of interest has changed. Since we need to know for sure which property
+  // we're interested in to check if we're affected, we have to assume we are.
+  if (
+    node.propertyNode !== undefined &&
+    (node.propertyNode.dirty || node.propertyNode.version !== node.lastPropertyValueVersion)
+  ) {
+    return false;
+  }
+
+  // We know for sure that `node.lastProperty` is the property we care about. If the same property
+  // got changed in our parent, though, we might still be affected.
+  if (deepSignalWriter.lastProperty === node.lastProperty) {
+    return false;
+  }
+
+  // We've proven that:
+  //  * another deep signal is changing a specific property of our parent signal
+  //  * it's not the property that we're reading
+  //
+  // There is the chance that our property signal changed since `lastProperty` was computed. If
+  // that were the case, we'd already be dirty from that notification, so it's safe to assume that
+  // under this circumstance, we're not affected.
+  return true;
+}
+
+export function setDeepSignalWriter(node: DeepSignalNode | null): DeepSignalNode | null {
+  const prev = deepSignalWriter;
+  deepSignalWriter = node;
+  return prev;
+}
+
+let deepSignalWriter: DeepSignalNode | null = null;