synstate 4.1.0 → 5.0.0

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(

package/src/core/class/update-loop.test.mts

@@ -0,0 +1,104 @@
+import { createState } from '../../utils/index.mjs';
+import { map } from '../operators/index.mjs';
+import { maxUpdateNesting, updateLoopMessage } from './propagation-state.mjs';
+
+describe('an update that keeps starting another inside itself', () => {
+  test('a subscriber that writes back to its own root throws a named error, not a stack overflow', () => {
+    const [a$, setA] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a > 0) {
+        setA(a + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      expect(() => {
+        setA(1);
+      }).toThrow(updateLoopMessage);
+    });
+  });
+
+  test('two subscribers writing to each other’s roots throw the same error', () => {
+    const [a$, setA] = createState(0);
+
+    const [b$, setB] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a > 0) {
+        setB(a + 1);
+      }
+    });
+
+    b$.subscribe((b) => {
+      if (b > 0) {
+        setA(b + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      expect(() => {
+        setA(1);
+      }).toThrow(updateLoopMessage);
+    });
+  });
+
+  test('updates work as before once the loop has thrown', () => {
+    const [a$, setA] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a > 0) {
+        setA(a + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      expect(() => {
+        setA(1);
+      }).toThrow(updateLoopMessage);
+    });
+
+    const [b$, setB] = createState(0);
+
+    const mut_received: number[] = [];
+
+    b$.pipe(map((b) => b * 10)).subscribe((b) => {
+      mut_received.push(b);
+    });
+
+    setB(1);
+
+    setB(2);
+
+    assert.deepStrictEqual(mut_received, [0, 10, 20]);
+  });
+
+  test('a write that converges may nest up to the limit', () => {
+    const [a$, setA, { getSnapshot }] = createState(0);
+
+    a$.subscribe((a) => {
+      if (0 < a && a < maxUpdateNesting) {
+        setA(a + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      setA(1);
+    });
+
+    assert.strictEqual(getSnapshot(), maxUpdateNesting);
+  });
+});
+
+/**
+ * Runs `run` with `console.warn` silenced: every case here writes from a
+ * subscriber, which warns once per root.
+ */
+const withoutWarnings = (run: () => void): void => {
+  vi.stubGlobal('console', { ...console, warn: vi.fn() });
+
+  run();
+
+  // cspell:disable-next-line
+  vi.unstubAllGlobals();
+};

package/src/core/operators/index.mts

@@ -1,6 +1,7 @@
 export * from './audit.mjs';
 export * from './debounce.mjs';
 export * from './filter.mjs';
+export * from './keep-equal-parts.mjs';
 export * from './map.mjs';
 export * from './merge-map.mjs';
 export * from './pairwise.mjs';