@tstdl/base 0.88.0-alpha1 → 0.88.0-alpha2

package/signals/implementation/effect.js

@@ -5,7 +5,7 @@
  * 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 { Watch } from './watch.js';
+import { watch } from './watch.js';
 /**
  * Tracks all effects registered within a given application and runs them via `flush`.
  */
@@ -13,12 +13,12 @@ export class EffectManager {
     all = new Set();
     queue = new Set();
     pendingFlush;
-    create(effectFn, { allowSignalWrites = false } = {}) {
-        const watch = new Watch(effectFn, (watch) => {
-            if (!this.all.has(watch)) {
+    create(effectFn, allowSignalWrites) {
+        const w = watch(effectFn, () => {
+            if (!this.all.has(w)) {
                 return;
             }
-            this.queue.add(watch);
+            this.queue.add(w);
             if (!this.pendingFlush) {
                 this.pendingFlush = true;
                 queueMicrotask(() => {
@@ -27,24 +27,25 @@ export class EffectManager {
                 });
             }
         }, allowSignalWrites);
-        this.all.add(watch);
-        watch.notify();
+        this.all.add(w);
+        // Effects start dirty.
+        w.notify();
         const destroy = () => {
-            watch.cleanup();
-            this.all.delete(watch);
-            this.queue.delete(watch);
+            w.cleanup();
+            this.all.delete(w);
+            this.queue.delete(w);
         };
         return {
             destroy
         };
     }
     flush() {
-        if (this.queue.size == 0) {
+        if (this.queue.size === 0) {
             return;
         }
-        for (const watch of this.queue) {
-            this.queue.delete(watch);
-            watch.run();
+        for (const w of this.queue) {
+            this.queue.delete(w);
+            w.run();
         }
     }
     get isQueueEmpty() {
@@ -56,5 +57,5 @@ const effectManager = new EffectManager();
  * Create a global `Effect` for the given reactive function.
  */
 export function effect(effectFn, options) {
-    return effectManager.create(effectFn, options);
+    return effectManager.create(effectFn, options?.allowSignalWrites ?? false);
 }

package/signals/implementation/graph.d.ts

@@ -5,104 +5,149 @@
  * 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
  */
+type Version = number & {
+    __brand: 'Version';
+};
 export declare function setActiveConsumer(consumer: ReactiveNode | null): ReactiveNode | null;
+export declare const REACTIVE_NODE: {
+    version: Version;
+    dirty: boolean;
+    producerNode: undefined;
+    producerLastReadVersion: undefined;
+    producerIndexOfThis: undefined;
+    nextProducerIndex: number;
+    liveConsumerNode: undefined;
+    liveConsumerIndexOfThis: undefined;
+    consumerAllowSignalWrites: boolean;
+    consumerIsAlwaysLive: boolean;
+    producerMustRecompute: () => boolean;
+    producerRecomputeValue: () => void;
+    consumerMarkedDirty: () => void;
+};
 /**
- * A node in the reactive graph.
+ * A producer and/or consumer which participates in the reactive graph.
  *
- * Nodes can be producers of reactive values, consumers of other reactive values, or both.
+ * Producer `ReactiveNode`s which are accessed when a consumer `ReactiveNode` is the
+ * `activeConsumer` are tracked as dependencies of that consumer.
  *
- * Producers are nodes that produce values, and can be depended upon by consumer nodes.
+ * Certain consumers are also tracked as "live" consumers and create edges in the other direction,
+ * from producer to consumer. These edges are used to propagate change notifications when a
+ * producer's value is updated.
  *
- * 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.
+ * A `ReactiveNode` may be both a producer and consumer.
  */
-export declare abstract class ReactiveNode {
-    private readonly id;
-    /**
-     * A cached weak reference to this node, which will be used in `ReactiveEdge`s.
-     */
-    private readonly ref;
-    /**
-     * Edges to producers on which this node depends (in its consumer capacity).
-     */
-    private readonly producers;
-    /**
-     * Edges to consumers on which this node depends (in its producer capacity).
-     */
-    private readonly consumers;
+export interface ReactiveNode {
     /**
-     * Monotonically increasing counter representing a version of this `Consumer`'s
-     * dependencies.
-     */
-    protected trackingVersion: number;
-    /**
-     * Monotonically increasing counter which increases when the value of this `Producer`
-     * semantically changes.
+     * Version of the value that this node produces.
+     *
+     * This is incremented whenever a new value is produced by this node which is not equal to the
+     * previous value (by whatever definition of equality is in use).
      */
-    protected valueVersion: number;
+    version: Version;
     /**
-     * Whether signal writes should be allowed while this `ReactiveNode` is the current consumer.
+     * Whether this node (in its consumer capacity) is dirty.
+     *
+     * Only live consumers become dirty, when receiving a change notification from a dependency
+     * producer.
      */
-    protected abstract readonly consumerAllowSignalWrites: boolean;
+    dirty: boolean;
     /**
-     * Called for consumers whenever one of their dependencies notifies that it might have a new
-     * value.
+     * Producers which are dependencies of this consumer.
+     *
+     * Uses the same indices as the `producerLastReadVersion` and `producerIndexOfThis` arrays.
      */
-    protected abstract onConsumerDependencyMayHaveChanged(): void;
+    producerNode: ReactiveNode[] | undefined;
     /**
-     * Called for producers when a dependent consumer is checking if the producer's value has actually
-     * changed.
+     * `Version` of the value last read by a given producer.
+     *
+     * Uses the same indices as the `producerNode` and `producerIndexOfThis` arrays.
      */
-    protected abstract onProducerUpdateValueVersion(): void;
+    producerLastReadVersion: Version[] | undefined;
     /**
-     * Polls dependencies of a consumer to determine if they have actually changed.
+     * Index of `this` (consumer) in each producer's `liveConsumers` array.
+     *
+     * This value is only meaningful if this node is live (`liveConsumers.length > 0`). Otherwise
+     * these indices are stale.
      *
-     * 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.
+     * Uses the same indices as the `producerNode` and `producerLastReadVersion` arrays.
      */
-    protected consumerPollProducersForChange(): boolean;
+    producerIndexOfThis: number[] | undefined;
     /**
-     * Notify all consumers of this producer that its value may have changed.
+     * Index into the producer arrays that the next dependency of this node as a consumer will use.
+     *
+     * This index is zeroed before this node as a consumer begins executing. When a producer is read,
+     * it gets inserted into the producers arrays at this index. There may be an existing dependency
+     * in this location which may or may not match the incoming producer, depending on whether the
+     * same producers were read in the same order as the last computation.
      */
-    protected producerMayHaveChanged(): void;
+    nextProducerIndex: number;
     /**
-     * Mark that this producer node has been accessed in the current reactive context.
+     * Array of consumers of this producer that are "live" (they require push notifications).
+     *
+     * `liveConsumerNode.length` is effectively our reference count for this node.
      */
-    protected producerAccessed(): void;
+    liveConsumerNode: ReactiveNode[] | undefined;
     /**
-     * Whether this consumer currently has any producers registered.
+     * Index of `this` (producer) in each consumer's `producerNode` array.
+     *
+     * Uses the same indices as the `liveConsumerNode` array.
      */
-    protected get hasProducers(): boolean;
+    liveConsumerIndexOfThis: number[] | undefined;
     /**
-     * Whether this `ReactiveNode` in its producer capacity is currently allowed to initiate updates,
-     * based on the current consumer context.
+     * Whether writes to signals are allowed when this consumer is the `activeConsumer`.
+     *
+     * This is used to enforce guardrails such as preventing writes to writable signals in the
+     * computation function of computed signals, which is supposed to be pure.
      */
-    protected get producerUpdatesAllowed(): boolean;
+    consumerAllowSignalWrites: boolean;
+    readonly consumerIsAlwaysLive: boolean;
     /**
-     * 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`.
+     * Tracks whether producers need to recompute their value independently of the reactive graph (for
+     * example, if no initial value has been computed).
      */
-    private producerPollStatus;
+    producerMustRecompute(node: unknown): boolean;
+    producerRecomputeValue(node: unknown): void;
+    consumerMarkedDirty(node: unknown): void;
 }
+/**
+ * Called by implementations when a producer's signal is read.
+ */
+export declare function producerAccessed(node: ReactiveNode): void;
+/**
+ * Ensure this producer's `version` is up-to-date.
+ */
+export declare function producerUpdateValueVersion(node: ReactiveNode): void;
+/**
+ * Propagate a dirty notification to live consumers of this producer.
+ */
+export declare function producerNotifyConsumers(node: ReactiveNode): void;
+/**
+ * Whether this `ReactiveNode` in its producer capacity is currently allowed to initiate updates,
+ * based on the current consumer context.
+ */
+export declare function producerUpdatesAllowed(): boolean;
+export declare function consumerMarkDirty(node: ReactiveNode): void;
+/**
+ * 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 declare function consumerBeforeComputation(node: ReactiveNode | null): ReactiveNode | null;
+/**
+ * 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 declare function consumerAfterComputation(node: ReactiveNode | null, prevConsumer: ReactiveNode | null): void;
+/**
+ * Determine whether this consumer has any dependencies which have changed since the last time
+ * they were read.
+ */
+export declare function consumerPollProducersForChange(node: ReactiveNode): boolean;
+/**
+ * Disconnect this consumer from the graph.
+ */
+export declare function consumerDestroy(node: ReactiveNode): void;
+export {};