synstate 4.0.0 → 5.0.0

package/src/core/class/manager-observable-class.mts

@@ -1,137 +1,32 @@
 // @sumi-expect-error-file classes/no-class
 // @sumi-expect-error-file banned-syntax/no-this
 // @sumi-expect-error-file functions/prefer-arrow-function
-// @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
-import type { Optional } from 'ts-data-forge';
-import type { MutableSet } from 'ts-type-forge';
-import type { ManagerObservableKind, UpdateToken } from '../types/index.mjs';
-import { issueUpdateToken } from '../utils/index.mjs';
+import type { ManagerObservableKind } from '../types/index.mjs';
 import { ObservableBaseClass } from './observable-base-class.mjs';
-import type { ChildNode, ManagerNode } from './observable-node.mjs';
-import { beginPropagation, endPropagation } from './propagation-state.mjs';
+import {
+  beginPropagation,
+  closeUpdate,
+  drainUpdate,
+  endPropagation,
+  openUpdate,
+} from './propagation-state.mjs';
 
 /**
  * The base of the observables that start updates of their own: a root, and
  * an async child (`debounce`, `switchMap`), which emits later than its
- * parents do. Every descendant registers to the managers it is reached from,
- * and an update reaches them in ascending depth, so that each sees its
- * parents' values of that update (no glitch).
+ * parents do. Its update visits, shallowest first, the nodes its value
+ * reaches: each node that emits puts its children in the update's queue
+ * (`propagation-state.mts`), so that each sees its parents' values of that
+ * update (no glitch) and a node no value reached is not visited.
  */
 export class ManagerObservableClass<
   A,
   Kind extends ManagerObservableKind,
   Depth extends number,
 > extends ObservableBaseClass<A, Kind, Depth> {
-  /**
-   * The descendants, by depth: the set at index `i` holds those at
-   * `depth + 1 + i`, in the order they registered. Depths below a live node
-   * never skip one (every live node has a live parent one level up), so the
-   * array has few holes; a hole is `undefined`, never a gap left for V8 to
-   * treat as a holey array.
-   *
-   * An update walks this array and its sets in place. Adding or removing a
-   * node is O(1) and there is no flat order to rebuild; only the first node
-   * of a depth replaces the array with a longer copy. A node deleted during
-   * the walk is skipped by the set's iterator; a node registered during it is
-   * also put in `#mut_joinedDuringUpdate` and skipped, so an update visits the
-   * nodes that existed when it began.
-   */
-  #mut_propagationOrder: readonly (MutableSet<ChildNode> | undefined)[];
-
-  /** Whether this node is propagating an update of its own. */
-  #mut_isPropagating: boolean;
-
-  /**
-   * The descendants that registered while this node propagated the update
-   * under way, which that update does not visit; made when the first one
-   * arrives. Kept on the manager rather than in a module, so that it also
-   * holds for a node another copy of synstate registered.
-   */
-  #mut_joinedDuringUpdate: MutableSet<ChildNode> | undefined;
-
-  /** The managers this node's descendants register to: itself. */
-  readonly managers: readonly ManagerNode[];
-
-  constructor(
-    config: Readonly<{
-      kind: Kind;
-      depth: Depth;
-      initialValue: Optional<A>;
-    }>,
-  ) {
-    super(config);
-
-    this.managers = [this];
-
-    this.#mut_propagationOrder = [];
-
-    this.#mut_isPropagating = false;
-
-    this.#mut_joinedDuringUpdate = undefined;
-  }
-
-  /**
-   * Runs `tryUpdate` on the descendants, shallowest first, skipping those
-   * registered after this update began.
-   */
-  #propagate(updateToken: UpdateToken): void {
-    for (const bucket of this.#mut_propagationOrder) {
-      if (bucket !== undefined) {
-        for (const c of bucket) {
-          // Read for each node, since the set is made when the first joins.
-          if (this.#mut_joinedDuringUpdate?.has(c) !== true) {
-            c.tryUpdate(updateToken);
-          }
-        }
-      }
-    }
-  }
-
-  addDescendant(child: ChildNode): void {
-    const descendants = this.#mut_propagationOrder;
-
-    const index = child.depth - this.depth - 1;
-
-    const mut_bucket = descendants[index];
-
-    if (mut_bucket === undefined) {
-      // The first node of its depth: rare, so the array is copied rather than
-      // written, which also leaves a walk already under way on the old one.
-      this.#mut_propagationOrder = Array.from(
-        { length: Math.max(descendants.length, index + 1) },
-        (_, i) => (i === index ? new Set([child]) : descendants[i]),
-      );
-    } else {
-      mut_bucket.add(child);
-    }
-
-    if (!this.#mut_isPropagating) {
-      return;
-    }
-
-    this.#mut_joinedDuringUpdate ??= new Set();
-
-    this.#mut_joinedDuringUpdate.add(child);
-  }
-
-  deleteDescendant(child: ChildNode): void {
-    // An emptied set stays, to be reused by the next node of its depth.
-    this.#mut_propagationOrder[child.depth - this.depth - 1]?.delete(child);
-  }
-
   /** Emits `nextValue` and propagates it to the descendants. */
   protected startUpdate(nextValue: A): void {
-    const updateToken = issueUpdateToken();
-
-    // A write to this same manager from inside its own update starts an inner
-    // one; what joins during it joined during the outer one too.
-    const wasPropagating = this.#mut_isPropagating;
-
-    const joinedBefore = this.#mut_joinedDuringUpdate;
-
-    this.#mut_isPropagating = true;
-
-    this.#mut_joinedDuringUpdate = undefined;
+    const updateToken = openUpdate(this.depth);
 
     beginPropagation(updateToken);
 
@@ -142,23 +37,9 @@ export class ManagerObservableClass<
     try {
       this.setNext(nextValue, updateToken);
 
-      this.#propagate(updateToken);
+      drainUpdate(updateToken);
     } finally {
-      // Widened: TypeScript would take the write above for the value.
-      const joinedNow = this.#mut_joinedDuringUpdate as
-        MutableSet<ChildNode> | undefined;
-
-      this.#mut_isPropagating = wasPropagating;
-
-      this.#mut_joinedDuringUpdate = joinedBefore;
-
-      if (wasPropagating && joinedNow !== undefined) {
-        this.#mut_joinedDuringUpdate ??= new Set();
-
-        for (const c of joinedNow) {
-          this.#mut_joinedDuringUpdate.add(c);
-        }
-      }
+      closeUpdate(updateToken);
 
       endPropagation();
     }

package/src/core/class/observable-base-class.mts

@@ -29,6 +29,7 @@ import {
   type ScopeInternals,
 } from '../utils/index.mjs';
 import type { ChildNode } from './observable-node.mjs';
+import { enqueueChildren } from './propagation-state.mjs';
 
 /**
  * The base of every observable, and the reason an observable is a class.
@@ -64,6 +65,7 @@ export class ObservableBaseClass<
   #mut_children: MutableSet<ChildNode> | undefined;
   #mut_subscribers: MutableSet<Subscriber<A>> | undefined;
   #mut_scope: ScopeInternals | undefined;
+  #mut_queuedFor: UpdateToken | undefined;
   readonly kind: Kind;
   readonly depth: Depth;
   declare readonly [observableBrand]: true;
@@ -87,6 +89,8 @@ export class ObservableBaseClass<
 
     this.#mut_updateToken = notUpdatedYet;
 
+    this.#mut_queuedFor = undefined;
+
     this.#mut_children = undefined;
 
     this.#mut_subscribers = undefined;
@@ -130,6 +134,14 @@ export class ObservableBaseClass<
     return false;
   }
 
+  get queuedFor(): UpdateToken | undefined {
+    return this.#mut_queuedFor;
+  }
+
+  setQueuedFor(updateToken: UpdateToken): void {
+    this.#mut_queuedFor = updateToken;
+  }
+
   addChild(child: ChildNode): void {
     // A set, not an array: a completed child removes itself, and that has to
     // be O(1) for a UI that creates and completes derived nodes on every mount.
@@ -144,12 +156,21 @@ export class ObservableBaseClass<
     this.#mut_children?.delete(child);
   }
 
-  /** Stores `nextValue` as the current value and notifies subscribers. */
+  /**
+   * Stores `nextValue` as the current value, queues the children for the
+   * update `updateToken`, and notifies subscribers. The children are queued
+   * first, so that a child a subscriber creates, which starts from this
+   * value, is not visited for it again.
+   */
   protected setNext(nextValue: A, updateToken: UpdateToken): void {
     this.#mut_updateToken = updateToken;
 
     this.#mut_snapshot = Optional.some(nextValue);
 
+    if (this.#mut_children !== undefined) {
+      enqueueChildren(this.#mut_children, updateToken);
+    }
+
     if (this.#mut_subscribers !== undefined) {
       for (const s of this.#mut_subscribers) {
         s.onNext(nextValue);
@@ -248,7 +269,7 @@ export class ObservableBaseClass<
   // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   protected teardown(): void {}
 
-  /** Takes a completed child out of its parents' and managers' lists. */
+  /** Takes a completed child out of its parents' lists. */
   // eslint-disable-next-line @typescript-eslint/class-methods-use-this
   protected detach(): void {}
 

package/src/core/class/observable-node.mts

@@ -20,11 +20,12 @@ type NodeInternals = Readonly<{
   deleteChild: (child: ChildNode) => void;
 
   /**
-   * The managers this node's own descendants register to: itself for a
-   * manager, its parents' for a sync child, shared with its parent when it
-   * has one. Cached so that creating a child does not walk its ancestors.
+   * The last update that queued this node (`propagation-state.mts`). Left in
+   * place after the visit: the next update has another token.
    */
-  managers: readonly ManagerNode[];
+  queuedFor: UpdateToken | undefined;
+
+  setQueuedFor: (updateToken: UpdateToken) => void;
 }>;
 
 /** An observable, as the other nodes of the graph see it. */
@@ -36,13 +37,6 @@ export type ChildNode = NodeInternals &
     parents: readonly Observable<unknown>[];
   }>;
 
-export type ManagerNode = NodeInternals &
-  ObservableBase<unknown> &
-  Readonly<{
-    addDescendant: (child: ChildNode) => void;
-    deleteDescendant: (child: ChildNode) => void;
-  }>;
-
 /**
  * The one place a public observable is seen as the node it is. Every
  * observable is built by a synstate class, and the public types carry a

package/src/core/class/propagation-order.test.mts

@@ -1,8 +1,75 @@
+import type { FixedLengthTuple } from 'ts-type-forge';
 import { createState } from '../../utils/index.mjs';
 import { combine } from '../combine/index.mjs';
 import { map } from '../operators/index.mjs';
 
 describe('the nodes an update visits', () => {
+  test('a node an update nested in another reaches is still visited once by the outer one', () => {
+    const [source$, setSource] = createState(0);
+
+    const [other$, setOther] = createState(0);
+
+    const a$ = source$.pipe(map((x) => x));
+
+    const b$ = source$.pipe(map((x) => x));
+
+    const c$ = combine([a$, b$, other$]);
+
+    const mut_received: FixedLengthTuple<3, number>[] = [];
+
+    c$.subscribe((v) => {
+      mut_received.push(v);
+    });
+
+    // Runs after `a$` has queued `c$` for the outer update, and before `b$`
+    // queues it again.
+    b$.subscribe((x) => {
+      if (x === 1) {
+        setOther(1);
+      }
+    });
+
+    setSource(1);
+
+    assert.deepStrictEqual(mut_received, [
+      [0, 0, 0],
+      // the nested update
+      [1, 1, 1],
+      // the outer update
+      [1, 1, 1],
+    ]);
+  });
+
+  test('a node created during an update is visited by it if a parent emits after', () => {
+    const [count$, setCount] = createState(0);
+
+    const early$ = count$.pipe(map((x) => x));
+
+    // Depth 2: emits after the subscribers of `early$` have run.
+    const late$ = count$.pipe(map((x) => x)).pipe(map((x) => x));
+
+    const mut_received: number[] = [];
+
+    let mut_created = false;
+
+    early$.subscribe((x) => {
+      if (x !== 1 || mut_created) {
+        return;
+      }
+
+      mut_created = true;
+
+      // Starts from `late$`'s value before this update.
+      late$.pipe(map((y) => y * 10)).subscribe((v) => {
+        mut_received.push(v);
+      });
+    });
+
+    setCount(1);
+
+    assert.deepStrictEqual(mut_received, [0, 10]);
+  });
+
   test('a node created while an update propagates is not visited by it', () => {
     const [count$, setCount] = createState(0);
 
@@ -39,6 +106,46 @@ describe('the nodes an update visits', () => {
     expect(mut_calls).toBe(2);
   });
 
+  test('a node of a new depth created while an update propagates is not visited by it', () => {
+    const [count$, setCount] = createState(0);
+
+    let mut_calls = 0;
+
+    const countCall = (x: number): number => {
+      mut_calls += 1;
+
+      return x;
+    };
+
+    let mut_created = false;
+
+    count$.subscribe((x) => {
+      if (x !== 1 || mut_created) {
+        return;
+      }
+
+      mut_created = true;
+
+      // Depth 3: deeper than anything `count$` had, so the manager's array
+      // grows while it is being walked.
+      count$
+        .pipe(map((y) => y))
+        .pipe(map((y) => y))
+        .pipe(map(countCall))
+        .subscribe(() => {});
+    });
+
+    count$.pipe(map((x) => x)).subscribe(() => {});
+
+    setCount(1);
+
+    expect(mut_calls).toBe(1);
+
+    setCount(2);
+
+    expect(mut_calls).toBe(2);
+  });
+
   test('a node completed while an update propagates is not visited by it', () => {
     const [count$, setCount] = createState(0);
 

package/src/core/class/propagation-state.mts

@@ -1,3 +1,7 @@
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
+// @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
 /**
  * The state of the update propagating now, shared by every observable.
  *
@@ -8,7 +12,10 @@
  * update takes.
  */
 import { Arr } from 'ts-data-forge';
+import { panic } from 'ts-std-forge';
+import type { MutableSet } from 'ts-type-forge';
 import type { UpdateToken } from '../types/index.mjs';
+import type { ChildNode } from './observable-node.mjs';
 
 /**
  * How many `startUpdate` calls are running, across every observable, and
@@ -78,3 +85,258 @@ export const endPropagation = (): void => {
     mut_afterPropagation.shift()?.();
   }
 };
+
+/**
+ * The buckets of this copy's open updates, one set per nesting level: a
+ * bucket per depth below the node that started the update, holding the
+ * queued nodes and how many of its slots are in use. Kept from update to
+ * update, so that an update allocates nothing but its token; emptying a
+ * bucket is setting its length to 0.
+ */
+const mut_bucketSets: Bucket[][] = [];
+
+/** How many updates of this copy are open, the outermost included. */
+const mut_queueState: { level: number } = { level: 0 };
+
+/**
+ * Opens an update started by a node at `depth`, and returns its token. The
+ * token is the update's queue: a node that emits with it puts its children
+ * there, whichever copy of synstate the node belongs to, so that an update
+ * reaches every node its value reaches, and each once, in ascending depth.
+ * Close it with {@link closeUpdate}.
+ */
+export const openUpdate = (depth: number): UpdateToken => {
+  if (mut_queueState.level >= maxUpdateNesting) {
+    // A programming error, as a circular dependency is: `panic` keeps the
+    // `Result` boundaries from turning it into an `Err`. Thrown before this
+    // update opens, so only the updates around it close, each in its own
+    // `startUpdate`'s `finally`.
+    panic(updateLoopMessage);
+  }
+
+  mut_queueState.level += 1;
+
+  return toToken(new UpdateQueue(depth + 1, mut_queueState.level));
+};
+
+/**
+ * How many updates of one copy may be open at once, one inside another. An
+ * update opens inside another only when a subscriber or projection writes to
+ * a root while the outer one is propagating; a chain of such writes this deep
+ * is a loop that would otherwise run until the stack overflows.
+ */
+export const maxUpdateNesting = 100;
+
+export const updateLoopMessage =
+  `synstate: more than ${maxUpdateNesting.toString()} updates were nested, one started inside another: a subscriber or projection keeps writing to an observable whose update reaches it again. Make the write stop (a condition, or a value equal to the current one), or derive the value with map / combine.` as const;
+
+/** Visits every node the update has queued, shallowest first. */
+export const drainUpdate = (updateToken: UpdateToken): void => {
+  toQueue(updateToken).drain();
+};
+
+/** Closes an update, emptying what an exception left in its buckets. */
+export const closeUpdate = (updateToken: UpdateToken): void => {
+  toQueue(updateToken).close();
+
+  mut_queueState.level -= 1;
+};
+
+/**
+ * Puts the children of a node that emitted with `updateToken` into that
+ * update's queue. The update may belong to another copy of synstate.
+ */
+export const enqueueChildren = (
+  children: ReadonlySet<ChildNode>,
+  updateToken: UpdateToken,
+): void => {
+  toQueue(updateToken).enqueueChildren(children);
+};
+
+// Written in place: a bucket is emptied by its length, not replaced.
+// transformer-ignore-next-line convert-to-readonly
+type Bucket = {
+  /** The queued nodes at one depth; the slots from `length` on are unused. */
+  // @sumi-expect-error readonly/require-readonly-type
+  readonly nodes: (ChildNode | undefined)[];
+  /** How many slots of `nodes` are in use. */
+  // @sumi-expect-error readonly/require-readonly-type
+  length: number;
+};
+
+/**
+ * The queue of one update, and its token.
+ *
+ * A queued node is marked with the token of the update that queued it
+ * (`queuedFor`), which is how an update queues a node once. The mark is not
+ * cleared after the visit: a later update has another token. An update does
+ * not overwrite the mark of an update that is still open — one it is nested
+ * in, or one of another copy of synstate — and remembers the nodes it
+ * queues despite such a mark in a set of its own instead.
+ */
+class UpdateQueue {
+  readonly #base: number;
+
+  /** `buckets[index]` holds the queued nodes at depth `base + index`. */
+  // @sumi-expect-error readonly/require-readonly-type
+  readonly #mut_buckets: Bucket[];
+
+  #mut_size: number;
+
+  #mut_isOpen: boolean;
+
+  #mut_queuedDespiteMark: MutableSet<ChildNode> | undefined;
+
+  /** `level` is 1 for the outermost update of this copy. */
+  constructor(base: number, level: number) {
+    this.#base = base;
+
+    const mut_buckets = mut_bucketSets[level - 1] ?? [];
+
+    mut_bucketSets[level - 1] = mut_buckets;
+
+    this.#mut_buckets = mut_buckets;
+
+    this.#mut_size = 0;
+
+    this.#mut_isOpen = true;
+
+    this.#mut_queuedDespiteMark = undefined;
+  }
+
+  #push(child: ChildNode): void {
+    const index = child.depth - this.#base;
+
+    const mut_buckets = this.#mut_buckets;
+
+    while (mut_buckets.length <= index) {
+      mut_buckets.push({ nodes: [], length: 0 });
+    }
+
+    if (index >= this.#mut_size) {
+      this.#mut_size = index + 1;
+    }
+
+    // Defined: the loop above made it.
+    // @sumi-expect-error banned-syntax/no-non-null-assertion
+    const mut_bucket = mut_buckets[index]!;
+
+    const { nodes: mut_nodes, length } = mut_bucket;
+
+    if (length < mut_nodes.length) {
+      mut_nodes[length] = child;
+    } else {
+      mut_nodes.push(child);
+    }
+
+    mut_bucket.length = length + 1;
+  }
+
+  /** Whether the update is still running; read across copies of synstate. */
+  get isOpen(): boolean {
+    return this.#mut_isOpen;
+  }
+
+  enqueueChildren(children: ReadonlySet<ChildNode>): void {
+    const ownMark = toToken(this);
+
+    for (const child of children) {
+      const mark = child.queuedFor;
+
+      if (mark === ownMark) {
+        continue;
+      }
+
+      if (mark !== undefined && toQueue(mark).isOpen) {
+        // Another open update has queued `child` and may not have visited
+        // it yet: leave its mark alone.
+        if (this.#mut_queuedDespiteMark === undefined) {
+          this.#mut_queuedDespiteMark = new Set();
+        } else if (this.#mut_queuedDespiteMark.has(child)) {
+          continue;
+        }
+
+        this.#mut_queuedDespiteMark.add(child);
+      } else {
+        child.setQueuedFor(ownMark);
+      }
+
+      this.#push(child);
+    }
+  }
+
+  drain(): void {
+    const token = toToken(this);
+
+    const mut_buckets = this.#mut_buckets;
+
+    // `size` grows while the buckets are visited, always past `index`, which
+    // a `range` built at the start would miss.
+    // eslint-disable-next-line ts-data-forge/prefer-range-for-loop
+    for (let mut_index = 0; mut_index < this.#mut_size; mut_index += 1) {
+      const mut_bucket = mut_buckets[mut_index];
+
+      if (mut_bucket === undefined) {
+        continue;
+      }
+
+      // A node visited here queues only deeper nodes, so this bucket does
+      // not grow while it is visited. Its length is kept until the end, so
+      // that `close` can clear what an exception leaves.
+      const { nodes: mut_nodes, length } = mut_bucket;
+
+      // eslint-disable-next-line ts-data-forge/prefer-range-for-loop
+      for (let mut_slot = 0; mut_slot < length; mut_slot += 1) {
+        const node = mut_nodes[mut_slot];
+
+        // Drops the reference, so that a node completed and dropped by
+        // everything else is not kept alive by a slot.
+        mut_nodes[mut_slot] = undefined;
+
+        if (node !== undefined && !node.isCompleted) {
+          node.tryUpdate(token);
+        }
+      }
+
+      mut_bucket.length = 0;
+    }
+
+    this.#mut_size = 0;
+  }
+
+  close(): void {
+    const mut_buckets = this.#mut_buckets;
+
+    // Only after an exception is anything left.
+    // eslint-disable-next-line ts-data-forge/prefer-range-for-loop
+    for (let mut_index = 0; mut_index < this.#mut_size; mut_index += 1) {
+      const mut_bucket = mut_buckets[mut_index];
+
+      if (mut_bucket === undefined) {
+        continue;
+      }
+
+      mut_bucket.nodes.fill(undefined, 0, mut_bucket.length);
+
+      mut_bucket.length = 0;
+    }
+
+    this.#mut_size = 0;
+
+    this.#mut_isOpen = false;
+
+    this.#mut_queuedDespiteMark = undefined;
+  }
+}
+
+/**
+ * A token as the queue it is. A token reaches this copy from a node of any
+ * copy, and every copy's tokens have `enqueueChildren`.
+ */
+const toQueue = (updateToken: UpdateToken): UpdateQueue =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  updateToken as unknown as UpdateQueue;
+
+const toToken = (queue: UpdateQueue): UpdateToken =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  queue as unknown as UpdateToken;

package/src/core/class/remove-completed.test.mts

@@ -202,8 +202,8 @@ describe('a completed observable leaves the propagation graph', () => {
 
     const mut_got: number[] = [];
 
-    // Subscribed on a child, so the node is created while `s` is already
-    // walking its propagation order.
+    // Subscribed on a child, so the node is created while the update of `s`
+    // is under way.
     s.pipe(map((x) => x)).subscribe((x) => {
       if (x === 1) {
         s.pipe(