synstate 3.2.1 → 3.4.0

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);
       },
     }),

package/src/core/create/counter.test.mts

@@ -1,4 +1,5 @@
 import { Arr } from 'ts-data-forge';
+import { map } from '../operators/index.mjs';
 import { counter } from './counter.mjs';
 
 describe(counter, () => {
@@ -191,4 +192,85 @@ describe(counter, () => {
 
     vi.useRealTimers();
   });
+
+  test.each([
+    { emitInitial: true, expected: [0, 1, 2] },
+    { emitInitial: false, expected: [1, 2, 3] },
+  ] as const)(
+    'times: 3, emitInitial: $emitInitial completes right after the third emission',
+    ({ emitInitial, expected }) => {
+      vi.useFakeTimers();
+
+      const counter$ = counter(100, { times: 3, emitInitial });
+
+      const mut_history: number[] = [];
+
+      counter$.subscribe((n) => {
+        mut_history.push(n);
+      });
+
+      vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(
+        mut_history,
+        Arr.take(expected, 2),
+      );
+
+      assert.isFalse(counter$.isCompleted);
+
+      vi.advanceTimersToNextTimer();
+
+      assert.deepStrictEqual<readonly number[]>(mut_history, expected);
+
+      assert.isTrue(counter$.isCompleted);
+
+      assert.strictEqual(vi.getTimerCount(), 0);
+
+      vi.useRealTimers();
+    },
+  );
+
+  test('times: 1 emits only the 0 and clears the interval', () => {
+    vi.useFakeTimers();
+
+    const counter$ = counter(100, { times: 1 });
+
+    const mut_history: number[] = [];
+
+    counter$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    vi.advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [0]);
+
+    assert.isTrue(counter$.isCompleted);
+
+    assert.strictEqual(vi.getTimerCount(), 0);
+
+    vi.useRealTimers();
+  });
+
+  test('times completes the downstream after the last value reaches it', () => {
+    vi.useFakeTimers();
+
+    const counter$ = counter(100, { times: 2 });
+
+    const doubled$ = counter$.pipe(map((n) => n * 2));
+
+    const mut_history: number[] = [];
+
+    doubled$.subscribe((n) => {
+      mut_history.push(n);
+    });
+
+    vi.advanceTimersToNextTimer().advanceTimersToNextTimer();
+
+    assert.deepStrictEqual(mut_history, [0, 2]);
+
+    assert.isTrue(doubled$.isCompleted);
+
+    vi.useRealTimers();
+  });
 });

package/src/core/create/from-subscribable.mts

