synstate 3.3.0 → 3.4.0

package/src/core/base/create-child-observable.mts

@@ -57,6 +57,14 @@ type ChildObservableConfigBase<P extends NonEmptyUnknownList> = Readonly<{
    * `override complete() { teardown(); super.complete(); }`.
    */
   onComplete?: () => void;
+
+  /**
+   * Whether this observable can emit nothing more although some parent is
+   * still live, asked whenever a parent completes. `true` completes it then,
+   * as all parents completing does (`zip` once a completed source's queue is
+   * empty).
+   */
+  canEmitNoMore?: () => boolean;
 }>;
 
 export type ChildObservableConfig<
@@ -91,6 +99,7 @@ export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
     depth = 1 + maxDepth(parents),
     initialValue,
     onComplete,
+    canEmitNoMore,
   }: ChildObservableConfig<A, P>,
   createTryUpdate: (
     tools: SyncChildObservableTools<A>,
@@ -140,6 +149,7 @@ export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
     }
 
     tryCompleteChild({
+      canEmitNoMore,
       hasSubscriber: handle.hasSubscriber(),
       hasActiveChild: handle.hasActiveChild(),
       autoComplete,
@@ -166,9 +176,16 @@ export const createSyncChildObservable = <A, P extends NonEmptyUnknownList>(
     extra: { parents },
   });
 
-  registerChild(observable, parents);
+  // Completed parents never update again, so a child created under them is
+  // complete from the start; registering it would only leave a reference in
+  // each parent (#2248).
+  if (parents.every((p) => p.isCompleted)) {
+    dispose();
+  } else {
+    registerChild(observable, parents);
 
-  mut_self = observable;
+    mut_self = observable;
+  }
 
   return observable;
 };
@@ -210,6 +227,7 @@ export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
     depth = 1 + maxDepth(parents),
     initialValue,
     onComplete,
+    canEmitNoMore,
   }: ChildObservableConfig<A, P>,
   createTryUpdate: (
     tools: AsyncChildObservableTools<A>,
@@ -262,6 +280,7 @@ export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
     }
 
     tryCompleteChild({
+      canEmitNoMore,
       hasSubscriber: handle.hasSubscriber(),
       hasActiveChild: handle.hasActiveChild(),
       autoComplete,
@@ -289,9 +308,16 @@ export const createAsyncChildObservable = <A, P extends NonEmptyUnknownList>(
     extra: { parents, addDescendant, deleteDescendant },
   });
 
-  registerChild(observable, parents);
+  // Completed parents never update again, so a child created under them is
+  // complete from the start; registering it would only leave a reference in
+  // each parent (#2248).
+  if (parents.every((p) => p.isCompleted)) {
+    dispose();
+  } else {
+    registerChild(observable, parents);
 
-  mut_self = observable;
+    mut_self = observable;
+  }
 
   return observable;
 };
