synstate 4.1.0 → 5.0.0

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

package/src/utils/create-state.mts

@@ -29,7 +29,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` (default `Object.is`),
- *   to pass on only the updates that change the state
+ *   to pass on only the updates that change the state, and `keepEqualParts`,
+ *   to keep the parts of the state an update did not change
  * @returns A 3-element tuple: `[state, setState, { updateState, resetState, getSnapshot, initialState }]`
  *
  * @example
@@ -89,6 +90,57 @@ const reducer = <S,>(state: S, action: Action<S>): S => {
  * ]);
  * ```
  *
+ * @example
+ * ```ts
+ * type PullReport = DeepReadonly<{
+ *   summary: { open: number };
+ *   pulls: { number: number; title: string }[];
+ * }>;
+ *
+ * const [report, setReport] = createState<PullReport>(
+ *   { summary: { open: 0 }, pulls: [] },
+ *   { keepEqualParts: true },
+ * );
+ *
+ * const summary = report.pipe(map((r) => r.summary)).pipe(skipIfNoChange());
+ *
+ * const summaryHistory: unknown[] = [];
+ *
+ * summary.subscribe((value) => {
+ *   summaryHistory.push(value);
+ * });
+ *
+ * // A server answers each poll with the whole report, a new object every
+ * // time. What did not change keeps the object already held.
+ * setReport({
+ *   summary: { open: 1 },
+ *   pulls: [{ number: 1, title: 'one' }],
+ * });
+ *
+ * const held = report.getSnapshot().value;
+ *
+ * // An answer that changes nothing is not passed on at all.
+ * setReport({
+ *   summary: { open: 1 },
+ *   pulls: [{ number: 1, title: 'one' }],
+ * });
+ *
+ * assert.strictEqual(report.getSnapshot().value, held);
+ *
+ * // An edited title: a new report and a new array, while the summary is
+ * // the one held, so `summary` is not told of it.
+ * setReport({
+ *   summary: { open: 1 },
+ *   pulls: [{ number: 1, title: 'one (edited)' }],
+ * });
+ *
+ * assert.notStrictEqual(report.getSnapshot().value, held);
+ *
+ * assert.strictEqual(report.getSnapshot().value.summary, held.summary);
+ *
+ * assert.deepStrictEqual(summaryHistory, [{ open: 0 }, { open: 1 }]);
+ * ```
+ *
  * @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

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

@@ -1,3 +1,4 @@
+import { hasKey, isRecord } from 'ts-data-forge';
 import { createState } from './create-state.mjs';
 
 describe(createState, () => {
@@ -75,6 +76,93 @@ describe(createState, () => {
 
     assert.deepStrictEqual(seen, [held]);
   });
+
+  describe('keepEqualParts', () => {
+    type Report = Readonly<{
+      summary: Readonly<{ open: number }>;
+      entries: readonly Readonly<{ number: number; title: string }>[];
+    }>;
+
+    const initial: Report = {
+      summary: { open: 1 },
+      entries: [{ number: 1, title: 'a' }],
+    } as const;
+
+    test('passes nothing on, and keeps the current object, when the next state is deeply equal', () => {
+      const [state, setState, { getSnapshot }] = createState(initial, {
+        keepEqualParts: true,
+      });
+
+      const seen = record(state);
+
+      assert.strictEqual(
+        setState({
+          summary: { open: 1 },
+          entries: [{ number: 1, title: 'a' }],
+        }),
+        initial,
+      );
+
+      assert.strictEqual(getSnapshot(), initial);
+
+      assert.deepStrictEqual(seen, [initial]);
+    });
+
+    test('writes a new state whose unchanged branches are the current ones', () => {
+      const [state, setState] = createState(initial, { keepEqualParts: true });
+
+      const seen = record(state);
+
+      const written = setState({
+        summary: { open: 1 },
+        entries: [
+          { number: 1, title: 'a' },
+          { number: 2, title: 'b' },
+        ],
+      });
+
+      assert.deepStrictEqual(seen, [initial, written]);
+
+      assert.strictEqual(written.summary, initial.summary);
+
+      assert.strictEqual(written.entries[0], initial.entries[0]);
+    });
+
+    test('applies to `updateState` and matches items by `key`', () => {
+      const [state, , { updateState }] = createState(initial, {
+        keepEqualParts: {
+          key: (item) =>
+            isRecord(item) && hasKey(item, 'number') ? item.number : undefined,
+        },
+      });
+
+      // A whole new object, as a server answer would be.
+      const written = updateState(() => ({
+        summary: { open: 1 },
+        entries: [
+          { number: 0, title: 'new' },
+          { number: 1, title: 'a' },
+        ],
+      }));
+
+      assert.strictEqual(written.summary, initial.summary);
+
+      assert.strictEqual(written.entries[1], initial.entries[0]);
+
+      assert.strictEqual(state.getSnapshot().value, written);
+    });
+
+    test('is off by default', () => {
+      const [, setState] = createState(initial);
+
+      const next: Report = {
+        summary: { open: 1 },
+        entries: [{ number: 1, title: 'a' }],
+      } as const;
+
+      assert.strictEqual(setState(next), next);
+    });
+  });
 });
 
 const record = <A,>(