synstate 3.3.0 → 3.4.0

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

package/src/core/create/source.mts

@@ -43,6 +43,13 @@ import type {
  *
  * assert.deepStrictEqual(valueHistory, [1, 2, 3]);
  * ```
+ *
+ * @note Do not call `next` from a subscriber or a projection while another
+ * update is propagating: the write propagates immediately, so subscribers can
+ * see an intermediate state, and it logs a `console.warn` (once per
+ * observable). Derive the value from its source instead —
+ * `const b$ = a$.pipe(map((a) => a * 2))` rather than
+ * `a$.subscribe((a) => { setB(a * 2); })`.
  */
 export function source<const A>(
   initialValue: A,
@@ -51,19 +58,27 @@ export function source<const A>(
 export function source<const A>(): SourceObservable<A>;
 
 export function source<const A>(...args: readonly A[]): SourceObservable<A> {
-  return createRootObservable<A, Readonly<{ next: (nextValue: A) => void }>>(
+  return createRootObservable<
+    A,
+    Readonly<{ next: (nextValue: A) => A | undefined }>
+  >(
     {
       initialValue: Arr.isNonEmpty(args)
         ? Optional.some(args[0])
         : Optional.none,
     },
-    ({ startUpdate, isCompleted }) => ({
+    ({ startUpdate, getSnapshot, isCompleted }) => ({
+      // Returns the value held after the call: `nextValue`, or, once
+      // completed, the value already there — `undefined` only on a source
+      // that never had one, whose `next` is typed `void`.
       next: (nextValue: A) => {
         if (isCompleted()) {
-          return;
+          return Optional.unwrap(getSnapshot());
         }
 
         startUpdate(nextValue);
+
+        return nextValue;
       },
     }),
   );

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

@@ -0,0 +1,41 @@
+import { expectType } from 'ts-data-forge';
+import type { SourceObservable } from '../types/index.mjs';
+import { source } from './source.mjs';
+
+describe(source, () => {
+  test('`next` returns the value it passed on', () => {
+    const count$ = source<number>(0);
+
+    assert.strictEqual(count$.next(1), 1);
+
+    assert.strictEqual(count$.getSnapshot().value, 1);
+  });
+
+  test('once completed, `next` passes nothing on and returns the value held', () => {
+    const count$ = source<number>(0);
+
+    const mut_seen: number[] = [];
+
+    count$.subscribe((value) => {
+      mut_seen.push(value);
+    });
+
+    count$.next(1);
+
+    count$.complete();
+
+    assert.strictEqual(count$.next(2), 1);
+
+    assert.deepStrictEqual(mut_seen, [0, 1]);
+  });
+
+  test('`next` returns the value only on a source with an initial value', () => {
+    const passed = source<number>(0).next(1);
+
+    expectType<typeof passed, number>('=');
+
+    assert.strictEqual(passed, 1);
+
+    expectType<SourceObservable<number>['next'], (value: number) => void>('=');
+  });
+});

package/src/core/operators/merge-map.mts

@@ -98,9 +98,6 @@ import type {
  *   'C3',
  * ]);
  * ```
- *
- * @note To improve code readability, consider using `createState` instead of `mergeMap`,
- * subscribing to `parentObservable` and calling `setState` within it.
  */
 export const mergeMap =
   <A, B>(

package/src/core/operators/skip-until.mts

@@ -4,6 +4,7 @@ import type {
   DropInitialValueOperator,
   Observable,
   SkipUntilOperatorObservable,
+  Subscription,
 } from '../types/index.mjs';
 
 /**
@@ -65,12 +66,28 @@ const createSkipUntilObservable = <A,>(
   parentObservable: Observable<A>,
   notifier: Observable<unknown>,
 ): SkipUntilOperatorObservable<A> => {
-  let mut_isSkipping = true;
+  // A notifier that already holds a value, or has completed, would call
+  // `stopSkipping` inside `subscribe`, before the subscription is stored.
+  let mut_isSkipping =
+    Optional.isNone(notifier.getSnapshot()) && !notifier.isCompleted;
+
+  let mut_subscription: Subscription | undefined = undefined;
+
+  const stopSkipping = (): void => {
+    mut_isSkipping = false;
+
+    mut_subscription?.unsubscribe();
+
+    mut_subscription = undefined;
+  };
 
   const observable = createSyncChildObservable<A, readonly [A]>(
     {
       parents: [parentObservable],
       initialValue: Optional.none,
+      onComplete: () => {
+        mut_subscription?.unsubscribe();
+      },
     },
     ({ setNext }) =>
       (updateToken) => {
@@ -88,14 +105,9 @@ const createSkipUntilObservable = <A,>(
       },
   );
 
-  notifier.subscribe(
-    () => {
-      mut_isSkipping = false;
-    },
-    () => {
-      mut_isSkipping = false;
-    },
-  );
+  if (mut_isSkipping) {
+    mut_subscription = notifier.subscribe(stopSkipping, stopSkipping);
+  }
 
   return observable;
 };

package/src/core/operators/switch-map.mts

@@ -96,9 +96,6 @@ import type {
  *   'C3',
  * ]);
  * ```
- *
- * @note To improve code readability, consider using `createState` instead of `switchMap`,
- * subscribe to `parentObservable` and call `setState` within it.
  */
 export const switchMap =
   <A, B>(

package/src/core/operators/take-until-skip-until-teardown.test.mts

@@ -0,0 +1,127 @@
+import { source } from '../create/index.mjs';
+import { take } from '../predefined/index.mjs';
+import { skipUntil } from './skip-until.mjs';
+import { takeUntil } from './take-until.mjs';
+
+describe('takeUntil releases the notifier', () => {
+  test('when the result is completed before the notifier emits', () => {
+    const notifier$ = source<undefined>();
+
+    const result$ = source<number>().pipe(takeUntil(notifier$));
+
+    assert.isTrue(notifier$.hasSubscriber);
+
+    result$.complete();
+
+    assert.isFalse(notifier$.hasSubscriber);
+  });
+
+  test('when the parent completes', () => {
+    const notifier$ = source<undefined>();
+
+    const num$ = source<number>();
+
+    num$.pipe(takeUntil(notifier$));
+
+    num$.complete();
+
+    assert.isFalse(notifier$.hasSubscriber);
+  });
+
+  test('when the downstream completes', () => {
+    const notifier$ = source<undefined>();
+
+    const num$ = source<number>();
+
+    const taken$ = num$.pipe(takeUntil(notifier$)).pipe(take(1));
+
+    taken$.subscribe(() => {});
+
+    // `take(n)` completes on the emission after its `n`th.
+    num$.next(1);
+
+    num$.next(2);
+
+    assert.isTrue(taken$.isCompleted);
+
+    assert.isFalse(notifier$.hasSubscriber);
+  });
+
+  test('when the notifier emits', () => {
+    const notifier$ = source<undefined>();
+
+    const result$ = source<number>().pipe(takeUntil(notifier$));
+
+    notifier$.next(undefined);
+
+    assert.isTrue(result$.isCompleted);
+
+    assert.isFalse(notifier$.hasSubscriber);
+  });
+
+  test('when the notifier has already emitted', () => {
+    const notifier$ = source<number>(0);
+
+    const result$ = source<number>().pipe(takeUntil(notifier$));
+
+    assert.isTrue(result$.isCompleted);
+
+    assert.isFalse(notifier$.hasSubscriber);
+  });
+});
+
+describe('skipUntil releases the notifier', () => {
+  test('when the notifier emits', () => {
+    const notifier$ = source<undefined>();
+
+    const num$ = source<number>();
+
+    const result$ = num$.pipe(skipUntil(notifier$));
+
+    const mut_history: number[] = [];
+
+    result$.subscribe((x) => {
+      mut_history.push(x);
+    });
+
+    num$.next(1);
+
+    notifier$.next(undefined);
+
+    assert.isFalse(notifier$.hasSubscriber);
+
+    num$.next(2);
+
+    assert.deepStrictEqual(mut_history, [2]);
+  });
+
+  test('when the notifier has already emitted', () => {
+    const notifier$ = source<number>(0);
+
+    const num$ = source<number>();
+
+    const result$ = num$.pipe(skipUntil(notifier$));
+
+    const mut_history: number[] = [];
+
+    result$.subscribe((x) => {
+      mut_history.push(x);
+    });
+
+    assert.isFalse(notifier$.hasSubscriber);
+
+    num$.next(1);
+
+    assert.deepStrictEqual(mut_history, [1]);
+  });
+
+  test('when the result is completed before the notifier emits', () => {
+    const notifier$ = source<undefined>();
+
+    const result$ = source<number>().pipe(skipUntil(notifier$));
+
+    result$.complete();
+
+    assert.isFalse(notifier$.hasSubscriber);
+  });
+});

package/src/core/operators/take-until.mts

@@ -3,6 +3,7 @@ import { createSyncChildObservable } from '../base/index.mjs';
 import type {
   KeepInitialValueOperator,
   Observable,
+  Subscription,
   TakeUntilOperatorObservable,
 } from '../types/index.mjs';
 
@@ -68,10 +69,15 @@ const createTakeUntilObservable = <A,>(
   parentObservable: Observable<A>,
   notifier: Observable<unknown>,
 ): TakeUntilOperatorObservable<A> => {
+  let mut_subscription: Subscription | undefined = undefined;
+
   const observable = createSyncChildObservable<A, readonly [A]>(
     {
       parents: [parentObservable],
       initialValue: parentObservable.getSnapshot(),
+      onComplete: () => {
+        mut_subscription?.unsubscribe();
+      },
     },
     ({ setNext }) =>
       (updateToken) => {
@@ -88,7 +94,7 @@ const createTakeUntilObservable = <A,>(
       },
   );
 
-  notifier.subscribe(
+  const subscription = notifier.subscribe(
     () => {
       observable.complete();
     },
@@ -97,5 +103,13 @@ const createTakeUntilObservable = <A,>(
     },
   );
 
+  // A notifier that already holds a value completes `observable` inside
+  // `subscribe`, before `onComplete` can see the subscription.
+  if (observable.isCompleted) {
+    subscription.unsubscribe();
+  } else {
+    mut_subscription = subscription;
+  }
+
   return observable;
 };

package/src/core/operators/with-buffered-from.mts

@@ -3,6 +3,7 @@ import { createSyncChildObservable } from '../base/index.mjs';
 import type {
   KeepInitialValueOperator,
   Observable,
+  Subscription,
   WithBufferedFromOperatorObservable,
 } from '../types/index.mjs';
 import { maxDepth } from '../utils/index.mjs';
@@ -86,6 +87,8 @@ const createWithBufferedFromObservable = <A, B>(
     mut_bufferedValues = [];
   };
 
+  let mut_subscription: Subscription | undefined = undefined;
+
   const result = createSyncChildObservable<
     readonly [A, readonly B[]],
     readonly [A]
@@ -104,6 +107,11 @@ const createWithBufferedFromObservable = <A, B>(
               Optional.isNone(me) ? [] : [me.value],
             ] as const),
       ).value,
+      onComplete: () => {
+        mut_subscription?.unsubscribe();
+
+        clearBuffer();
+      },
     },
     ({ setNext }) =>
       (updateToken) => {
@@ -122,9 +130,13 @@ const createWithBufferedFromObservable = <A, B>(
       },
   );
 
-  observable.subscribe((value) => {
-    mut_bufferedValues = Arr.toPushed(mut_bufferedValues, value);
-  });
+  // A child completed at creation has already run `onComplete`; subscribing
+  // after it would leave a subscription nothing releases.
+  if (!result.isCompleted) {
+    mut_subscription = observable.subscribe((value) => {
+      mut_bufferedValues = Arr.toPushed(mut_bufferedValues, value);
+    });
+  }
 
   return result;
 };