synstate 3.3.0 → 4.0.0

package/src/core/class/write-during-propagation.test.mts

@@ -0,0 +1,234 @@
+import { Result } from 'ts-data-forge';
+import { panic } from 'ts-std-forge';
+import type { FixedLengthTuple } from 'ts-type-forge';
+import { createState } from '../../utils/index.mjs';
+import { combine } from '../combine/index.mjs';
+import { fromSubscribable, source } from '../create/index.mjs';
+import { map, switchMap } from '../operators/index.mjs';
+import { writeDuringPropagationWarning } from './root-observable-class.mjs';
+
+describe('a write to a root observable while an update is propagating (#2336)', () => {
+  test('warns when a subscriber writes to another state, and still propagates the write immediately', async () => {
+    const [a$, setA] = createState(0);
+
+    const [b$, setB] = createState(0);
+
+    const doubled$ = a$.pipe(map((a) => a * 10));
+
+    a$.subscribe((a) => {
+      setB(a * 2);
+    });
+
+    const mut_history: FixedLengthTuple<2, number>[] = [];
+
+    combine([doubled$, b$]).subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    const warn = await captureWarnings(() => {
+      setA(1);
+    });
+
+    assert.deepStrictEqual(warn, [writeDuringPropagationWarning]);
+
+    // The behavior is unchanged: b$ propagates before doubled$ is updated, so
+    // the intermediate state [0, 2] is observed.
+    assert.deepStrictEqual(mut_history, [
+      [0, 0],
+      [0, 2],
+      [10, 2],
+    ]);
+
+    assert.strictEqual(b$.getSnapshot().value, 2);
+  });
+
+  test('warns when a projection writes to a state', async () => {
+    const a$ = source<number>(0);
+
+    const [, setB] = createState(0);
+
+    a$.pipe(
+      map((a) => {
+        setB(a);
+
+        return a;
+      }),
+    ).subscribe(() => {});
+
+    const warn = await captureWarnings(() => {
+      a$.next(1);
+    });
+
+    assert.deepStrictEqual(warn, [writeDuringPropagationWarning]);
+  });
+
+  test('warns when a subscriber of an asynchronous child writes to a state', async () => {
+    const outer$ = source<number>(0);
+
+    const inner$ = source<number>(0);
+
+    const [, setB] = createState(0);
+
+    outer$.pipe(switchMap(() => inner$)).subscribe((v) => {
+      if (v > 0) {
+        setB(v);
+      }
+    });
+
+    const warnOnSwitch = await captureWarnings(() => {
+      outer$.next(1);
+    });
+
+    assert.deepStrictEqual(warnOnSwitch, []);
+
+    const warn = await captureWarnings(() => {
+      inner$.next(1);
+    });
+
+    assert.deepStrictEqual(warn, [writeDuringPropagationWarning]);
+  });
+
+  test('warns once per observable', async () => {
+    const a$ = source<number>(0);
+
+    const [, setB] = createState(0);
+
+    const [, setC] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a <= 0) {
+        return;
+      }
+
+      setB(a);
+
+      setB(a + 1);
+
+      setC(a);
+    });
+
+    const warn = await captureWarnings(() => {
+      a$.next(1);
+
+      a$.next(2);
+    });
+
+    assert.deepStrictEqual(warn, [
+      writeDuringPropagationWarning,
+      writeDuringPropagationWarning,
+    ]);
+  });
+
+  test('does not warn for writes outside propagation', async () => {
+    const [a$, setA] = createState(0);
+
+    const [b$, setB] = createState(0);
+
+    a$.subscribe((a) => {
+      queueMicrotask(() => {
+        setB(a);
+      });
+    });
+
+    const warn = await captureWarnings(async () => {
+      setA(1);
+
+      await Promise.resolve();
+    });
+
+    assert.deepStrictEqual(warn, []);
+
+    assert.strictEqual(b$.getSnapshot().value, 1);
+  });
+
+  test('does not warn when an operator emits an inner observable synchronously', async () => {
+    const outer$ = source<number>(0);
+
+    const mut_history: number[] = [];
+
+    outer$.pipe(switchMap((x) => source(x * 10))).subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    const warn = await captureWarnings(() => {
+      outer$.next(1);
+    });
+
+    assert.deepStrictEqual(warn, []);
+
+    assert.deepStrictEqual(mut_history, [10]);
+  });
+
+  test('does not warn when a root created during propagation emits while it is created', async () => {
+    const outer$ = source<number>(0);
+
+    const mut_history: number[] = [];
+
+    outer$
+      .pipe(
+        switchMap((x) =>
+          fromSubscribable<number>({
+            subscribe: (onNext) => {
+              onNext(x * 10);
+
+              return { unsubscribe: () => {} };
+            },
+          }),
+        ),
+      )
+      .subscribe((r) => {
+        if (Result.isOk(r)) {
+          mut_history.push(r.value);
+        }
+      });
+
+    const warn = await captureWarnings(() => {
+      outer$.next(1);
+    });
+
+    assert.deepStrictEqual(warn, []);
+
+    assert.deepStrictEqual(mut_history, [10]);
+  });
+
+  test('a subscriber that throws does not leave the propagation flag set', async () => {
+    const a$ = source<number>(0);
+
+    const [, setB] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a > 0) {
+        panic('boom');
+      }
+    });
+
+    const warn = await captureWarnings(() => {
+      expect(() => {
+        a$.next(1);
+      }).toThrow('boom');
+
+      setB(1);
+    });
+
+    assert.deepStrictEqual(warn, []);
+  });
+});
+
+/**
+ * Runs `run` with `console.warn` replaced by a mock, and returns the messages
+ * it was called with.
+ */
+const captureWarnings = async (
+  run: () => Promise<void> | void,
+): Promise<readonly unknown[]> => {
+  const warn = vi.fn();
+
+  vi.stubGlobal('console', { ...console, warn });
+
+  await run();
+
+  // cspell:disable-next-line
+  vi.unstubAllGlobals();
+
+  return warn.mock.calls.map((args: readonly unknown[]) => args[0]);
+};