@@ -3,6 +3,7 @@ import { createRootObservable } from '../base/index.mjs';
 import type {
   FromSubscribableObservable,
   Subscribable,
+  Subscription,
 } from '../types/index.mjs';
 
 /**
@@ -65,11 +66,25 @@ import type {
  */
 export const fromSubscribable = <A, E = unknown>(
   subscribable: Subscribable<A>,
-): FromSubscribableObservable<A, E> =>
-  createRootObservable<Result<A, E>>(
-    { initialValue: Optional.none },
-    ({ startUpdate, complete }) => {
-      subscribable.subscribe(
+): FromSubscribableObservable<A, E> => {
+  let mut_subscription: Subscription | undefined = undefined;
+
+  // Set once the subscribable has completed: its subscription is over, so
+  // completing this observable must not unsubscribe from it again.
+  let mut_isSourceCompleted = false;
+
+  const unsubscribe = (): void => {
+    if (!mut_isSourceCompleted) {
+      mut_subscription?.unsubscribe();
+    }
+
+    mut_subscription = undefined;
+  };
+
+  return createRootObservable<Result<A, E>>(
+    { initialValue: Optional.none, onComplete: unsubscribe },
+    ({ startUpdate, isCompleted, complete }) => {
+      const subscription = subscribable.subscribe(
         (nextValue) => {
           startUpdate(Result.ok(nextValue));
         },
@@ -82,10 +97,23 @@ export const fromSubscribable = <A, E = unknown>(
           );
         },
         () => {
+          mut_isSourceCompleted = true;
+
           complete();
         },
       );
 
+      // `subscribe` may have completed this observable before returning
+      // the subscription, so `unsubscribe` above had nothing to release.
+      if (isCompleted()) {
+        if (!mut_isSourceCompleted) {
+          subscription.unsubscribe();
+        }
+      } else {
+        mut_subscription = subscription;
+      }
+
       return {};
     },
   );
+};

package/src/core/create/from-subscribable.test.mts

@@ -0,0 +1,129 @@
+import { Result } from 'ts-data-forge';
+import { take } from '../predefined/index.mjs';
+import type { Subscribable } from '../types/index.mjs';
+import { fromSubscribable } from './from-subscribable.mjs';
+
+describe(fromSubscribable, () => {
+  test('complete() unsubscribes from the subscribable once', () => {
+    const { subscribable, emit, unsubscribe } = createManualSubscribable();
+
+    const observable$ = fromSubscribable(subscribable);
+
+    observable$.complete();
+
+    observable$.complete();
+
+    expect(unsubscribe).toHaveBeenCalledExactlyOnceWith();
+
+    emit(1);
+
+    assert.isTrue(observable$.isCompleted);
+  });
+
+  test('dispose() unsubscribes from the subscribable', () => {
+    const { subscribable, unsubscribe } = createManualSubscribable();
+
+    fromSubscribable(subscribable).dispose();
+
+    expect(unsubscribe).toHaveBeenCalledExactlyOnceWith();
+  });
+
+  test('does not unsubscribe when the subscribable completes first', () => {
+    const { subscribable, emit, completeSource, unsubscribe } =
+      createManualSubscribable();
+
+    const observable$ = fromSubscribable(subscribable);
+
+    const mut_history: number[] = [];
+
+    observable$.subscribe((result) => {
+      if (Result.isOk(result)) {
+        mut_history.push(result.value);
+      }
+    });
+
+    emit(1);
+
+    completeSource();
+
+    assert.isTrue(observable$.isCompleted);
+
+    observable$.complete();
+
+    expect(unsubscribe).not.toHaveBeenCalled();
+
+    assert.deepStrictEqual(mut_history, [1]);
+  });
+
+  test('does not unsubscribe when the subscribable completes synchronously during subscribe', () => {
+    const unsubscribe = vi.fn<() => void>();
+
+    const observable$ = fromSubscribable<number>({
+      subscribe: (_onNext, _onError, onComplete) => {
+        onComplete?.();
+
+        return { unsubscribe };
+      },
+    });
+
+    assert.isTrue(observable$.isCompleted);
+
+    expect(unsubscribe).not.toHaveBeenCalled();
+  });
+
+  test('a child that completes with nothing else using it unsubscribes from the subscribable', () => {
+    const { subscribable, emit, unsubscribe } = createManualSubscribable();
+
+    const observable$ = fromSubscribable(subscribable);
+
+    const taken$ = observable$.pipe(take(1));
+
+    taken$.subscribe(() => {});
+
+    emit(1);
+
+    emit(2);
+
+    assert.isTrue(taken$.isCompleted);
+
+    assert.isTrue(observable$.isCompleted);
+
+    expect(unsubscribe).toHaveBeenCalledExactlyOnceWith();
+  });
+});
+
+const createManualSubscribable = (): Readonly<{
+  subscribable: Subscribable<number>;
+  emit: (value: number) => void;
+  completeSource: () => void;
+  unsubscribe: () => void;
+}> => {
+  let mut_onNext: ((value: number) => void) | undefined = undefined;
+
+  let mut_onComplete: (() => void) | undefined = undefined;
+
+  const unsubscribe = vi.fn<() => void>(() => {
+    mut_onNext = undefined;
+
+    mut_onComplete = undefined;
+  });
+
+  return {
+    subscribable: {
+      subscribe: (onNext, _onError, onComplete) => {
+        mut_onNext = onNext;
+
+        mut_onComplete = onComplete;
+
+        return { unsubscribe };
+      },
+    },
+    emit: (value) => {
+      mut_onNext?.(value);
+    },
+    completeSource: () => {
+      mut_onComplete?.();
+    },
+    unsubscribe,
+  };
+};