@@ -426,20 +452,22 @@ const unregisterChild = <A,>(
 };
 
 const tryCompleteChild = <A,>({
+  canEmitNoMore,
   hasSubscriber,
   hasActiveChild,
   autoComplete,
   parents,
   complete,
 }: Readonly<{
+  canEmitNoMore: (() => boolean) | undefined;
   hasSubscriber: boolean;
   hasActiveChild: boolean;
   autoComplete: boolean;
   parents: ChildObservable<A>['parents'];
   complete: () => void;
 }>): void => {
-  // If there is no working parent node
-  if (parents.every((r) => r.isCompleted)) {
+  // If there is no working parent node, or no value can come from the live ones
+  if (parents.every((r) => r.isCompleted) || canEmitNoMore?.() === true) {
     complete();
 
     return;

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

@@ -285,6 +285,16 @@ export const createObservableBaseHandle = <A,>(
   };
 };
 
+/**
+ * How many `startUpdate` calls are running, across every observable. A root
+ * written to while this is non-zero is written to from inside a subscriber or
+ * a projection, which {@link isPropagating} lets it detect (#2336).
+ */
+const mut_propagation = { depth: 0 };
+
+/** Whether some observable's update is propagating right now. */
+export const isPropagating = (): boolean => mut_propagation.depth > 0;
+
 /**
  * The extra members every manager observable — a root or an async child — owns:
  * the depth-ordered descendant list and the update propagation that walks it.
@@ -389,10 +399,20 @@ export const createManagerObservableParts = <A,>(
   const startUpdate = (nextValue: A): void => {
     const updateToken = issueUpdateToken();
 
-    handle.setNext(nextValue, updateToken);
+    mut_propagation.depth += 1;
+
+    // A subscriber or projection may throw, and the depth has to come back
+    // down regardless, or every later write would warn. The exception itself
+    // is not caught: it reaches the caller of `next` as it always has.
+    // @sumi-expect-error exceptions/no-try
+    try {
+      handle.setNext(nextValue, updateToken);
 
-    for (const p of getPropagationOrder()) {
-      p.tryUpdate(updateToken);
+      for (const p of getPropagationOrder()) {
+        p.tryUpdate(updateToken);
+      }
+    } finally {
+      mut_propagation.depth -= 1;
     }
   };
 

package/src/core/base/create-root-observable.mts

@@ -6,6 +6,7 @@ import {
   createManagerObservableParts,
   createObservableBaseHandle,
   createTryUpdateNotImplemented,
+  isPropagating,
 } from './create-observable-base.mjs';
 
 /**
@@ -17,6 +18,8 @@ export type RootObservableTools<A> = Readonly<{
   /** Emits `nextValue` and propagates the update to all descendants. */
   startUpdate: (nextValue: A) => void;
 
+  getSnapshot: () => Optional<A>;
+
   isCompleted: () => boolean;
 
   /** Completes this observable (leaf teardown included). */
@@ -78,12 +81,33 @@ export const createRootObservable = <
     }
   };
 
+  // A root created while an update propagates (inside a `switchMap`
+  // projection, say) may emit synchronously while `init` runs, as
+  // `fromSubscribable` does for a synchronous source. Nothing is derived from
+  // it yet, so that is its initial value rather than a write (#2336).
+  let mut_isInitializing = true;
+
+  let mut_hasWarned = false;
+
+  const startUpdateWithWarning = (nextValue: A): void => {
+    if (!mut_isInitializing && !mut_hasWarned && isPropagating()) {
+      mut_hasWarned = true;
+
+      console.warn(writeDuringPropagationWarning);
+    }
+
+    startUpdate(nextValue);
+  };
+
   const extension: Extension = init({
-    startUpdate,
+    startUpdate: startUpdateWithWarning,
+    getSnapshot: handle.getSnapshot,
     isCompleted: handle.isCompleted,
     complete,
   });
 
+  mut_isInitializing = false;
+
   return assembleObservable({
     kind: 'root',
     depth: 0,
@@ -102,6 +126,16 @@ export const createRootObservable = <
   });
 };
 
