synstate 3.3.0 → 4.0.0

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

@@ -0,0 +1,92 @@
+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 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;
+
+      count$.pipe(map(countCall)).subscribe(() => {});
+    });
+
+    count$.pipe(map((x) => x)).subscribe(() => {});
+
+    setCount(1);
+
+    // Once for the initial value; the update that created it does not run it
+    // again.
+    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);
+
+    let mut_calls = 0;
+
+    const late$ = count$.pipe(map((x) => x + 1)).pipe(
+      map((x) => {
+        mut_calls += 1;
+
+        return x;
+      }),
+    );
+
+    late$.subscribe(() => {});
+
+    count$.subscribe((x) => {
+      if (x === 1) {
+        late$.complete();
+      }
+    });
+
+    mut_calls = 0;
+
+    setCount(1);
+
+    expect(mut_calls).toBe(0);
+  });
+
+  test('a manager whose descendants skip depths updates them in order', () => {
+    const [a$, setA] = createState(0);
+
+    const [b$] = createState(10);
+
+    // `c$` is at depth 3 and the only descendant of `a$`.
+    const c$ = combine([a$, b$.pipe(map((x) => x)).pipe(map((x) => x))]);
+
+    const d$ = c$.pipe(map(([x, y]) => x + y));
+
+    const mut_values: number[] = [];
+
+    d$.subscribe((v) => {
+      mut_values.push(v);
+    });
+
+    setA(1);
+
+    setA(2);
+
+    assert.deepStrictEqual(mut_values, [10, 11, 12]);
+  });
+});

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

@@ -0,0 +1,80 @@
+/**
+ * The state of the update propagating now, shared by every observable.
+ *
+ * It is module state rather than a field of a class, so that nothing outside
+ * this file can reach it but through the functions below: an exported class
+ * would hand its static fields to every importer, and a private static field
+ * costs about twice as much per access as a module binding, on a path every
+ * update takes.
+ */
+import { Arr } from 'ts-data-forge';
+import type { UpdateToken } from '../types/index.mjs';
+
+/**
+ * How many `startUpdate` calls are running, across every observable, and
+ * the token of the outermost one.
+ */
+const mut_propagation: {
+  depth: number;
+  outermostToken: UpdateToken | undefined;
+} = { depth: 0, outermostToken: undefined };
+
+/**
+ * Work deferred by {@link runAfterPropagation}, run once the outermost
+ * `startUpdate` has reached every descendant.
+ */
+const mut_afterPropagation: (() => void)[] = [];
+
+/**
+ * Whether some observable's update is propagating right now. A root written
+ * to while one is, is written to from inside a subscriber or a projection
+ * (#2336).
+ */
+export const isPropagating = (): boolean => mut_propagation.depth > 0;
+
+/** The token of the outermost update propagating now, if any. */
+export const outermostUpdateToken = (): UpdateToken | undefined =>
+  mut_propagation.outermostToken;
+
+/**
+ * Runs `task` once the update now propagating has reached every descendant, or
+ * at once when none is. A child that completes itself in its `tryUpdate`
+ * completes its children with it, before they have seen the value it has just
+ * passed on (`take`).
+ */
+export const runAfterPropagation = (task: () => void): void => {
+  if (isPropagating()) {
+    mut_afterPropagation.push(task);
+  } else {
+    task();
+  }
+};
+
+/** Brackets one `startUpdate`; see {@link endPropagation}. */
+export const beginPropagation = (updateToken: UpdateToken): void => {
+  if (mut_propagation.depth === 0) {
+    mut_propagation.outermostToken = updateToken;
+  }
+
+  mut_propagation.depth += 1;
+};
+
+/**
+ * Ends one `startUpdate`, and runs the deferred work once the outermost one
+ * has ended.
+ */
+export const endPropagation = (): void => {
+  mut_propagation.depth -= 1;
+
+  if (mut_propagation.depth > 0) {
+    return;
+  }
+
+  mut_propagation.outermostToken = undefined;
+
+  // A deferred task may start an update of its own, which flushes what that
+  // update defers before this loop moves on.
+  while (Arr.isNonEmpty(mut_afterPropagation)) {
+    mut_afterPropagation.shift()?.();
+  }
+};

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

