synstate 4.0.0 → 5.0.0

package/src/core/class/update-loop.test.mts

@@ -0,0 +1,104 @@
+import { createState } from '../../utils/index.mjs';
+import { map } from '../operators/index.mjs';
+import { maxUpdateNesting, updateLoopMessage } from './propagation-state.mjs';
+
+describe('an update that keeps starting another inside itself', () => {
+  test('a subscriber that writes back to its own root throws a named error, not a stack overflow', () => {
+    const [a$, setA] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a > 0) {
+        setA(a + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      expect(() => {
+        setA(1);
+      }).toThrow(updateLoopMessage);
+    });
+  });
+
+  test('two subscribers writing to each other’s roots throw the same error', () => {
+    const [a$, setA] = createState(0);
+
+    const [b$, setB] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a > 0) {
+        setB(a + 1);
+      }
+    });
+
+    b$.subscribe((b) => {
+      if (b > 0) {
+        setA(b + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      expect(() => {
+        setA(1);
+      }).toThrow(updateLoopMessage);
+    });
+  });
+
+  test('updates work as before once the loop has thrown', () => {
+    const [a$, setA] = createState(0);
+
+    a$.subscribe((a) => {
+      if (a > 0) {
+        setA(a + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      expect(() => {
+        setA(1);
+      }).toThrow(updateLoopMessage);
+    });
+
+    const [b$, setB] = createState(0);
+
+    const mut_received: number[] = [];
+
+    b$.pipe(map((b) => b * 10)).subscribe((b) => {
+      mut_received.push(b);
+    });
+
+    setB(1);
+
+    setB(2);
+
+    assert.deepStrictEqual(mut_received, [0, 10, 20]);
+  });
+
+  test('a write that converges may nest up to the limit', () => {
+    const [a$, setA, { getSnapshot }] = createState(0);
+
+    a$.subscribe((a) => {
+      if (0 < a && a < maxUpdateNesting) {
+        setA(a + 1);
+      }
+    });
+
+    withoutWarnings(() => {
+      setA(1);
+    });
+
+    assert.strictEqual(getSnapshot(), maxUpdateNesting);
+  });
+});
+
+/**
+ * Runs `run` with `console.warn` silenced: every case here writes from a
+ * subscriber, which warns once per root.
+ */
+const withoutWarnings = (run: () => void): void => {
+  vi.stubGlobal('console', { ...console, warn: vi.fn() });
+
+  run();
+
+  // cspell:disable-next-line
+  vi.unstubAllGlobals();
+};

package/src/core/create/empty.mts

@@ -0,0 +1,42 @@
+import { Optional } from 'ts-data-forge';
+import { RootObservableClass } from '../class/index.mjs';
+import type { RootObservable } from '../types/index.mjs';
+
+/**
+ * Creates an Observable that holds no value and is already completed, so it
+ * never passes anything on (almost equivalent to RxJS `EMPTY`). Useful inside
+ * `switchMap` for the branch that should follow nothing, where a `source()`
+ * would offer a `next` that nothing calls.
+ *
+ * @template A - The type of the values it would carry
+ * @returns An Observable with no value that is already completed
+ *
+ * @example
+ * ```ts
+ * const nothing$ = empty<number>();
+ *
+ * const valueHistory: number[] = [];
+ *
+ * nothing$.subscribe(
+ *   (value) => {
+ *     valueHistory.push(value);
+ *   },
+ *   () => {
+ *     // onComplete — called immediately since empty() completes right away
+ *   },
+ * );
+ *
+ * assert.deepStrictEqual(valueHistory, []);
+ *
+ * assert.strictEqual(nothing$.isCompleted, true);
+ * ```
+ */
+export const empty = <A,>(): RootObservable<A> => {
+  const obs = new RootObservableClass<A>({
+    initialValue: Optional.none,
+  });
+
+  obs.complete();
+
+  return obs;
+};

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

