synstate 3.2.1 → 3.4.0

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

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

@@ -0,0 +1,56 @@
+import { source } from '../create/index.mjs';
+import { withBufferedFrom } from './with-buffered-from.mjs';
+
+describe('withBufferedFrom teardown', () => {
+  test('unsubscribes from the buffered observable on complete', () => {
+    const data$ = source<string>();
+
+    const trigger$ = source<number>();
+
+    const result$ = trigger$.pipe(withBufferedFrom(data$));
+
+    assert.isTrue(data$.hasSubscriber);
+
+    result$.complete();
+
+    assert.isTrue(result$.isCompleted);
+
+    assert.isFalse(data$.hasSubscriber);
+  });
+
+  test('unsubscribes from the buffered observable when the parent completes', () => {
+    const data$ = source<string>();
+
+    const trigger$ = source<number>();
+
+    const result$ = trigger$.pipe(withBufferedFrom(data$));
+
+    trigger$.complete();
+
+    assert.isTrue(result$.isCompleted);
+
+    assert.isFalse(data$.hasSubscriber);
+  });
+
+  test('keeps buffering while subscribed', () => {
+    const data$ = source<string>();
+
+    const trigger$ = source<number>();
+
+    const result$ = trigger$.pipe(withBufferedFrom(data$));
+
+    const mut_history: (readonly [number, readonly string[]])[] = [];
+
+    result$.subscribe((v) => {
+      mut_history.push(v);
+    });
+
+    data$.next('A');
+
+    data$.next('B');
+
+    trigger$.next(1);
+
+    assert.deepStrictEqual(mut_history, [[1, ['A', 'B']]]);
+  });
+});

package/src/core/types/observable-family.mts

@@ -20,7 +20,11 @@ import type { NonEmptyUnknownList } from './types.mjs';
 // RootObservable
 
 export type InitializedSourceObservable<A> = Readonly<{
-  next: (value: A) => void;
+  /**
+   * Passes `value` on and returns it. Once completed, passes nothing on and
+   * returns the value held.
+   */
+  next: (value: A) => A;
 }> &
   InitializedRootObservable<A>;
 

package/src/core/types/observable.mts

@@ -35,9 +35,28 @@ type CreateObservableType<A, Kind extends ObservableKind> = Readonly<{
   hasChild: boolean;
   hasActiveChild: () => boolean;
 
+  /**
+   * Whether this observable completes itself once nothing uses it any more —
+   * once it has neither subscribers nor live children when one of its children
+   * completes. True when completing it would release something: it has a
+   * teardown of its own (a timer, an inner subscription) or a parent with
+   * `autoComplete`. A `source` or `createState` and everything derived from
+   * it alone are never completed this way, so completing a derived observable
+   * cannot end a state that something else may still read (#2133).
+   */
+  autoComplete: boolean;
+
   tryUpdate: (updateToken: UpdateToken) => void;
   tryComplete: () => void;
   complete: () => void;
+
+  /**
+   * Completes this observable and takes it out of the graph, without telling
+   * its parents: unlike `complete()`, it never completes an upstream
+   * observable, whatever its `autoComplete`. Its descendants are completed as
+   * by `complete()` once none of their parents is live.
+   */
+  dispose: () => void;
   subscribe: (onNext: (v: A) => void, onComplete?: () => void) => Subscription;
 
   pipe: PipeMethod<A>;

package/src/utils/create-event-emitter.mts

@@ -18,13 +18,13 @@ import { source, type Observable } from '../core/index.mjs';
  *
  * emitClick(); // logs: Clicked!
  *
- * assert.deepStrictEqual(mut_clickCount.value, 1);
+ * assert.strictEqual(mut_clickCount.value, 1);
  *
  * emitClick();
  *
  * emitClick();
  *
- * assert.deepStrictEqual(mut_clickCount.value, 3);
+ * assert.strictEqual(mut_clickCount.value, 3);
  * ```
  */
 export const createEventEmitter = (): readonly [

package/src/utils/create-reducer.mts

@@ -11,7 +11,9 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  * @param initialState - The initial value of the state
  * @param options - {@link StateOptions}: `equals`, to pass on only the
  *   dispatches that change the state
- * @returns A 3-element tuple: `[state, dispatch, { getSnapshot, initialState }]`
+ * @returns A 3-element tuple: `[state, dispatch, { getSnapshot, initialState }]`.
+ *   `dispatch` returns the state it leaves; once `state` is completed, that
+ *   is the state held.
  *
  * @example
  * ```ts
@@ -67,6 +69,13 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  *
  * assert.deepStrictEqual(countHistory, [0, 2]);
  * ```
+ *
+ * @note Do not call `dispatch` 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 const createReducer = <S, A>(
   reducer: Reducer<S, A>,
@@ -89,13 +98,10 @@ export const createReducer = <S, A>(
 
     const nextState = reducer(currentState, action);
 
-    if (equals?.(currentState, nextState) === true) {
-      return currentState;
-    }
-
-    state.next(nextState);
-
-    return nextState;
+    // Once completed, `next` keeps the state held and returns it.
+    return equals?.(currentState, nextState) === true
+      ? currentState
+      : state.next(nextState);
   };
 
   const getSnapshot = (): S => state.getSnapshot().value;

package/src/utils/create-reducer.test.mts

@@ -65,6 +65,18 @@ describe(createReducer, () => {
 
     assert.deepStrictEqual(mut_asked, [[0, 5]]);
   });
+
+  test('once the state is completed, a dispatch returns the current state', () => {
+    const [state, dispatch, { getSnapshot }] = createReducer(keepOrAdd, 0);
+
+    dispatch({ type: 'add', amount: 1 });
+
+    state.complete();
+
+    assert.strictEqual(dispatch({ type: 'add', amount: 2 }), 1);
+
+    assert.strictEqual(getSnapshot(), 1);
+  });
 });
 
 type Count = Readonly<{ count: number }>;

package/src/utils/create-state.mts

@@ -88,6 +88,13 @@ const reducer = <S,>(state: S, action: Action<S>): S => {
  *   'label:bug page:2',
  * ]);
  * ```
+ *
+ * @note Do not call `setState`, `updateState` or `resetState` 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 const createState = <S,>(
   initialState: S,

package/src/utils/create-state.test.mts

@@ -34,6 +34,26 @@ describe(createState, () => {
     assert.deepStrictEqual(seen, [0, 1]);
   });
 
+  test('once the state is completed, setState, updateState and resetState return the current value', () => {
+    const [state, setState, { updateState, resetState, getSnapshot }] =
+      createState(0);
+
+    setState(1);
+
+    state.complete();
+
+    assert.strictEqual(setState(2), 1);
+
+    assert.strictEqual(
+      updateState((current) => current + 1),
+      1,
+    );
+
+    assert.strictEqual(resetState(), 1);
+
+    assert.strictEqual(getSnapshot(), 1);
+  });
+
   // What `equals` is for: whatever reads the state, directly or through
   // anything derived from it, is told only of a real change, and an equal
   // value written over the current one leaves the object that is there.