@@ -0,0 +1,369 @@
+import { Optional } from 'ts-data-forge';
+import type { FixedLengthTuple } from 'ts-type-forge';
+import { createState } from '../../utils/index.mjs';
+import { combine } from '../combine/index.mjs';
+import { source } from '../create/index.mjs';
+import { map, switchMap, takeWhile } from '../operators/index.mjs';
+import { toNode } from './observable-node.mjs';
+
+describe('a completed observable leaves the propagation graph', () => {
+  test('completed derived observables stop computing (#2134)', () => {
+    const [count$, setCount] = createState(0);
+
+    // A subscriber, so that the root has a reason to stay alive whatever the
+    // completion rules for an unused root are.
+    count$.subscribe(() => {});
+
+    let mut_calls = 0;
+
+    const countCall = (x: number): number => {
+      mut_calls += 1;
+
+      return x;
+    };
+
+    for (const _ of Array.from({ length: 1000 })) {
+      const d = count$.pipe(map(countCall));
+
+      d.complete();
+
+      assert.isTrue(d.isCompleted);
+    }
+
+    mut_calls = 0;
+
+    setCount(1);
+
+    expect(mut_calls).toBe(0);
+  });
+
+  test('a completed descendant several levels down stops computing', () => {
+    const [count$, setCount] = createState(0);
+
+    count$.subscribe(() => {});
+
+    let mut_calls = 0;
+
+    const d1 = count$.pipe(map((x) => x + 1));
+
+    const d2 = d1.pipe(
+      map((x) => {
+        mut_calls += 1;
+
+        return x;
+      }),
+    );
+
+    d1.subscribe(() => {});
+
+    d2.complete();
+
+    mut_calls = 0;
+
+    setCount(1);
+
+    expect(mut_calls).toBe(0);
+
+    assert.deepStrictEqual(d1.getSnapshot(), Optional.some(2));
+  });
+
+  test('completing a node in the middle of a chain removes everything below it', () => {
+    const s = source<number>(0);
+
+    s.subscribe(() => {});
+
+    const middle = s.pipe(map((x) => x + 1));
+
+    let mut_calls = 0;
+
+    const leaf = middle.pipe(
+      map((x) => {
+        mut_calls += 1;
+
+        return x;
+      }),
+    );
+
+    const mut_got: number[] = [];
+
+    leaf.subscribe((v) => {
+      mut_got.push(v);
+    });
+
+    middle.complete();
+
+    assert.isTrue(leaf.isCompleted);
+
+    assert.isFalse(toNode(s).hasChild);
+
+    mut_calls = 0;
+
+    s.next(1);
+
+    // The leaf is not reached through the completed node, nor directly.
+    expect(mut_calls).toBe(0);
+
+    assert.deepStrictEqual(mut_got, [1]);
+  });
+
+  test('completing the root of a long chain takes time linear in its length', () => {
+    const s = source<number>(0);
+
+    let mut_tail = s.pipe(map((x) => x));
+
+    for (const _ of Array.from({ length: 499 })) {
+      mut_tail = mut_tail.pipe(map((x) => x));
+    }
+
+    const leaf = mut_tail;
+
+    leaf.subscribe(() => {});
+
+    const start = performance.now();
+
+    s.complete();
+
+    const elapsed = performance.now() - start;
+
+    assert.isTrue(leaf.isCompleted);
+
+    // Each node used to re-run the completion of every ancestor, each run
+    // walking the ancestors again: cubic in the length, over 2 s here.
+    expect(elapsed).toBeLessThan(1000);
+  });
+
+  test('the parent no longer reports the completed child', () => {
+    const s = source<number>(0);
+
+    s.subscribe(() => {});
+
+    const d = s.pipe(map((x) => x));
+
+    assert.isTrue(toNode(s).hasChild);
+
+    d.complete();
+
+    assert.isFalse(toNode(s).hasChild);
+
+    assert.isFalse(toNode(s).hasActiveChild());
+  });
+
+  test('a node with another live parent keeps updating', () => {
+    const a = source<number>(0);
+
+    const b = source<number>(0);
+
+    const a2 = a.pipe(map((x) => x * 10));
+
+    const c = combine([a2, b]);
+
+    const mut_got: FixedLengthTuple<2, number>[] = [];
+
+    c.subscribe((v) => {
+      mut_got.push(v);
+    });
+
+    b.complete();
+
+    a.next(1);
+
+    assert.deepStrictEqual(mut_got, [
+      [0, 0],
+      [10, 0],
+    ]);
+  });
+
+  test('a sibling completing during propagation does not disturb the others', () => {
+    const s = source<number>(0);
+
+    const stopper = s.pipe(takeWhile((x) => x < 1));
+
+    stopper.subscribe(() => {});
+
+    const mut_got: number[] = [];
+
+    s.pipe(map((x) => x * 2)).subscribe((v) => {
+      mut_got.push(v);
+    });
+
+    s.next(1);
+
+    s.next(2);
+
+    assert.isTrue(stopper.isCompleted);
+
+    assert.deepStrictEqual(mut_got, [0, 2, 4]);
+  });
+
+  test('a node created during propagation is not updated by that same update', () => {
+    const s = source<number>(0);
+
+    let mut_calls = 0;
+
+    const mut_got: number[] = [];
+
+    // Subscribed on a child, so the node is created while `s` is already
+    // walking its propagation order.
+    s.pipe(map((x) => x)).subscribe((x) => {
+      if (x === 1) {
+        s.pipe(
+          map((y) => {
+            mut_calls += 1;
+
+            return y;
+          }),
+        ).subscribe((y) => {
+          mut_got.push(y);
+        });
+      }
+    });
+
+    s.next(1);
+
+    // Only the initial value computed when the node was created.
+    expect(mut_calls).toBe(1);
+
+    assert.deepStrictEqual(mut_got, [1]);
+
+    s.next(2);
+
+    assert.deepStrictEqual(mut_got, [1, 2]);
+  });
+
+  test('inner observables switched away from stop computing', () => {
+    const [outer$, setOuter] = createState(0);
+
+    const [inner$, setInner] = createState(0);
+
+    inner$.subscribe(() => {});
+
+    let mut_calls = 0;
+
+    const result$ = outer$.pipe(
+      switchMap((o) =>
+        inner$.pipe(
+          map((i) => {
+            mut_calls += 1;
+
+            return o + i;
+          }),
+        ),
+      ),
+    );
+
+    result$.subscribe(() => {});
+
+    for (const o of [1, 2, 3, 4, 5]) {
+      setOuter(o);
+    }
+
+    mut_calls = 0;
+
+    setInner(1);
+
+    expect(mut_calls).toBe(1);
+  });
+});
+
+describe('a completed observable keeps its last value', () => {
+  test('getSnapshot returns the value the observable completed with', () => {
+    const s = source<number>(0);
+
+    s.next(5);
+
+    s.complete();
+
+    assert.isTrue(s.isCompleted);
+
+    assert.deepStrictEqual(s.getSnapshot(), Optional.some(5));
+  });
+
+  test('combine keeps reading the last value of a parent that completed after it changed', () => {
+    const a = source<number>(0);
+
+    const b = source<number>(0);
+
+    const c = combine([a, b]);
+
+    const mut_got: FixedLengthTuple<2, number>[] = [];
+
+    c.subscribe((v) => {
+      mut_got.push(v);
+    });
+
+    b.next(5);
+
+    b.complete();
+
+    a.next(1);
+
+    assert.isFalse(c.isCompleted);
+
+    assert.deepStrictEqual(mut_got, [
+      [0, 0],
+      [0, 5],
+      [1, 5],
+    ]);
+  });
+
+  test('a derived observable completed by its parent keeps its last value for combine', () => {
+    const a = source<number>(0);
+
+    const s = source<number>(1);
+
+    const m = s.pipe(map((x) => x * 2));
+
+    const c = combine([a, m]);
+
+    const mut_got: FixedLengthTuple<2, number>[] = [];
+
+    c.subscribe((v) => {
+      mut_got.push(v);
+    });
+
+    s.next(3);
+
+    s.complete();
+
+    assert.isTrue(m.isCompleted);
+
+    assert.deepStrictEqual(m.getSnapshot(), Optional.some(6));
+
+    a.next(1);
+
+    assert.isFalse(c.isCompleted);
+
+    assert.deepStrictEqual(mut_got, [
+      [0, 2],
+      [0, 6],
+      [1, 6],
+    ]);
+  });
+
+  test('combine created after a parent completed starts from its last value', () => {
+    const a = source<number>(0);
+
+    const b = source<number>(0);
+
+    b.next(5);
+
+    b.complete();
+
+    const c = combine([a, b]);
+
+    assert.deepStrictEqual(c.getSnapshot(), Optional.some([0, 5] as const));
+
+    const mut_got: FixedLengthTuple<2, number>[] = [];
+
+    c.subscribe((v) => {
+      mut_got.push(v);
+    });
+
+    a.next(1);
+
+    assert.deepStrictEqual(mut_got, [
+      [0, 5],
+      [1, 5],
+    ]);
+  });
+});

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

