synstate 3.3.0 → 3.4.0

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/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.