@@ -0,0 +1,65 @@
+import { Arr, Optional } from 'ts-data-forge';
+import { createState } from '../../utils/index.mjs';
+import { switchMap } from '../operators/index.mjs';
+import { empty } from './empty.mjs';
+
+describe(empty, () => {
+  test('holds no value and is already completed', () => {
+    const nothing$ = empty<number>();
+
+    assert.isTrue(nothing$.isCompleted);
+
+    assert.isTrue(Optional.isNone(nothing$.getSnapshot()));
+  });
+
+  test('passes nothing on to a subscriber, and completes it at once', () => {
+    const nothing$ = empty<number>();
+
+    const mut_seen: number[] = [];
+
+    const mut_completed = { value: false };
+
+    nothing$.subscribe(
+      (value) => {
+        mut_seen.push(value);
+      },
+      () => {
+        mut_completed.value = true;
+      },
+    );
+
+    assert.deepStrictEqual(mut_seen, []);
+
+    assert.isTrue(mut_completed.value);
+  });
+
+  test('switched to, it passes nothing on, and switchMap goes on', () => {
+    const [on$, setOn] = createState(true);
+
+    const [count$, setCount] = createState(0);
+
+    const followed$ = on$.pipe(
+      switchMap((isOn) => (isOn ? count$ : empty<number>())),
+    );
+
+    const mut_seen: number[] = [];
+
+    followed$.subscribe((value) => {
+      mut_seen.push(value);
+    });
+
+    setOn(false);
+
+    const seenBefore = Arr.length(mut_seen);
+
+    setCount(1);
+
+    assert.strictEqual(Arr.length(mut_seen), seenBefore);
+
+    setOn(true);
+
+    assert.deepStrictEqual(Arr.last(mut_seen), Optional.some(1));
+
+    assert.isFalse(followed$.isCompleted);
+  });
+});

package/src/core/create/index.mts

@@ -1,4 +1,5 @@
 export * from './counter.mjs';
+export * from './empty.mjs';
 export * from './from-abortable-promise.mjs';
 export * from './from-promise.mjs';
 export * from './from-subscribable.mjs';

package/src/core/operators/index.mts

@@ -1,6 +1,7 @@
 export * from './audit.mjs';
 export * from './debounce.mjs';
 export * from './filter.mjs';
+export * from './keep-equal-parts.mjs';
 export * from './map.mjs';
 export * from './merge-map.mjs';
 export * from './pairwise.mjs';

package/src/core/operators/keep-equal-parts.mts