@@ -0,0 +1,85 @@
+// @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 { Optional } from 'ts-data-forge';
+import {
+  isRootObservable,
+  type RootObservable,
+  type UpdateToken,
+} from '../types/index.mjs';
+import { ManagerObservableClass } from './manager-observable-class.mjs';
+import { isPropagating, outermostUpdateToken } from './propagation-state.mjs';
+
+export class RootObservableClass<A>
+  extends ManagerObservableClass<A, 'root', 0>
+  implements RootObservable<A>
+{
+  /**
+   * The outermost update propagating when this root was created. A root
+   * created while an update propagates (inside a `switchMap` projection,
+   * say) may emit while it is created, as `fromSubscribable` does for a
+   * synchronous source. Nothing is derived from it yet, so that is its
+   * initial value rather than a write (#2336).
+   */
+  readonly #createdDuring: UpdateToken | undefined;
+  #mut_hasWarned: boolean;
+
+  constructor({
+    initialValue,
+  }: Readonly<{
+    initialValue: Optional<A>;
+  }>) {
+    super({
+      kind: 'root',
+      depth: 0,
+      initialValue,
+    });
+
+    this.#createdDuring = outermostUpdateToken();
+
+    this.#mut_hasWarned = false;
+
+    this.adoptIntoCurrentScope();
+  }
+
+  /**
+   * Emits `nextValue` and propagates the update to all descendants, warning
+   * once when it is a write from inside another update.
+   */
+  protected override startUpdate(nextValue: A): void {
+    if (
+      !this.#mut_hasWarned &&
+      isPropagating() &&
+      outermostUpdateToken() !== this.#createdDuring
+    ) {
+      this.#mut_hasWarned = true;
+
+      console.warn(writeDuringPropagationWarning);
+    }
+
+    super.startUpdate(nextValue);
+  }
+}
+
+/**
+ * Shown once per root observable, the first time it is written to (`next`,
+ * `setState`, `dispatch`, …) while another update is still propagating —
+ * from a subscriber or a projection. The write still propagates immediately,
+ * as it always has; the warning is there because the pattern is wrong, not
+ * because anything was refused.
+ */
+export const writeDuringPropagationWarning =
+  'synstate: an observable was written to (next / setState / dispatch) while an update was propagating, so subscribers can see intermediate states. Derive the value with map / combine instead of writing from a subscriber or a projection.';
+
+if (import.meta.vitest !== undefined) {
+  test('isRootObservable', () => {
+    assert.isTrue(
+      isRootObservable(
+        new RootObservableClass({
+          initialValue: Optional.some(0),
+        }),
+      ),
+    );
+  });
+}