+/**
+ * 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(

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

@@ -0,0 +1,234 @@
+import { Result } from 'ts-data-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 './create-root-observable.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) {
+        // @sumi-expect-error exceptions/no-throw
+        throw new Error('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/merge.mts

@@ -58,9 +58,6 @@ 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,

package/src/core/combine/zip.mts

@@ -10,6 +10,7 @@ import type {
   Observable,
   SyncChildObservable,
   TupleToQueueTuple,
+  UpdateToken,
   Wrap,
   ZipObservable,
   ZipObservableRefined,
@@ -18,7 +19,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 +38,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');
  *
@@ -95,19 +98,43 @@ const createZipObservable = <const A extends NonEmptyUnknownList>(
 
   const queues: TupleToQueueTuple<A> = Arr.map(parents, () => createQueue());
 
+  // 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.
+  const mut_takenTokens: UpdateToken[] = Array.from(
+    parents,
+    (p) => p.updateToken,
+  );
+
+  // No tuple can be completed any more once a completed source has nothing
+  // left to pair (#2343).
+  const canEmitNoMore = (): boolean =>
+    parents.some(
+      (par, index) =>
+        par.isCompleted &&
+        queues[index]?.isEmpty === true &&
+        (par.updateToken === mut_takenTokens[index] ||
+          Optional.isNone(par.getSnapshot())),
+    );
+
   return createSyncChildObservable<A, A>(
     {
       parents,
       initialValue,
+      canEmitNoMore,
     },
-    ({ setNext }) =>
+    ({ setNext, complete }) =>
       (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 (!(par.updateToken === updateToken && Optional.isSome(sn))) {
+            continue;
           }
+
+          queues[index]?.enqueue(sn.value);
+
+          mut_takenTokens[index] = updateToken;
         }
 
         if (queues.some((list) => list.isEmpty)) {
@@ -121,6 +148,10 @@ const createZipObservable = <const A extends NonEmptyUnknownList>(
           Arr.map(queues, (q) => Optional.unwrap(q.dequeue())) as A;
 
         setNext(nextValue, updateToken);
+
+        if (canEmitNoMore()) {
+          complete();
+        }
       },
   );
 };

package/src/core/create/counter.mts

@@ -1,4 +1,5 @@
 import { asSafeUint, Optional, SafeUint } from 'ts-data-forge';
+import type { PositiveSafeIntWithSmallInt } from 'ts-type-forge';
 import { createRootObservable } from '../base/index.mjs';
 import type { CounterObservable, TimerId } from '../types/index.mjs';
 
@@ -15,6 +16,10 @@ import type { CounterObservable, TimerId } from '../types/index.mjs';
  * @param options.emitInitial - If false, skips the 0 emitted right after
  *   `start()`, so the first value is 1, one interval later — like RxJS
  *   `interval` rather than `timer(0, ms)` (default: true)
+ * @param options.times - If set, completes right after the `times`-th
+ *   emission and clears its timers. Completion does not travel upstream, so
+ *   `counter(ms).pipe(take(n))` leaves the counter running; pass `times` to
+ *   the counter instead (default: unlimited)
  * @returns An observable that emits sequential numbers
  *
  * @example
@@ -45,11 +50,11 @@ import type { CounterObservable, TimerId } from '../types/index.mjs';
  *
  * assert.isTrue(Arr.isMinLengthArray(3, valueHistory));
  *
- * assert.deepStrictEqual(valueHistory[0], 0);
+ * assert.strictEqual(valueHistory[0], 0);
  *
- * assert.deepStrictEqual(valueHistory[1], 1);
+ * assert.strictEqual(valueHistory[1], 1);
  *
- * assert.deepStrictEqual(valueHistory[2], 2);
+ * assert.strictEqual(valueHistory[2], 2);
  * ```
  */
 export const counter = (
@@ -57,6 +62,7 @@ export const counter = (
   options?: Readonly<{
     startManually?: boolean;
     emitInitial?: boolean;
+    times?: PositiveSafeIntWithSmallInt;
   }>,
 ): CounterObservable => {
   let mut_counter: SafeUint = asSafeUint(0);
@@ -67,6 +73,8 @@ export const counter = (
 
   let mut_isStarted = false;
 
+  let mut_emittedCount = 0;
+
   const resetTimer = (): void => {
     if (mut_timerId0 !== undefined) {
       clearTimeout(mut_timerId0);
@@ -82,7 +90,7 @@ export const counter = (
     Readonly<{ start: () => void }>
   >(
     { initialValue: Optional.none, onComplete: resetTimer },
-    ({ startUpdate, isCompleted }) => ({
+    ({ startUpdate, isCompleted, complete }) => ({
       start: () => {
         if (mut_isStarted) {
           console.warn('cannot start twice');
@@ -98,16 +106,29 @@ export const counter = (
           return;
         }
 
+        const emit = (value: SafeUint): void => {
+          startUpdate(value);
+
+          mut_emittedCount += 1;
+
+          if (
+            options?.times !== undefined &&
+            mut_emittedCount >= options.times
+          ) {
+            complete();
+          }
+        };
+
         if (options?.emitInitial ?? true) {
           mut_timerId0 = setTimeout(() => {
-            startUpdate(mut_counter);
+            emit(mut_counter);
           }, 0);
         }
 
         mut_timerId = setInterval(() => {
           mut_counter = SafeUint.add(1, mut_counter);
 
-          startUpdate(mut_counter);
+          emit(mut_counter);
         }, intervalMilliSeconds);
       },
     }),