@@ -0,0 +1,167 @@
+// Sumi bans classes, `this`, method syntax and writes to `this` outside a
+// `mut_` binding; an observable is a class (`ObservableBaseClass` says why),
+// so those rules are waived here (D-63).
+// @sumi-expect-error-file classes/no-class
+// @sumi-expect-error-file banned-syntax/no-this
+// @sumi-expect-error-file functions/prefer-arrow-function
+// @sumi-expect-error-file mutation/no-mutation-without-mut-prefix
+import {
+  Optional,
+  replaceEqualDeep,
+  type ReplaceEqualDeepOptions,
+} from 'ts-data-forge';
+import { SyncChildObservableClass } from '../class/index.mjs';
+import type {
+  KeepEqualPartsOperatorObservable,
+  KeepInitialValueOperator,
+  Observable,
+  UpdateToken,
+} from '../types/index.mjs';
+
+/**
+ * Passes on each value with every part deeply equal to the same part of the
+ * value passed on before replaced by that part, and skips a value deeply
+ * equal to it altogether (structural sharing). A reader of a part that did
+ * not change keeps the object it has, so `skipIfNoChange()` with `Object.is`
+ * stops it. Superset of `skipIfNoChange(fastDeepEqual)`.
+ *
+ * **Prefer keeping references where the value is written** — compare before
+ * `setState`, and skip it when nothing changed — so that nothing downstream
+ * has anything to undo. The `keepEqualParts` option of `createState` and
+ * `createReducer` does it for a state written whole, and `replaceEqualDeep`
+ * of ts-data-forge does it for any other write. This operator lets every
+ * update that changes nothing reach the source and everything up to it, and
+ * walks the whole value again on each one; reach for it when the source is
+ * not yours to change (a stream that arrives whole from outside).
+ *
+ * Array items are matched by index; pass `{ key }` to match them by key, an
+ * item for which `key` returns `undefined` being matched by index. Only plain
+ * objects and arrays are walked into; a `Map`, a `Set`, a `Date` or a class
+ * instance is compared and kept whole. The values must not be changed after
+ * they are passed on, because the parts kept are shared by later values.
+ *
+ * @template A - The type of values from the source
+ * @param options - `key`, to match array items by key rather than by index
+ * @returns An operator that keeps the parts that did not change
+ *
+ * @example
+ * ```ts
+ * type Board = DeepReadonly<{
+ *   title: string;
+ *   cards: { id: number; text: string }[];
+ * }>;
+ *
+ * // A stream that arrives whole from outside (a WebSocket, say), each
+ * // message a new object even when nothing changed. A state you write
+ * // yourself takes `createState(initial, { keepEqualParts: true })`
+ * // instead.
+ * const message$ = source<Board>();
+ *
+ * const board$ = message$.pipe(keepEqualParts());
+ *
+ * const firstCard$ = board$
+ *   .pipe(map((board) => board.cards[0]))
+ *   .pipe(skipIfNoChange());
+ *
+ * const boardHistory: Board[] = [];
+ *
+ * board$.subscribe((board) => {
+ *   boardHistory.push(board);
+ * });
+ *
+ * const firstCardHistory: unknown[] = [];
+ *
+ * firstCard$.subscribe((card) => {
+ *   firstCardHistory.push(card);
+ * });
+ *
+ * message$.next({ title: 'todo', cards: [{ id: 1, text: 'a' }] });
+ *
+ * // Equal to the last one: nothing is passed on.
+ * message$.next({ title: 'todo', cards: [{ id: 1, text: 'a' }] });
+ *
+ * assert.strictEqual(boardHistory.length, 1);
+ *
+ * // A card added: a new board, but the first card is the one passed on
+ * // before, so `firstCard$` is not told of it.
+ * message$.next({
+ *   title: 'todo',
+ *   cards: [
+ *     { id: 1, text: 'a' },
+ *     { id: 2, text: 'b' },
+ *   ],
+ * });
+ *
+ * assert.strictEqual(boardHistory.length, 2);
+ *
+ * assert.strictEqual(boardHistory[1]?.cards[0], boardHistory[0]?.cards[0]);
+ *
+ * assert.strictEqual(firstCardHistory.length, 1);
+ * ```
+ */
+export const keepEqualParts = <A,>(
+  options?: ReplaceEqualDeepOptions,
+): KeepInitialValueOperator<A, A> =>
+  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
+  ((parentObservable) =>
+    new KeepEqualPartsObservableClass(
+      parentObservable,
+      options,
+    )) as KeepInitialValueOperator<A, A>;
+
+class KeepEqualPartsObservableClass<A>
+  extends SyncChildObservableClass<A, readonly [A]>
+  implements KeepEqualPartsOperatorObservable<A>
+{
+  readonly #options: ReplaceEqualDeepOptions | undefined;
+  #mut_previousValue: Optional<A>;
+
+  constructor(
+    parentObservable: Observable<A>,
+    options: ReplaceEqualDeepOptions | undefined,
+  ) {
+    super({
+      parents: [parentObservable],
+      initialValue: parentObservable.getSnapshot(),
+    });
+
+    this.#mut_previousValue = parentObservable.getSnapshot();
+
+    this.#options = options;
+
+    this.attach();
+  }
+
+  override tryUpdate(updateToken: UpdateToken): void {
+    const par = this.parents[0];
+
+    const sn = par.getSnapshot();
+
+    if (par.updateToken !== updateToken || Optional.isNone(sn)) {
+      return; // skip update
+    }
+
+    const prev = this.#mut_previousValue;
+
+    if (Optional.isNone(prev)) {
+      this.#mut_previousValue = sn;
+
+      this.setNext(sn.value, updateToken);
+
+      return;
+    }
+
+    const kept = replaceEqualDeep(prev.value, sn.value, this.#options);
+
+    if (Object.is(kept, prev.value)) {
+      return;
+    }
+
+    // Updated before `setNext`, which can lead back here.
+    this.#mut_previousValue = Object.is(kept, sn.value)
+      ? sn
+      : Optional.some(kept);
+
+    this.setNext(kept, updateToken);
+  }
+}

package/src/core/operators/keep-equal-parts.test.mts

@@ -0,0 +1,132 @@
+import { hasKey, isRecord, Optional } from 'ts-data-forge';
+import { source } from '../create/index.mjs';
+import { keepEqualParts } from './keep-equal-parts.mjs';
+import { map } from './map.mjs';
+import { skipIfNoChange } from './skip-if-no-change.mjs';
+
+type Report = Readonly<{
+  readAt: number;
+  summary: Readonly<{ open: number }>;
+  entries: readonly Readonly<{ number: number; title: string }>[];
+}>;
+
+describe(keepEqualParts, () => {
+  test('passes on nothing when the next value is deeply equal to the last one', () => {
+    const report$ = source<Report>();
+
+    const kept$ = report$.pipe(keepEqualParts());
+
+    const seen = record(kept$);
+
+    report$.next(report(1, [entry(1, 'a')]));
+
+    report$.next(report(1, [entry(1, 'a')]));
+
+    assert.strictEqual(seen.length, 1);
+  });
+
+  test('passes on a new root whose unchanged branches are the ones passed on before', () => {
+    const report$ = source<Report>();
+
+    const kept$ = report$.pipe(keepEqualParts());
+
+    const seen = record(kept$);
+
+    report$.next(report(1, [entry(1, 'a'), entry(2, 'b')]));
+
+    report$.next(report(2, [entry(1, 'a'), entry(2, 'b (edited)')]));
+
+    assert.strictEqual(seen.length, 2);
+
+    const [first, second] = seen;
+
+    assert.notStrictEqual(second, first);
+
+    assert.strictEqual(second?.summary, first?.summary);
+
+    assert.strictEqual(second?.entries[0], first?.entries[0]);
+
+    assert.notStrictEqual(second?.entries[1], first?.entries[1]);
+
+    assert.strictEqual(second?.readAt, 2);
+  });
+
+  test('matches array items by `key`', () => {
+    const report$ = source<Report>();
+
+    const kept$ = report$.pipe(
+      keepEqualParts({
+        key: (item) =>
+          isRecord(item) && hasKey(item, 'number') ? item.number : undefined,
+      }),
+    );
+
+    const seen = record(kept$);
+
+    report$.next(report(1, [entry(1, 'a')]));
+
+    report$.next(report(1, [entry(0, 'new'), entry(1, 'a')]));
+
+    const [first, second] = seen;
+
+    assert.strictEqual(second?.entries[1], first?.entries[0]);
+  });
+
+  test('keeps the initial value of an initialized parent', () => {
+    const initial = report(1, []);
+
+    const report$ = source<Report>(initial);
+
+    const kept$ = report$.pipe(keepEqualParts());
+
+    assert.strictEqual(
+      Optional.unwrapOr(kept$.getSnapshot(), undefined),
+      initial,
+    );
+
+    const seen = record(kept$);
+
+    report$.next(report(1, []));
+
+    assert.deepStrictEqual(seen, [initial]);
+  });
+
+  test('lets `skipIfNoChange()` stop a part that did not change', () => {
+    const report$ = source<Report>(report(1, [entry(1, 'a')]));
+
+    const summaries = record(
+      report$
+        .pipe(keepEqualParts())
+        .pipe(map((held) => held.summary))
+        .pipe(skipIfNoChange()),
+    );
+
+    report$.next(report(2, [entry(1, 'a')]));
+
+    assert.strictEqual(summaries.length, 1);
+  });
+});
+
+const entry = (
+  number: number,
+  title: string,
+): Readonly<{ number: number; title: string }> => ({ number, title }) as const;
+
+const report = (readAt: number, entries: Report['entries']): Report =>
+  ({
+    readAt,
+    summary: { open: entries.length },
+    entries,
+  }) as const;
+
+const record = <A,>(
+  observable: Readonly<{ subscribe: (onNext: (value: A) => void) => unknown }>,
+): readonly A[] => {
+  const mut_seen: A[] = [];
+
+  observable.subscribe((value) => {
+    mut_seen.push(value);
+  });
+
+  return mut_seen;
+};

package/src/core/types/id.mts

@@ -1,3 +1,7 @@
-import type { Brand } from 'ts-type-forge';
+import type { Brand, UnknownRecord } from 'ts-type-forge';
 
-export type UpdateToken = Brand<symbol, 'update-token'>;
+/**
+ * Identifies one update. Opaque: an object issued per update, which is also
+ * that update's queue.
+ */
+export type UpdateToken = Brand<UnknownRecord, 'update-token'>;

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

@@ -244,6 +244,11 @@ export type WithBufferedFromOperatorObservable<A, B> = SyncChildObservable<
 
 export type FilterOperatorObservable<A> = SyncChildObservable<A, readonly [A]>;
 
+export type KeepEqualPartsOperatorObservable<A> = SyncChildObservable<
+  A,
+  readonly [A]
+>;
+
 export type SkipIfNoChangeOperatorObservable<A> = SyncChildObservable<
   A,
   readonly [A]

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

@@ -1,16 +1,5 @@
 import type { UpdateToken } from '../types/index.mjs';
 
-/**
- * The token of a new update, which the update's root or async child passes to
- * every node it reaches. A `Symbol` with no description, issued once per
- * update and never per node, so its cost is spread over every node the
- * update reaches. Unique without any counter, so the tokens of two copies of
- * synstate in one program never coincide, and nothing is kept in a global.
- */
-export const issueUpdateToken = (): UpdateToken =>
-  // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  Symbol() as UpdateToken;
-
 /**
  * The token a node holds before its first update: one value shared by every
  * node of this copy, since no update is ever issued it, so creating a node
@@ -18,4 +7,4 @@ export const issueUpdateToken = (): UpdateToken =>
  */
 export const notUpdatedYet: UpdateToken =
   // @sumi-expect-error banned-syntax/no-unsafe-type-assertion
-  Symbol('synstate/not-updated-yet') as UpdateToken;
+  Object.freeze({}) as UpdateToken;

package/src/utils/create-reducer.mts

@@ -1,3 +1,4 @@
+import { replaceEqualDeep, type ReplaceEqualDeepOptions } from 'ts-data-forge';
 import type { Reducer } from 'ts-type-forge';
 import { source, type InitializedObservable } from '../core/index.mjs';
 
@@ -10,7 +11,8 @@ import { source, type InitializedObservable } from '../core/index.mjs';
  * @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` (default `Object.is`),
- *   to pass on only the dispatches that change the state
+ *   to pass on only the dispatches that change the state, and
+ *   `keepEqualParts`, to keep the parts of the state a dispatch did not change
  * @returns A 3-element tuple: `[state, dispatch, { getSnapshot, initialState }]`.
  *   `dispatch` returns the state it leaves; once `state` is completed, that
  *   is the state held.
@@ -93,10 +95,20 @@ export const createReducer = <S, A>(
 
   const equals = options?.equals ?? Object.is;
 
+  const keepEqualParts = options?.keepEqualParts ?? false;
+
+  const keepOptions =
+    typeof keepEqualParts === 'boolean' ? undefined : keepEqualParts;
+
   const dispatch = (action: A): S => {
     const currentState = state.getSnapshot().value;
 
-    const nextState = reducer(currentState, action);
+    const reduced = reducer(currentState, action);
+
+    const nextState =
+      keepEqualParts === false
+        ? reduced
+        : replaceEqualDeep(currentState, reduced, keepOptions);
 
     // Once completed, `next` keeps the state held and returns it.
     return equals(currentState, nextState)
@@ -131,4 +143,32 @@ export type StateOptions<S> = Readonly<{
    * @param next - The state the update would set
    */
   equals?: (current: S, next: S) => boolean;
+
+  /**
+   * Whether an update keeps the parts of the state it did not change. With
+   * `true`, the next state is compared with the current one before it is
+   * written, and every part of it deeply equal to the same part of the
+   * current state is replaced by that part (`replaceEqualDeep` of
+   * ts-data-forge): a reader of an unchanged part keeps the object it has, so
+   * `skipIfNoChange()` with `Object.is` stops it. When the whole next state is
+   * deeply equal, the current state is kept and nothing is passed on, so
+   * `equals` can stay `Object.is`.
+   *
+   * This is for a state written whole from a source that answers with a new
+   * object every time, a server polled for a report, say. Array items are
+   * matched by index; pass `{ key }` to match them by key, an item for which
+   * `key` returns `undefined` being matched by index. Only plain objects and
+   * arrays are walked into; a `Map`, a `Set`, a `Date` or a class instance is
+   * compared and kept whole.
+   *
+   * Prefer this over `keepEqualParts()` downstream: keeping the parts where
+   * the state is written means no update with nothing in it is passed on at
+   * all, and nothing downstream has anything to undo.
+   *
+   * Defaults to `false`: the next state is written as given. With it on,
+   * each update compares deeply every part of the next state that is not
+   * the very object of the current one; a state whose updates already keep
+   * what they do not change, as `{ ...prev, x }` does, gains nothing from it.
+   */
+  keepEqualParts?: boolean | ReplaceEqualDeepOptions;
 }>;