@tstdl/base 0.88.0-alpha1 → 0.88.0-alpha3

package/signals/implementation/graph.js

@@ -6,182 +6,261 @@
  * found in the LICENSE file at https://angular.io/license
  */
 /**
- * Counter tracking the next `ProducerId` or `ConsumerId`.
- */
-let _nextReactiveId = 0;
-/**
- * Tracks the currently active reactive consumer (or `null` if there is no active
- * consumer).
+ * The currently active consumer `ReactiveNode`, if running code in a reactive context.
+ *
+ * Change this via `setActiveConsumer`.
  */
 let activeConsumer = null;
-/**
- * Whether the graph is currently propagating change notifications.
- */
 let inNotificationPhase = false;
 export function setActiveConsumer(consumer) {
     const prev = activeConsumer;
     activeConsumer = consumer;
     return prev;
 }
+export const REACTIVE_NODE = {
+    version: 0,
+    dirty: false,
+    producerNode: undefined,
+    producerLastReadVersion: undefined,
+    producerIndexOfThis: undefined,
+    nextProducerIndex: 0,
+    liveConsumerNode: undefined,
+    liveConsumerIndexOfThis: undefined,
+    consumerAllowSignalWrites: false,
+    consumerIsAlwaysLive: false,
+    producerMustRecompute: () => false,
+    producerRecomputeValue: () => { },
+    consumerMarkedDirty: () => { },
+};
 /**
- * A node in the reactive graph.
- *
- * Nodes can be producers of reactive values, consumers of other reactive values, or both.
- *
- * Producers are nodes that produce values, and can be depended upon by consumer nodes.
- *
- * Producers expose a monotonic `valueVersion` counter, and are responsible for incrementing this
- * version when their value semantically changes. Some producers may produce their values lazily and
- * thus at times need to be polled for potential updates to their value (and by extension their
- * `valueVersion`). This is accomplished via the `onProducerUpdateValueVersion` method for
- * implemented by producers, which should perform whatever calculations are necessary to ensure
- * `valueVersion` is up to date.
- *
- * Consumers are nodes that depend on the values of producers and are notified when those values
- * might have changed.
- *
- * Consumers do not wrap the reads they consume themselves, but rather can be set as the active
- * reader via `setActiveConsumer`. Reads of producers that happen while a consumer is active will
- * result in those producers being added as dependencies of that consumer node.
- *
- * The set of dependencies of a consumer is dynamic. Implementers expose a monotonically increasing
- * `trackingVersion` counter, which increments whenever the consumer is about to re-run any reactive
- * reads it needs and establish a new set of dependencies as a result.
- *
- * Producers store the last `trackingVersion` they've seen from `Consumer`s which have read them.
- * This allows a producer to identify whether its record of the dependency is current or stale, by
- * comparing the consumer's `trackingVersion` to the version at which the dependency was
- * last observed.
+ * Called by implementations when a producer's signal is read.
  */
