synstate 3.0.6 → 3.1.0

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

@@ -1,21 +1,21 @@
 import { expectType, type Result } from 'ts-data-forge';
-import {
-  type ArrayElement,
-  type FixedLengthTuple,
-  type NonEmptyTuple,
-  type SafeUint,
+import type {
+  ArrayElement,
+  FixedLengthTuple,
+  NonEmptyTuple,
+  SafeUint,
 } from 'ts-type-forge';
-import {
-  type AsyncChildObservable,
-  type InitializedObservable,
-  type InitializedRootObservable,
-  type InitializedSyncChildObservable,
-  type Observable,
-  type RootObservable,
-  type SyncChildObservable,
-  type Unwrap,
+import type {
+  AsyncChildObservable,
+  InitializedObservable,
+  InitializedRootObservable,
+  InitializedSyncChildObservable,
+  Observable,
+  RootObservable,
+  SyncChildObservable,
+  Unwrap,
 } from './observable.mjs';
-import { type NonEmptyUnknownList } from './types.mjs';
+import type { NonEmptyUnknownList } from './types.mjs';
 
 // RootObservable
 

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

@@ -1,4 +1,4 @@
-import { type StrictExclude } from 'ts-type-forge';
+import type { StrictExclude } from 'ts-type-forge';
 
 export type ObservableKind = 'root' | 'sync child' | 'async child';
 

package/src/core/types/observable.mts

@@ -1,8 +1,8 @@
 import { expectType, type Optional, type Some } from 'ts-data-forge';
-import { type FixedLengthTuple, type StrictOmit } from 'ts-type-forge';
-import { type ObservableId, type UpdateToken } from './id.mjs';
-import { type ObservableKind } from './observable-kind.mjs';
-import { type NonEmptyUnknownList, type Subscription } from './types.mjs';
+import type { FixedLengthTuple, StrictOmit } from 'ts-type-forge';
+import type { ObservableId, UpdateToken } from './id.mjs';
+import type { ObservableKind } from './observable-kind.mjs';
+import type { NonEmptyUnknownList, Subscription } from './types.mjs';
 
 /**
  * Inheritance

package/src/core/types/types.mts

@@ -1,5 +1,5 @@
 import { expectType, type Queue } from 'ts-data-forge';
-import { type NonEmptyTuple } from 'ts-type-forge';
+import type { NonEmptyTuple } from 'ts-type-forge';
 
 export type TupleToQueueTuple<T extends readonly unknown[]> = Readonly<{
   [P in keyof T]: Queue<T[P]>;

package/src/core/utils/id-maker.mts

@@ -1,7 +1,7 @@
-import {
-  type ObservableId,
-  type SubscriberId,
-  type UpdateToken,
+import type {
+  ObservableId,
+  SubscriberId,
+  UpdateToken,
 } from '../types/index.mjs';
 
 function* idMaker<T extends symbol>(): Generator<T, T, T> {

package/src/core/utils/max-depth.mts

@@ -1,5 +1,5 @@
 import { Arr, Optional, pipe } from 'ts-data-forge';
-import { type Observable } from '../types/index.mjs';
+import type { Observable } from '../types/index.mjs';
 
 export const maxDepth = (parents: readonly Observable<unknown>[]): number =>
   pipe(Arr.maxBy(parents, (p) => p.depth))

package/src/core/utils/observable-utils.mts

@@ -1,4 +1,4 @@
-import { type Subscriber } from '../types/index.mjs';
+import type { Subscriber } from '../types/index.mjs';
 
 export const toSubscriber = <A,>(
   onNext: (v: A) => void,

package/src/core/utils/utils.mts

@@ -1,5 +1,5 @@
 import { Arr, asSafeInt, asUint32, SafeInt } from 'ts-data-forge';
-import { type NegativeInt32, type Uint32 } from 'ts-type-forge';
+import type { NegativeInt32, Uint32 } from 'ts-type-forge';
 
 export const halfInt = (x: SafeInt): SafeInt =>
   x % 2 === 0

package/src/utils/collect-to-array.mts

@@ -1,4 +1,4 @@
-import { type Observable } from '../core/index.mjs';
+import type { Observable } from '../core/index.mjs';
 
 export const collectToArray = <A,>(
   observable: Observable<A>,

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

@@ -1,4 +1,5 @@
-import { type InitializedObservable } from '../core/index.mjs';
+import type { InitializedObservable } from '../core/index.mjs';
+import type { StateOptions } from './create-reducer.mjs';
 import { createState } from './create-state.mjs';
 
 /**
@@ -6,6 +7,8 @@ import { createState } from './create-state.mjs';
  * Extends `createState` with boolean-specific helpers like `toggle`, `setTrue`, and `setFalse`.
  *
  * @param initialState - The initial boolean value
+ * @param options - {@link StateOptions}: `equals`, to pass on only the
+ *   updates that change the state
  * @returns A 2-element tuple: `[state, { setTrue, setFalse, toggle, setState, updateState, resetState, getSnapshot, initialState }]`
  *
  * @example
@@ -14,24 +17,25 @@ import { createState } from './create-state.mjs';
  * import { createBooleanState } from 'synstate';
  * import { useObservableValue } from 'synstate-react-hooks';
  *
- *     // Menu drawer open/close state.
- *     // setTrue and setFalse can be passed directly as callbacks
- *     // — no need to create wrapper functions like `() => setState(true)`.
- *     const [menuOpen$, { setTrue: openMenu, setFalse: closeMenu }] =
- *       createBooleanState(false);
+ * // Menu drawer open/close state.
+ * // setTrue and setFalse can be passed directly as callbacks
+ * // — no need to create wrapper functions like `() => setState(true)`.
+ * const [menuOpen$, { setTrue: openMenu, setFalse: closeMenu }] =
+ *   createBooleanState(false);
  *
- *     const SampleComponent = (): React.JSX.Element => (
- *       <MenuDrawer
- *         open={useObservableValue(menuOpen$)}
- *         onClose={closeMenu}
- *         onOpen={openMenu}
- *       />
- *     );
+ * const SampleComponent = (): React.JSX.Element => (
+ *   <MenuDrawer
+ *     open={useObservableValue(menuOpen$)}
+ *     onClose={closeMenu}
+ *     onOpen={openMenu}
+ *   />
+ * );
  * ```
  */
 
 export const createBooleanState = (
   initialState: boolean,
+  options?: StateOptions<boolean>,
 ): readonly [
   state: InitializedObservable<boolean>,
   utils: Readonly<{
@@ -46,7 +50,7 @@ export const createBooleanState = (
   }>,
 ] => {
   const [state, setState, { updateState, resetState, getSnapshot }] =
-    createState(initialState);
+    createState(initialState, options);
 
   return [
     state,

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

@@ -0,0 +1,23 @@
+import { createBooleanState } from './create-boolean-state.mjs';
+
+describe(createBooleanState, () => {
+  test('with `equals`, setting what it already holds passes nothing on', () => {
+    const [state, { setTrue, setFalse }] = createBooleanState(false, {
+      equals: Object.is,
+    });
+
+    const mut_seen: boolean[] = [];
+
+    state.subscribe((value) => {
+      mut_seen.push(value);
+    });
+
+    setFalse();
+
+    setTrue();
+
+    setTrue();
+
+    assert.deepStrictEqual(mut_seen, [false, true]);
+  });
+});

package/src/utils/create-reducer.mts

@@ -1,4 +1,4 @@
-import { type Reducer } from 'ts-type-forge';
+import type { Reducer } from 'ts-type-forge';
 import { source, type InitializedObservable } from '../core/index.mjs';
 
 /**
@@ -9,6 +9,8 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  * @template A - The type of actions
  * @param reducer - A pure function that takes current state and action, returns new state
  * @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 }]`
  *
  * @example
@@ -43,10 +45,33 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  *
  * assert.deepStrictEqual(stateHistory, [0, 1, 2, 1]);
  * ```
+ *
+ * @example
+ * ```ts
+ * const [count, dispatch] = createReducer(
+ *   (s, action: Readonly<{ type: 'add'; amount: number }>) =>
+ *     s + action.amount,
+ *   0,
+ *   { equals: Object.is },
+ * );
+ *
+ * const countHistory: number[] = [];
+ *
+ * count.subscribe((value: number) => {
+ *   countHistory.push(value);
+ * });
+ *
+ * dispatch({ type: 'add', amount: 0 }); // 0 again: nothing is passed on
+ *
+ * dispatch({ type: 'add', amount: 2 });
+ *
+ * assert.deepStrictEqual(countHistory, [0, 2]);
+ * ```
  */
 export const createReducer = <S, A>(
   reducer: Reducer<S, A>,
   initialState: S,
+  options?: StateOptions<NoInfer<S>>,
 ): readonly [
   state: InitializedObservable<S>,
   dispatch: (action: A) => S,
@@ -57,8 +82,16 @@ export const createReducer = <S, A>(
 ] => {
   const state = source<S>(initialState);
 
+  const equals = options?.equals;
+
   const dispatch = (action: A): S => {
-    const nextState = reducer(state.getSnapshot().value, action);
+    const currentState = state.getSnapshot().value;
+
+    const nextState = reducer(currentState, action);
+
+    if (equals?.(currentState, nextState) === true) {
+      return currentState;
+    }
 
     state.next(nextState);
 
@@ -69,3 +102,27 @@ export const createReducer = <S, A>(
 
   return [state, dispatch, { getSnapshot, initialState }] as const;
 };
+
+/**
+ * Options of {@link createReducer}, `createState` and `createBooleanState`.
+ */
+export type StateOptions<S> = Readonly<{
+  /**
+   * Whether the next state is the same as the current one. When it says so,
+   * the update is not passed on — no subscriber, and nothing derived from
+   * the state, is told of it — and the current state is kept, along with its
+   * identity: `setState` and the like return the current state rather than
+   * the next.
+   *
+   * Decide here, where the state is held, rather than downstream with
+   * `skipIfNoChange`: an update passed on here reaches whatever reads the
+   * state directly before any operator can thin it out.
+   *
+   * When omitted, every update is passed on, equal or not. That default is
+   * stocked in `NEXT_MAJOR.md` to become `Object.is`.
+   *
+   * @param current - The state held now
+   * @param next - The state the update would set
+   */
+  equals?: (current: S, next: S) => boolean;
+}>;

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

@@ -0,0 +1,87 @@
+import type { FixedLengthTuple } from 'ts-type-forge';
+import { createReducer } from './create-reducer.mjs';
+
+describe(createReducer, () => {
+  test('passes on every dispatch when no `equals` is given, equal or not', () => {
+    const [state, dispatch] = createReducer(keepOrAdd, 0);
+
+    const seen = record(state);
+
+    dispatch({ type: 'keep' });
+
+    dispatch({ type: 'add', amount: 1 });
+
+    assert.deepStrictEqual(seen, [0, 0, 1]);
+  });
+
+  test('with `equals`, does not pass on a dispatch whose next state is equal to the current one', () => {
+    const [state, dispatch, { getSnapshot }] = createReducer(keepOrAdd, 0, {
+      equals: Object.is,
+    });
+
+    const seen = record(state);
+
+    assert.strictEqual(dispatch({ type: 'keep' }), 0);
+
+    assert.strictEqual(dispatch({ type: 'add', amount: 1 }), 1);
+
+    assert.strictEqual(dispatch({ type: 'add', amount: 0 }), 1);
+
+    assert.deepStrictEqual(seen, [0, 1]);
+
+    assert.strictEqual(getSnapshot(), 1);
+  });
+
+  test('keeps the current object when `equals` finds the next one equal to it', () => {
+    const initial = { count: 0 } as const;
+
+    const [state, dispatch, { getSnapshot }] = createReducer(
+      (_current: Count, next: Count) => next,
+      initial,
+      { equals: (current, next) => current.count === next.count },
+    );
+
+    const seen = record(state);
+
+    assert.strictEqual(dispatch({ count: 0 }), initial);
+
+    assert.strictEqual(getSnapshot(), initial);
+
+    assert.deepStrictEqual(seen, [initial]);
+  });
+
+  test('asks `equals` with the current state first and the next one second', () => {
+    const mut_asked: FixedLengthTuple<2, number>[] = [];
+
+    const [, dispatch] = createReducer(keepOrAdd, 0, {
+      equals: (current, next) => {
+        mut_asked.push([current, next]);
+
+        return false;
+      },
+    });
+
+    dispatch({ type: 'add', amount: 5 });
+
+    assert.deepStrictEqual(mut_asked, [[0, 5]]);
+  });
+});
+
+type Count = Readonly<{ count: number }>;
+
+type KeepOrAdd = Readonly<{ type: 'keep' } | { type: 'add'; amount: number }>;
+
+const keepOrAdd = (current: number, action: KeepOrAdd): number =>
+  action.type === 'keep' ? current : current + action.amount;
+
+const record = <A,>(
+  state: Readonly<{ subscribe: (onNext: (value: A) => void) => unknown }>,
+): readonly A[] => {
+  const mut_seen: A[] = [];
+
+  state.subscribe((value) => {
+    mut_seen.push(value);
+  });
+
+  return mut_seen;
+};

package/src/utils/create-state.mts

@@ -1,5 +1,5 @@
-import { type InitializedObservable } from '../core/index.mjs';
-import { createReducer } from './create-reducer.mjs';
+import type { InitializedObservable } from '../core/index.mjs';
+import { createReducer, type StateOptions } from './create-reducer.mjs';
 
 type Action<S> = Readonly<
   | {
@@ -28,6 +28,8 @@ const reducer = <S,>(state: S, action: Action<S>): S => {
  *
  * @template S - The type of the state
  * @param initialState - The initial value of the state
+ * @param options - {@link StateOptions}: `equals`, to pass on only the
+ *   updates that change the state
  * @returns A 3-element tuple: `[state, setState, { updateState, resetState, getSnapshot, initialState }]`
  *
  * @example
@@ -54,9 +56,42 @@ const reducer = <S,>(state: S, action: Action<S>): S => {
  *
  * assert.deepStrictEqual(stateHistory, [0, 10, 11, 0]);
  * ```
+ *
+ * @example
+ * ```ts
+ * const [filters, setFilters] = createState(
+ *   { label: 'bug', page: 1 },
+ *   { equals: fastDeepEqual },
+ * );
+ *
+ * const before = filters.getSnapshot().value;
+ *
+ * // Derived state is recomputed only when the state really changes.
+ * const query = filters.pipe(
+ *   map(({ label, page }) => `label:${label} page:${page}`),
+ * );
+ *
+ * const queryHistory: string[] = [];
+ *
+ * query.subscribe((value: string) => {
+ *   queryHistory.push(value);
+ * });
+ *
+ * setFilters({ label: 'bug', page: 1 }); // equal: nothing is passed on
+ *
+ * assert.strictEqual(filters.getSnapshot().value, before);
+ *
+ * setFilters({ label: 'bug', page: 2 });
+ *
+ * assert.deepStrictEqual(queryHistory, [
+ *   'label:bug page:1',
+ *   'label:bug page:2',
+ * ]);
+ * ```
  */
 export const createState = <S,>(
   initialState: S,
+  options?: StateOptions<NoInfer<S>>,
 ): readonly [
   state: InitializedObservable<S>,
   setState: (v: S) => S,
@@ -70,6 +105,7 @@ export const createState = <S,>(
   const [state, dispatch, { getSnapshot }] = createReducer<S, Action<S>>(
     reducer,
     initialState,
+    options,
   );
 
   const updateState = (updateFn: (prev: S) => S): S =>

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

@@ -0,0 +1,72 @@
+import { createState } from './create-state.mjs';
+
+describe(createState, () => {
+  test('passes on every update when no `equals` is given, equal or not', () => {
+    const [state, setState] = createState(0);
+
+    const seen = record(state);
+
+    setState(0);
+
+    assert.deepStrictEqual(seen, [0, 0]);
+  });
+
+  test('with `equals`, setState, updateState and resetState do not pass on a value equal to the current one', () => {
+    const [state, setState, { updateState, resetState }] = createState(0, {
+      equals: Object.is,
+    });
+
+    const seen = record(state);
+
+    assert.strictEqual(setState(0), 0);
+
+    assert.strictEqual(
+      updateState((current) => current),
+      0,
+    );
+
+    assert.strictEqual(resetState(), 0);
+
+    setState(1);
+
+    assert.strictEqual(setState(1), 1);
+
+    assert.deepStrictEqual(seen, [0, 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.
+  test('keeps the current object when `equals` finds the next one equal to it', () => {
+    const [state, setState, { getSnapshot }] = createState<readonly number[]>(
+      [1, 2],
+      {
+        equals: (current, next) =>
+          current.length === next.length &&
+          current.every((value, index) => value === next[index]),
+      },
+    );
+
+    const held = getSnapshot();
+
+    const seen = record(state);
+
+    assert.strictEqual(setState([1, 2]), held);
+
+    assert.strictEqual(getSnapshot(), held);
+
+    assert.deepStrictEqual(seen, [held]);
+  });
+});
+
+const record = <A,>(
+  state: Readonly<{ subscribe: (onNext: (value: A) => void) => unknown }>,
+): readonly A[] => {
+  const mut_seen: A[] = [];
+
+  state.subscribe((value) => {
+    mut_seen.push(value);
+  });
+
+  return mut_seen;
+};