package/src/core/combine/combine.mts

@@ -1,6 +1,12 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
 import { Arr, expectType, Optional } from 'ts-data-forge';
 import type { NonEmptyTuple, Tuple } from 'ts-type-forge';
-import { createSyncChildObservable } from '../base/index.mjs';
+import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import type {
@@ -11,6 +17,7 @@ import type {
   NonEmptyUnknownList,
   Observable,
   SyncChildObservable,
+  UpdateToken,
   Wrap,
 } from '../types/index.mjs';
 
@@ -75,7 +82,9 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): CombineObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  createCombineObservable(parents) as unknown as CombineObservableRefined<OS>;
+  new CombineObservableClass(
+    parents,
+  ) as unknown as CombineObservableRefined<OS>;
 
 /**
  * Alias for `combine`.
@@ -83,61 +92,64 @@ export const combine = <const OS extends NonEmptyTuple<Observable<unknown>>>(
  */
 export const combineLatest = combine;
 
-const createCombineObservable = <const A extends NonEmptyUnknownList>(
-  parents: Wrap<A>,
-): CombineObservable<A> => {
-  const parentsValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
-    parents,
-    (p) => p.getSnapshot(),
-  );
-
-  // The annotation on `initialValue` is what replaces the type assertion.
-  // `Arr.map` carries a single result element type, so it reports `A[number]`
-  // at every position, and `Tuple.MapTo<A[number], A>` — the uniform mapping
-  // — is *not* assignable back to `A`. The positional
-  // `Readonly<{ [K in keyof A]: A[K] }>` is, and TypeScript accepts the
-  // uniform result into it because the two mapped types share `keyof A`. So
-  // it is the annotation, not an assertion, that records the position-wise
-  // fact the checker cannot derive on its own.
-  const initialValue: Optional<Readonly<{ [K in keyof A]: A[K] }>> = Arr.every(
-    parentsValues,
-    Optional.isSome,
-  )
-    ? Optional.some(Arr.map(parentsValues, (c) => c.value))
-    : Optional.none;
-
-  return createSyncChildObservable<A, A>(
-    {
+class CombineObservableClass<const A extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<A, A>
+  implements CombineObservable<A>
+{
+  constructor(parents: Wrap<A>) {
+    const parentsValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
+      parents,
+      (p) => p.getSnapshot(),
+    );
+
+    // The annotation on `initialValue` is what replaces the type assertion.
+    // `Arr.map` carries a single result element type, so it reports `A[number]`
+    // at every position, and `Tuple.MapTo<A[number], A>` — the uniform mapping
+    // — is *not* assignable back to `A`. The positional
+    // `Readonly<{ [K in keyof A]: A[K] }>` is, and TypeScript accepts the
+    // uniform result into it because the two mapped types share `keyof A`. So
+    // it is the annotation, not an assertion, that records the position-wise
+    // fact the checker cannot derive on its own.
+    const initialValue: Optional<Readonly<{ [K in keyof A]: A[K] }>> =
+      Arr.every(parentsValues, Optional.isSome)
+        ? Optional.some(Arr.map(parentsValues, (c) => c.value))
+        : Optional.none;
+
+    super({
       parents,
       initialValue,
-    },
-    ({ setNext }) =>
-      (updateToken) => {
-        if (parents.every((o) => o.updateToken !== updateToken)) {
-          return; // all parents are skipped
-        }
-
-        // Same shape-preserving chain as the initial value: `Arr.map` (not the
-        // native one, which drops the tuple shape) into the uniform
-        // `Tuple.MapTo`, then a positional annotation to get back to `A`.
-        const parentValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
-          parents,
-          (a) => a.getSnapshot(),
-        );
-
-        if (!Arr.every(parentValues, Optional.isSome)) {
-          return;
-        }
-
-        const nextValue: Readonly<{ [K in keyof A]: A[K] }> = Arr.map(
-          parentValues,
-          (a) => a.value,
-        );
-
-        setNext(nextValue, updateToken);
-      },
-  );
-};
+    });
+
+    this.attach();
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const parents = this.parents;
+
+    if (parents.every((o) => o.updateToken !== updateToken)) {
+      return; // all parents are skipped
+    }
+
+    // Same shape-preserving chain as the initial value: `Arr.map` (not the
+    // native one, which drops the tuple shape) into the uniform
+    // `Tuple.MapTo`, then a positional annotation to get back to `A`.
+    const parentValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
+      parents,
+      (a) => a.getSnapshot(),
+    );
+
+    if (!Arr.every(parentValues, Optional.isSome)) {
+      return;
+    }
+
+    const nextValue: Readonly<{ [K in keyof A]: A[K] }> = Arr.map(
+      parentValues,
+      (a) => a.value,
+    );
+
+    this.setNext(nextValue, updateToken);
+  }
+}
 
 if (import.meta.vitest !== undefined) {
   test('type test', () => {

package/src/core/combine/merge.mts

@@ -1,6 +1,12 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
 import { Optional, expectType } from 'ts-data-forge';
 import type { ArrayElement, NonEmptyTuple } from 'ts-type-forge';
-import { createSyncChildObservable } from '../base/index.mjs';
+import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import type {
   MergeObservable,
@@ -8,6 +14,7 @@ import type {
   NonEmptyUnknownList,
   Observable,
   SyncChildObservable,
+  UpdateToken,
   Wrap,
 } from '../types/index.mjs';
 
@@ -58,42 +65,42 @@ import type {
  *
  * assert.deepStrictEqual(valueHistory, ['c1', 'k1', 'c2', 'k2']);
  * ```
- *
- * @note To improve code readability, consider using `createState` instead of `merge`,
- * subscribing to `parents` and calling `setState` within it.
  */
 export const merge = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): MergeObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  createMergeObservable(parents) as MergeObservableRefined<OS>;
+  new MergeObservableClass(parents) as MergeObservableRefined<OS>;
 
-const createMergeObservable = <const P extends NonEmptyUnknownList>(
-  parents: Wrap<P>,
-): MergeObservable<P> =>
-  createSyncChildObservable<ArrayElement<P>, P>(
-    {
+class MergeObservableClass<const P extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<ArrayElement<P>, P>
+  implements MergeObservable<P>
+{
+  constructor(parents: Wrap<P>) {
+    super({
       parents,
       initialValue: Optional.none,
-    },
-    ({ setNext }) =>
-      (updateToken) => {
-        const parentToUse = parents.find(
-          (o) =>
-            o.updateToken === updateToken && Optional.isSome(o.getSnapshot()),
-        );
+    });
+
+    this.attach();
+  }
 
-        if (parentToUse === undefined) {
-          return;
-        }
+  override tryUpdate(updateToken: UpdateToken): void {
+    const parentToUse = this.parents.find(
+      (o) => o.updateToken === updateToken && Optional.isSome(o.getSnapshot()),
+    );
 
-        const nextValue =
-          // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-          Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
+    if (parentToUse === undefined) {
+      return;
+    }
 
-        setNext(nextValue, updateToken);
-      },
-  );
+    const nextValue =
+      // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+      Optional.unwrap(parentToUse.getSnapshot()) as ArrayElement<P>;
+
+    this.setNext(nextValue, updateToken);
+  }
+}
 
 if (import.meta.vitest !== undefined) {
   test('type test', () => {

package/src/core/combine/zip.mts

@@ -1,6 +1,13 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @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 { Arr, Optional, createQueue, expectType } from 'ts-data-forge';
 import type { NonEmptyTuple, Tuple } from 'ts-type-forge';
-import { createSyncChildObservable } from '../base/index.mjs';
+import { SyncChildObservableClass } from '../class/index.mjs';
 import { source } from '../create/index.mjs';
 import { withInitialValue } from '../operators/index.mjs';
 import type {
@@ -10,6 +17,7 @@ import type {
   Observable,
   SyncChildObservable,
   TupleToQueueTuple,
+  UpdateToken,
   Wrap,
   ZipObservable,
   ZipObservableRefined,
@@ -18,7 +26,9 @@ import type {
 /**
  * Combines multiple observables by pairing their emissions by index.
  * Waits for all sources to emit their nth value before emitting the nth tuple.
- * Completes when any source completes.
+ * Completes once a completed source has no value left to pair, as RxJS's
+ * `zip` does: at once if it completes with nothing queued, otherwise after
+ * the tuple that takes its last queued value.
  *
  * @template OS - Tuple type of source observables
  * @param parents - Array of observables to zip
@@ -35,7 +45,7 @@ import type {
  * //  Explanation:
  * //  - zip pairs values by their index from multiple sources
  * //  - Waits for all sources to emit at the same index
- * //  - Completes when any source completes
+ * //  - Completes once a completed source has no value left to pair
  *
  * const [letters$, setLetter] = createState<string>('A');
  *
@@ -68,62 +78,97 @@ export const zip = <const OS extends NonEmptyTuple<Observable<unknown>>>(
   parents: OS,
 ): ZipObservableRefined<OS> =>
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  createZipObservable(parents) as unknown as ZipObservableRefined<OS>;
-
-const createZipObservable = <const A extends NonEmptyUnknownList>(
-  parents: Wrap<A>,
-): ZipObservable<A> => {
-  const parentsValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
-    parents,
-    (p) => p.getSnapshot(),
-  );
-
-  // The annotation on `initialValue` is what replaces the type assertion.
-  // `Arr.map` carries a single result element type, so it reports `A[number]`
-  // at every position, and `Tuple.MapTo<A[number], A>` — the uniform mapping
-  // — is *not* assignable back to `A`. The positional
-  // `Readonly<{ [K in keyof A]: A[K] }>` is, and TypeScript accepts the
-  // uniform result into it because the two mapped types share `keyof A`. So
-  // it is the annotation, not an assertion, that records the position-wise
-  // fact the checker cannot derive on its own.
-  const initialValue: Optional<Readonly<{ [K in keyof A]: A[K] }>> = Arr.every(
-    parentsValues,
-    Optional.isSome,
-  )
-    ? Optional.some(Arr.map(parentsValues, (c) => c.value))
-    : Optional.none;
-
-  const queues: TupleToQueueTuple<A> = Arr.map(parents, () => createQueue());
-
-  return createSyncChildObservable<A, A>(
-    {
+  new ZipObservableClass(parents) as unknown as ZipObservableRefined<OS>;
+
+class ZipObservableClass<const A extends NonEmptyUnknownList>
+  extends SyncChildObservableClass<A, A>
+  implements ZipObservable<A>
+{
+  readonly #queues: TupleToQueueTuple<A>;
+
+  /**
+   * The token of each parent's latest value that zip has taken in, so that a
+   * value a parent emits in the update it completes in — its `tryComplete`
+   * reaches zip before its `tryUpdate` does — still counts as queued.
+   * Written in place, one slot per parent, on every update that reaches zip.
+   */
+  // @sumi-expect-error readonly/require-readonly-type
+  readonly #mut_takenTokens: UpdateToken[];
+
+  constructor(parents: Wrap<A>) {
+    const parentsValues: Tuple.MapTo<Optional<A[number]>, A> = Arr.map(
       parents,
-      initialValue,
-    },
-    ({ setNext }) =>
-      (updateToken) => {
-        for (const [index, par] of parents.entries()) {
-          const sn = par.getSnapshot();
-
-          if (par.updateToken === updateToken && Optional.isSome(sn)) {
-            queues[index]?.enqueue(sn.value);
-          }
-        }
-
-        if (queues.some((list) => list.isEmpty)) {
-          return;
-        }
-
-        const nextValue =
-          // `Arr.map` has a single result element type, so it reports
-          // `A[number] | undefined` per position rather than `A[P]`.
-          // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-          Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
-
-        setNext(nextValue, updateToken);
-      },
-  );
-};
+      (p) => p.getSnapshot(),
+    );
+
+    // The annotation on `initialValue` is what replaces the type assertion.
+    // `Arr.map` carries a single result element type, so it reports `A[number]`
+    // at every position, and `Tuple.MapTo<A[number], A>` — the uniform mapping
+    // — is *not* assignable back to `A`. The positional
+    // `Readonly<{ [K in keyof A]: A[K] }>` is, and TypeScript accepts the
+    // uniform result into it because the two mapped types share `keyof A`. So
+    // it is the annotation, not an assertion, that records the position-wise
+    // fact the checker cannot derive on its own.
+    const initialValue: Optional<Readonly<{ [K in keyof A]: A[K] }>> =
+      Arr.every(parentsValues, Optional.isSome)
+        ? Optional.some(Arr.map(parentsValues, (c) => c.value))
+        : Optional.none;
+
+    super({ parents, initialValue });
+
+    this.#queues = Arr.map(parents, () => createQueue());
+
+    this.#mut_takenTokens = Array.from(parents, (p) => p.updateToken);
+
+    this.attach();
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const queues = this.#queues;
+
+    for (const [index, par] of this.parents.entries()) {
+      const sn = par.getSnapshot();
+
+      if (!(par.updateToken === updateToken && Optional.isSome(sn))) {
+        continue;
+      }
+
+      queues[index]?.enqueue(sn.value);
+
+      this.#mut_takenTokens[index] = updateToken;
+    }
+
+    if (queues.some((list) => list.isEmpty)) {
+      return;
+    }
+
+    const nextValue =
+      // `Arr.map` has a single result element type, so it reports
+      // `A[number] | undefined` per position rather than `A[P]`.
+      // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+      Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
+
+    this.setNext(nextValue, updateToken);
+
+    if (this.canEmitNoMore()) {
+      this.complete();
+    }
+  }
+
+  /**
+   * No tuple can be completed any more once a completed source has nothing
+   * left to pair (#2343).
+   */
+  override canEmitNoMore(): boolean {
+    return this.parents.some(
+      (par, index) =>
+        par.isCompleted &&
+        this.#queues[index]?.isEmpty === true &&
+        (par.updateToken === this.#mut_takenTokens[index] ||
+          Optional.isNone(par.getSnapshot())),
+    );
+  }
+}
 
 if (import.meta.vitest !== undefined) {
   test('type test', () => {