-export class ReactiveNode {
-    id = _nextReactiveId++;
-    /**
-     * A cached weak reference to this node, which will be used in `ReactiveEdge`s.
-     */
-    ref = new WeakRef(this);
-    /**
-     * Edges to producers on which this node depends (in its consumer capacity).
-     */
-    producers = new Map();
-    /**
-     * Edges to consumers on which this node depends (in its producer capacity).
-     */
-    consumers = new Map();
-    /**
-     * Monotonically increasing counter representing a version of this `Consumer`'s
-     * dependencies.
-     */
-    trackingVersion = 0;
-    /**
-     * Monotonically increasing counter which increases when the value of this `Producer`
-     * semantically changes.
-     */
-    valueVersion = 0;
-    /**
-     * Polls dependencies of a consumer to determine if they have actually changed.
-     *
-     * If this returns `false`, then even though the consumer may have previously been notified of a
-     * change, the values of its dependencies have not actually changed and the consumer should not
-     * rerun any reactions.
-     */
-    consumerPollProducersForChange() {
-        for (const [producerId, edge] of this.producers) {
-            const producer = edge.producerNode.deref();
-            // On Safari < 16.1 deref can return null, we need to check for null also.
-            // See https://github.com/WebKit/WebKit/commit/44c15ba58912faab38b534fef909dd9e13e095e0
-            if (producer == null || edge.atTrackingVersion !== this.trackingVersion) {
-                // This dependency edge is stale, so remove it.
-                this.producers.delete(producerId);
-                producer?.consumers.delete(this.id);
-                continue;
-            }
-            if (producer.producerPollStatus(edge.seenValueVersion)) {
-                // One of the dependencies reports a real value change.
-                return true;
-            }
+export function producerAccessed(node) {
+    if (inNotificationPhase) {
+        throw new Error('Assertion error: signal read during notification phase');
+    }
+    if (activeConsumer === null) {
+        // Accessed outside of a reactive context, so nothing to record.
+        return;
+    }
+    // This producer is the `idx`th dependency of `activeConsumer`.
+    const idx = activeConsumer.nextProducerIndex++;
+    assertConsumerNode(activeConsumer);
+    if (idx < activeConsumer.producerNode.length && activeConsumer.producerNode[idx] !== node) {
+        // There's been a change in producers since the last execution of `activeConsumer`.
+        // `activeConsumer.producerNode[idx]` holds a stale dependency which will be be removed and
+        // replaced with `this`.
+        //
+        // If `activeConsumer` isn't live, then this is a no-op, since we can replace the producer in
+        // `activeConsumer.producerNode` directly. However, if `activeConsumer` is live, then we need
+        // to remove it from the stale producer's `liveConsumer`s.
+        if (consumerIsLive(activeConsumer)) {
+            const staleProducer = activeConsumer.producerNode[idx];
+            producerRemoveLiveConsumerAtIndex(staleProducer, activeConsumer.producerIndexOfThis[idx]);
+            // At this point, the only record of `staleProducer` is the reference at
+            // `activeConsumer.producerNode[idx]` which will be overwritten below.
         }
-        // No dependency reported a real value change, so the `Consumer` has also not been
-        // impacted.
-        return false;
-    }
-    /**
-     * Notify all consumers of this producer that its value may have changed.
-     */
-    producerMayHaveChanged() {
-        // Prevent signal reads when we're updating the graph
-        const prev = inNotificationPhase;
-        inNotificationPhase = true;
-        try {
-            for (const [consumerId, edge] of this.consumers) {
-                const consumer = edge.consumerNode.deref();
-                // On Safari < 16.1 deref can return null, we need to check for null also.
-                // See https://github.com/WebKit/WebKit/commit/44c15ba58912faab38b534fef909dd9e13e095e0
-                if (consumer == null || consumer.trackingVersion !== edge.atTrackingVersion) {
-                    this.consumers.delete(consumerId);
-                    consumer?.producers.delete(this.id);
-                    continue;
-                }
-                consumer.onConsumerDependencyMayHaveChanged();
+    }
+    if (activeConsumer.producerNode[idx] !== node) {
+        // We're a new dependency of the consumer (at `idx`).
+        activeConsumer.producerNode[idx] = node;
+        // If the active consumer is live, then add it as a live consumer. If not, then use 0 as a
+        // placeholder value.
+        activeConsumer.producerIndexOfThis[idx] =
+            consumerIsLive(activeConsumer) ? producerAddLiveConsumer(node, activeConsumer, idx) : 0;
+    }
+    activeConsumer.producerLastReadVersion[idx] = node.version;
+}
+/**
+ * Ensure this producer's `version` is up-to-date.
+ */
+export function producerUpdateValueVersion(node) {
+    if (consumerIsLive(node) && !node.dirty) {
+        // A live consumer will be marked dirty by producers, so a clean state means that its version
+        // is guaranteed to be up-to-date.
+        return;
+    }
+    if (!node.producerMustRecompute(node) && !consumerPollProducersForChange(node)) {
+        // None of our producers report a change since the last time they were read, so no
+        // recomputation of our value is necessary, and we can consider ourselves clean.
+        node.dirty = false;
+        return;
+    }
+    node.producerRecomputeValue(node);
+    // After recomputing the value, we're no longer dirty.
+    node.dirty = false;
+}
+/**
+ * Propagate a dirty notification to live consumers of this producer.
+ */
+export function producerNotifyConsumers(node) {
+    if (node.liveConsumerNode === undefined) {
+        return;
+    }
+    // Prevent signal reads when we're updating the graph
+    const prev = inNotificationPhase;
+    inNotificationPhase = true;
+    try {
+        for (const consumer of node.liveConsumerNode) {
+            if (!consumer.dirty) {
+                consumerMarkDirty(consumer);
             }
         }
-        finally {
-            inNotificationPhase = prev;
+    }
+    finally {
+        inNotificationPhase = prev;
+    }
+}
+/**
+ * Whether this `ReactiveNode` in its producer capacity is currently allowed to initiate updates,
+ * based on the current consumer context.
+ */
+export function producerUpdatesAllowed() {
+    return activeConsumer?.consumerAllowSignalWrites !== false;
+}
+export function consumerMarkDirty(node) {
+    node.dirty = true;
+    producerNotifyConsumers(node);
+    node.consumerMarkedDirty?.(node);
+}
+/**
+ * Prepare this consumer to run a computation in its reactive context.
+ *
+ * Must be called by subclasses which represent reactive computations, before those computations
+ * begin.
+ */
+export function consumerBeforeComputation(node) {
+    node && (node.nextProducerIndex = 0);
+    return setActiveConsumer(node);
+}
+/**
+ * Finalize this consumer's state after a reactive computation has run.
+ *
+ * Must be called by subclasses which represent reactive computations, after those computations
+ * have finished.
+ */
+export function consumerAfterComputation(node, prevConsumer) {
+    setActiveConsumer(prevConsumer);
+    if (!node || node.producerNode === undefined || node.producerIndexOfThis === undefined ||
+        node.producerLastReadVersion === undefined) {
+        return;
+    }
+    if (consumerIsLive(node)) {
+        // For live consumers, we need to remove the producer -> consumer edge for any stale producers
+        // which weren't dependencies after the recomputation.
+        for (let i = node.nextProducerIndex; i < node.producerNode.length; i++) {
+            producerRemoveLiveConsumerAtIndex(node.producerNode[i], node.producerIndexOfThis[i]);
         }
     }
-    /**
-     * Mark that this producer node has been accessed in the current reactive context.
-     */
-    producerAccessed() {
-        if (inNotificationPhase) {
-            throw new Error(`Assertion error: signal read during notification phase`);
+    // Truncate the producer tracking arrays.
+    for (let i = node.nextProducerIndex; i < node.producerNode.length; i++) {
+        node.producerNode.pop();
+        node.producerLastReadVersion.pop();
+        node.producerIndexOfThis.pop();
+    }
+}
+/**
+ * Determine whether this consumer has any dependencies which have changed since the last time
+ * they were read.
+ */
+export function consumerPollProducersForChange(node) {
+    assertConsumerNode(node);
+    // Poll producers for change.
+    for (let i = 0; i < node.producerNode.length; i++) {
+        const producer = node.producerNode[i];
+        const seenVersion = node.producerLastReadVersion[i];
+        // First check the versions. A mismatch means that the producer's value is known to have
+        // changed since the last time we read it.
+        if (seenVersion !== producer.version) {
+            return true;
         }
-        if (activeConsumer === null) {
-            return;
+        // The producer's version is the same as the last time we read it, but it might itself be
+        // stale. Force the producer to recompute its version (calculating a new value if necessary).
+        producerUpdateValueVersion(producer);
+        // Now when we do this check, `producer.version` is guaranteed to be up to date, so if the
+        // versions still match then it has not changed since the last time we read it.
+        if (seenVersion !== producer.version) {
+            return true;
         }
-        // Either create or update the dependency `Edge` in both directions.
-        let edge = activeConsumer.producers.get(this.id);
-        if (edge === undefined) {
-            edge = {
-                consumerNode: activeConsumer.ref,
-                producerNode: this.ref,
-                seenValueVersion: this.valueVersion,
-                atTrackingVersion: activeConsumer.trackingVersion,
-            };
-            activeConsumer.producers.set(this.id, edge);
-            this.consumers.set(activeConsumer.id, edge);
+    }
+    return false;
+}
+/**
+ * Disconnect this consumer from the graph.
+ */
+export function consumerDestroy(node) {
+    assertConsumerNode(node);
+    if (consumerIsLive(node)) {
+        // Drop all connections from the graph to this node.
+        for (let i = 0; i < node.producerNode.length; i++) {
+            producerRemoveLiveConsumerAtIndex(node.producerNode[i], node.producerIndexOfThis[i]);
         }
-        else {
-            edge.seenValueVersion = this.valueVersion;
-            edge.atTrackingVersion = activeConsumer.trackingVersion;
+    }
+    // Truncate all the arrays to drop all connection from this node to the graph.
+    node.producerNode.length = node.producerLastReadVersion.length = node.producerIndexOfThis.length =
+        0;
+    if (node.liveConsumerNode) {
+        node.liveConsumerNode.length = node.liveConsumerIndexOfThis.length = 0;
+    }
+}
+/**
+ * Add `consumer` as a live consumer of this node.
+ *
+ * Note that this operation is potentially transitive. If this node becomes live, then it becomes
+ * a live consumer of all of its current producers.
+ */
+function producerAddLiveConsumer(node, consumer, indexOfThis) {
+    assertProducerNode(node);
+    assertConsumerNode(node);
+    if (node.liveConsumerNode.length === 0) {
+        // When going from 0 to 1 live consumers, we become a live consumer to our producers.
+        for (let i = 0; i < node.producerNode.length; i++) {
+            node.producerIndexOfThis[i] = producerAddLiveConsumer(node.producerNode[i], node, i);
         }
     }
-    /**
-     * Whether this consumer currently has any producers registered.
-     */
-    get hasProducers() {
-        return this.producers.size > 0;
-    }
-    /**
-     * Whether this `ReactiveNode` in its producer capacity is currently allowed to initiate updates,
-     * based on the current consumer context.
-     */
-    get producerUpdatesAllowed() {
-        return activeConsumer?.consumerAllowSignalWrites !== false;
-    }
-    /**
-     * Checks if a `Producer` has a current value which is different than the value
-     * last seen at a specific version by a `Consumer` which recorded a dependency on
-     * this `Producer`.
-     */
-    producerPollStatus(lastSeenValueVersion) {
-        // `producer.valueVersion` may be stale, but a mismatch still means that the value
-        // last seen by the `Consumer` is also stale.
-        if (this.valueVersion !== lastSeenValueVersion) {
-            return true;
+    node.liveConsumerIndexOfThis.push(indexOfThis);
+    return node.liveConsumerNode.push(consumer) - 1;
+}
+/**
+ * Remove the live consumer at `idx`.
+ */
+function producerRemoveLiveConsumerAtIndex(node, idx) {
+    assertProducerNode(node);
+    assertConsumerNode(node);
+    if (node.liveConsumerNode.length === 1) {
+        // When removing the last live consumer, we will no longer be live. We need to remove
+        // ourselves from our producers' tracking (which may cause consumer-producers to lose
+        // liveness as well).
+        for (let i = 0; i < node.producerNode.length; i++) {
+            producerRemoveLiveConsumerAtIndex(node.producerNode[i], node.producerIndexOfThis[i]);
         }
-        // Trigger the `Producer` to update its `valueVersion` if necessary.
-        this.onProducerUpdateValueVersion();
-        // At this point, we can trust `producer.valueVersion`.
-        return this.valueVersion !== lastSeenValueVersion;
     }
+    // Move the last value of `liveConsumers` into `idx`. Note that if there's only a single
+    // live consumer, this is a no-op.
+    const lastIdx = node.liveConsumerNode.length - 1;
+    node.liveConsumerNode[idx] = node.liveConsumerNode[lastIdx];
+    node.liveConsumerIndexOfThis[idx] = node.liveConsumerIndexOfThis[lastIdx];
+    // Truncate the array.
+    node.liveConsumerNode.length--;
+    node.liveConsumerIndexOfThis.length--;
+    // If the index is still valid, then we need to fix the index pointer from the producer to this
+    // consumer, and update it from `lastIdx` to `idx` (accounting for the move above).
+    if (idx < node.liveConsumerNode.length) {
+        const idxProducer = node.liveConsumerIndexOfThis[idx];
+        const consumer = node.liveConsumerNode[idx];
+        assertConsumerNode(consumer);
+        consumer.producerIndexOfThis[idxProducer] = idx;
+    }
+}
+function consumerIsLive(node) {
+    return node.consumerIsAlwaysLive || (node?.liveConsumerNode?.length ?? 0) > 0;
+}
+function assertConsumerNode(node) {
+    node.producerNode ??= [];
+    node.producerIndexOfThis ??= [];
+    node.producerLastReadVersion ??= [];
+}
+function assertProducerNode(node) {
+    node.liveConsumerNode ??= [];
+    node.liveConsumerIndexOfThis ??= [];
 }

package/signals/implementation/signal.js

@@ -5,9 +5,9 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import { createSignalFromFunction, defaultEquals } from './api.js';
+import { SIGNAL, defaultEquals } from './api.js';
 import { throwInvalidWriteToSignalError } from './errors.js';
-import { ReactiveNode } from './graph.js';
+import { REACTIVE_NODE, producerAccessed, producerNotifyConsumers, producerUpdatesAllowed } from './graph.js';
 /**
  * If set, called after `WritableSignal`s are updated.
  *
@@ -15,89 +15,22 @@ import { ReactiveNode } from './graph.js';
  * of setting a signal.
  */
 let postSignalSetFn = null;
-class WritableSignalImpl extends ReactiveNode {
-    value;
-    equal;
-    readonlySignal;
-    consumerAllowSignalWrites = false;
-    constructor(value, equal) {
-        super();
-        this.value = value;
-        this.equal = equal;
-    }
-    onConsumerDependencyMayHaveChanged() {
-        // This never happens for writable signals as they're not consumers.
-    }
-    onProducerUpdateValueVersion() {
-        // Writable signal value versions are always up to date.
-    }
-    /**
-     * Directly update the value of the signal to a new value, which may or may not be
-     * equal to the previous.
-     *
-     * In the event that `newValue` is semantically equal to the current value, `set` is
-     * a no-op.
-     */
-    set(newValue) {
-        if (!this.producerUpdatesAllowed) {
-            throwInvalidWriteToSignalError();
-        }
-        if (!this.equal(this.value, newValue)) {
-            this.value = newValue;
-            this.valueVersion++;
-            this.producerMayHaveChanged();
-            postSignalSetFn?.();
-        }
-    }
-    /**
-     * Derive a new value for the signal from its current value using the `updater` function.
-     *
-     * This is equivalent to calling `set` on the result of running `updater` on the current
-     * value.
-     */
-    update(updater) {
-        if (!this.producerUpdatesAllowed) {
-            throwInvalidWriteToSignalError();
-        }
-        this.set(updater(this.value));
-    }
-    /**
-     * Calls `mutator` on the current value and assumes that it has been mutated.
-     */
-    mutate(mutator) {
-        if (!this.producerUpdatesAllowed) {
-            throwInvalidWriteToSignalError();
-        }
-        // Mutate bypasses equality checks as it's by definition changing the value.
-        mutator(this.value);
-        this.valueVersion++;
-        this.producerMayHaveChanged();
-        postSignalSetFn?.();
-    }
-    asReadonly() {
-        if (this.readonlySignal === undefined) {
-            this.readonlySignal = createSignalFromFunction(this, () => this.signal());
-        }
-        return this.readonlySignal;
-    }
-    signal() {
-        this.producerAccessed();
-        return this.value;
-    }
-}
 /**
  * Create a `Signal` that can be set or updated directly.
  */
 export function signal(initialValue, options) {
-    const signalNode = new WritableSignalImpl(initialValue, options?.equal ?? defaultEquals);
-    // Casting here is required for g3, as TS inference behavior is slightly different between our
-    // version/options and g3's.
-    const signalFn = createSignalFromFunction(signalNode, signalNode.signal.bind(signalNode), {
-        set: signalNode.set.bind(signalNode),
-        update: signalNode.update.bind(signalNode),
-        mutate: signalNode.mutate.bind(signalNode),
-        asReadonly: signalNode.asReadonly.bind(signalNode)
-    });
+    const node = Object.create(SIGNAL_NODE);
+    node.value = initialValue;
+    options?.equal && (node.equal = options.equal);
+    function signalFn() {
+        producerAccessed(node);
+        return node.value;
+    }
+    signalFn.set = signalSetFn;
+    signalFn.update = signalUpdateFn;
+    signalFn.mutate = signalMutateFn;
+    signalFn.asReadonly = signalAsReadonlyFn;
+    signalFn[SIGNAL] = node;
     return signalFn;
 }
 export function setPostSignalSetFn(fn) {
@@ -105,3 +38,47 @@ export function setPostSignalSetFn(fn) {
     postSignalSetFn = fn;
     return prev;
 }
+const SIGNAL_NODE = {
+    ...REACTIVE_NODE,
+    equal: defaultEquals,
+    readonlyFn: undefined,
+};
+function signalValueChanged(node) {
+    node.version++;
+    producerNotifyConsumers(node);
+    postSignalSetFn?.();
+}
+function signalSetFn(newValue) {
+    const node = this[SIGNAL];
+    if (!producerUpdatesAllowed()) {
+        throwInvalidWriteToSignalError();
+    }
+    if (!node.equal(node.value, newValue)) {
+        node.value = newValue;
+        signalValueChanged(node);
+    }
+}
+function signalUpdateFn(updater) {
+    if (!producerUpdatesAllowed()) {
+        throwInvalidWriteToSignalError();
+    }
+    signalSetFn.call(this, updater(this[SIGNAL].value));
+}
+function signalMutateFn(mutator) {
+    const node = this[SIGNAL];
+    if (!producerUpdatesAllowed()) {
+        throwInvalidWriteToSignalError();
+    }
+    // Mutate bypasses equality checks as it's by definition changing the value.
+    mutator(node.value);
+    signalValueChanged(node);
+}
+function signalAsReadonlyFn() {
+    const node = this[SIGNAL];
+    if (node.readonlyFn === undefined) {
+        const readonlyFn = () => this();
+        readonlyFn[SIGNAL] = node;
+        node.readonlyFn = readonlyFn;
+    }
+    return node.readonlyFn;
+}

package/signals/implementation/watch.d.ts

@@ -5,7 +5,6 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import { ReactiveNode } from './graph.js';
 /**
  * A cleanup function that can be optionally registered from the watch logic. If registered, the
  * cleanup logic runs before the next watch execution.
@@ -15,24 +14,8 @@ export type WatchCleanupFn = () => void;
  * A callback passed to the watch function that makes it possible to register cleanup logic.
  */
 export type WatchCleanupRegisterFn = (cleanupFn: WatchCleanupFn) => void;
-/**
- * Watches a reactive expression and allows it to be scheduled to re-run
- * when any dependencies notify of a change.
- *
- * `Watch` doesn't run reactive expressions itself, but relies on a consumer-
- * provided scheduling operation to coordinate calling `Watch.run()`.
- */
-export declare class Watch extends ReactiveNode {
-    private watch;
-    private schedule;
-    protected readonly consumerAllowSignalWrites: boolean;
-    private dirty;
-    private cleanupFn;
-    private registerOnCleanup;
-    constructor(watch: (onCleanup: WatchCleanupRegisterFn) => void, schedule: (watch: Watch) => void, allowSignalWrites: boolean);
+export interface Watch {
     notify(): void;
-    protected onConsumerDependencyMayHaveChanged(): void;
-    protected onProducerUpdateValueVersion(): void;
     /**
      * Execute the reactive expression in the context of this `Watch` consumer.
      *
@@ -42,3 +25,4 @@ export declare class Watch extends ReactiveNode {
     run(): void;
     cleanup(): void;
 }
+export declare function watch(fn: (onCleanup: WatchCleanupRegisterFn) => void, schedule: (watch: Watch) => void, allowSignalWrites: boolean): Watch;