synstate 4.0.0 → 5.0.0

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,>(