ts-data-forge 14.9.0 → 14.10.0

package/dist/others/index.d.mts

@@ -6,6 +6,7 @@ export * from './if-then.mjs';
 export * from './map-nullable.mjs';
 export * from './memoize-function.mjs';
 export * from './panic-error.mjs';
+export * from './replace-equal-deep.mjs';
 export * from './tuple.mjs';
 export * from './unknown-to-string.mjs';
 //# sourceMappingURL=index.d.mts.map

package/dist/others/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/others/index.mts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/others/index.mts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}

package/dist/others/index.mjs

@@ -6,6 +6,7 @@ export * from './if-then.mjs';
 export * from './map-nullable.mjs';
 export * from './memoize-function.mjs';
 export * from './panic-error.mjs';
+export * from './replace-equal-deep.mjs';
 export * from './tuple.mjs';
 export * from './unknown-to-string.mjs';
 //# sourceMappingURL=index.mjs.map

package/dist/others/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/others/index.mts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/others/index.mts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC"}

package/dist/others/replace-equal-deep.d.mts

@@ -0,0 +1,95 @@
+/**
+ * Returns `next` with every part deeply equal to the same part of `current`
+ * replaced by that part of `current` (structural sharing). When the whole of
+ * `next` is deeply equal to `current`, `current` itself is returned, so an
+ * `Object.is` comparison of the result with `current` tells whether anything
+ * changed, and a reader that compares by reference sees a new object only
+ * where the value really changed.
+ *
+ * Only plain objects and arrays are walked into. Anything else — a `Map`, a
+ * `Set`, a `Date`, a class instance — is compared whole with
+ * {@link fastDeepEqual} and kept or replaced whole.
+ *
+ * Array items are matched by index. Give `key` to match them by key instead:
+ * an item for which it returns something other than `undefined` is matched
+ * with the item of `current` it returns the same key for, and an item it
+ * returns `undefined` for is still matched by index. The one `key` is used
+ * for the arrays at every depth.
+ *
+ * Neither argument is changed. The result shares objects with both, so it
+ * relies on neither being changed afterwards.
+ *
+ * Call it where the new value is written over the one held, so that nothing
+ * downstream has a new object it must compare again.
+ *
+ * @param current - The value held now
+ * @param next - The value to write over it
+ * @param options - {@link ReplaceEqualDeepOptions}
+ * @returns `current` when `next` is deeply equal to it; otherwise a value
+ *   deeply equal to `next` that reuses the equal parts of `current`
+ *
+ * @example
+ * ```ts
+ * type PullReport = DeepReadonly<{
+ *   summary: { open: number };
+ *   pulls: { number: number; title: string }[];
+ * }>;
+ *
+ * const held: PullReport = {
+ *   summary: { open: 2 },
+ *   pulls: [
+ *     { number: 1, title: 'one' },
+ *     { number: 2, title: 'two' },
+ *   ],
+ * } as const;
+ *
+ * // A server answers with the whole report every time.
+ * const answer: PullReport = {
+ *   summary: { open: 2 },
+ *   pulls: [
+ *     { number: 1, title: 'one' },
+ *     { number: 2, title: 'two (edited)' },
+ *   ],
+ * } as const;
+ *
+ * const written = replaceEqualDeep(held, answer);
+ *
+ * assert.deepStrictEqual(written, answer);
+ *
+ * // What did not change is the object already held,
+ * assert.strictEqual(written.summary, held.summary);
+ *
+ * assert.strictEqual(written.pulls[0], held.pulls[0]);
+ *
+ * // and what changed is new.
+ * assert.notStrictEqual(written.pulls[1], held.pulls[1]);
+ *
+ * // An answer that changes nothing gives back the value held.
+ * assert.strictEqual(replaceEqualDeep(held, structuredClone(held)), held);
+ *
+ * // Match array items by key rather than by index.
+ * const opened = replaceEqualDeep(
+ *   held.pulls,
+ *   [{ number: 0, title: 'zero' }, ...structuredClone(held.pulls)],
+ *   {
+ *     key: (item) =>
+ *       isRecord(item) && hasKey(item, 'number') ? item.number : undefined,
+ *   },
+ * );
+ *
+ * assert.strictEqual(opened[1], held.pulls[0]);
+ *
+ * assert.strictEqual(opened[2], held.pulls[1]);
+ * ```
+ */
+export declare const replaceEqualDeep: <T>(current: T, next: T, options?: ReplaceEqualDeepOptions) => T;
+/** Options of {@link replaceEqualDeep}. */
+export type ReplaceEqualDeepOptions = Readonly<{
+    /**
+     * The key an array item is matched by. Items it returns `undefined` for
+     * are matched by index. Keys are compared with `SameValueZero`, as `Map`
+     * compares them.
+     */
+    key?: (item: unknown) => unknown;
+}>;
+//# sourceMappingURL=replace-equal-deep.d.mts.map

package/dist/others/replace-equal-deep.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-equal-deep.d.mts","sourceRoot":"","sources":["../../src/others/replace-equal-deep.mts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,WACvB,CAAC,QACJ,CAAC,YACG,uBAAuB,KAChC,CAIwC,CAAC;AAE5C,2CAA2C;AAC3C,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C;;;;OAIG;IACH,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CAClC,CAAC,CAAC"}

package/dist/others/replace-equal-deep.mjs

@@ -0,0 +1,156 @@
+import { hasKey, isRecord } from '../guard/index.mjs';
+import { fastDeepEqual } from './fast-deep-equal.mjs';
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+export const replaceEqualDeep = (current, next, options) => 
+
+
+
+replace(current, next, options?.key);
+const replace = (current, next, key) => Object.is(current, next)
+    ? current
+    : isPlainArray(current) && isPlainArray(next)
+        ? replaceArray(current, next, key)
+        : isPlainObject(current) && isPlainObject(next)
+            ? replaceObject(current, next, key)
+            : fastDeepEqual(current, next)
+                ? current
+                : next;
+
+
+
+const replaceArray = (current, next, key) => {
+    const byKey = key === undefined ? undefined : indexByKey(current, key);
+    let mut_isCurrent = current.length === next.length;
+    let mut_isNext = true;
+    const mut_shared = [];
+    for (let mut_index = 0; mut_index < next.length; mut_index += 1) {
+        const index = mut_index;
+        const item = next[index];
+        const itemKey = key?.(item);
+        const before = itemKey === undefined || byKey === undefined
+            ? index < current.length
+                ? current[index]
+                : absent
+            : byKey.has(itemKey)
+                ? byKey.get(itemKey)
+                : absent;
+        const result = before === absent ? item : replace(before, item, key);
+        mut_isCurrent &&= Object.is(result, current[index]);
+        mut_isNext &&= Object.is(result, item);
+        mut_shared.push(result);
+    }
+    return mut_isCurrent ? current : mut_isNext ? next : mut_shared;
+};
+const replaceObject = (current, next, key) => {
+    const nextKeys = Object.keys(next);
+    let mut_isCurrent = Object.keys(current).length === nextKeys.length;
+    let mut_isNext = true;
+    const mut_shared = {};
+    for (const k of nextKeys) {
+        const value = next[k];
+        const has = hasKey(current, k);
+        const result = has ? replace(current[k], value, key) : value;
+        mut_isCurrent &&= has && Object.is(result, current[k]);
+        mut_isNext &&= Object.is(result, value);
+        mut_shared[k] = result;
+    }
+    return mut_isCurrent ? current : mut_isNext ? next : mut_shared;
+};
+
+const absent = Symbol('absent');
+const indexByKey = (items, key) => {
+    const mut_byKey = new Map();
+    for (const item of items) {
+        const itemKey = key(item);
+        if (itemKey !== undefined && !mut_byKey.has(itemKey)) {
+            mut_byKey.set(itemKey, item);
+        }
+    }
+    return mut_byKey;
+};
+const isPlainArray = (value) => Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+const isPlainObject = (value) => isRecord(value) && Object.getPrototypeOf(value) === Object.prototype;
+//# sourceMappingURL=replace-equal-deep.mjs.map

package/dist/others/replace-equal-deep.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-equal-deep.mjs","sourceRoot":"","sources":["../../src/others/replace-equal-deep.mts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "14.9.0",
+  "version": "14.10.0",
   "private": false,
   "keywords": [
     "typescript",
@@ -46,9 +46,9 @@
     "@mui/material": "9.4.0",
     "@types/react": "19.3.0",
     "@vitest/browser-playwright": "5.0.3",
-    "eslint-config-typed": "5.19.0",
-    "eslint-plugin-ts-fortress": "1.3.5",
-    "eslint-plugin-ts-type-forge": "0.8.10",
+    "eslint-config-typed": "5.19.1",
+    "eslint-plugin-ts-fortress": "1.3.7",
+    "eslint-plugin-ts-type-forge": "0.8.12",
     "immer": "11.1.21",
     "playwright": "1.64.0",
     "prettier": "3.9.9",

package/src/others/index.mts

@@ -6,5 +6,6 @@ export * from './if-then.mjs';
 export * from './map-nullable.mjs';
 export * from './memoize-function.mjs';
 export * from './panic-error.mjs';
+export * from './replace-equal-deep.mjs';
 export * from './tuple.mjs';
 export * from './unknown-to-string.mjs';

package/src/others/replace-equal-deep.mts

@@ -0,0 +1,225 @@
+import type { MutableRecord, UnknownRecord } from 'ts-type-forge';
+import { hasKey, isRecord } from '../guard/index.mjs';
+import { fastDeepEqual } from './fast-deep-equal.mjs';
+
+/**
+ * Returns `next` with every part deeply equal to the same part of `current`
+ * replaced by that part of `current` (structural sharing). When the whole of
+ * `next` is deeply equal to `current`, `current` itself is returned, so an
+ * `Object.is` comparison of the result with `current` tells whether anything
+ * changed, and a reader that compares by reference sees a new object only
+ * where the value really changed.
+ *
+ * Only plain objects and arrays are walked into. Anything else — a `Map`, a
+ * `Set`, a `Date`, a class instance — is compared whole with
+ * {@link fastDeepEqual} and kept or replaced whole.
+ *
+ * Array items are matched by index. Give `key` to match them by key instead:
+ * an item for which it returns something other than `undefined` is matched
+ * with the item of `current` it returns the same key for, and an item it
+ * returns `undefined` for is still matched by index. The one `key` is used
+ * for the arrays at every depth.
+ *
+ * Neither argument is changed. The result shares objects with both, so it
+ * relies on neither being changed afterwards.
+ *
+ * Call it where the new value is written over the one held, so that nothing
+ * downstream has a new object it must compare again.
+ *
+ * @param current - The value held now
+ * @param next - The value to write over it
+ * @param options - {@link ReplaceEqualDeepOptions}
+ * @returns `current` when `next` is deeply equal to it; otherwise a value
+ *   deeply equal to `next` that reuses the equal parts of `current`
+ *
+ * @example
+ * ```ts
+ * type PullReport = DeepReadonly<{
+ *   summary: { open: number };
+ *   pulls: { number: number; title: string }[];
+ * }>;
+ *
+ * const held: PullReport = {
+ *   summary: { open: 2 },
+ *   pulls: [
+ *     { number: 1, title: 'one' },
+ *     { number: 2, title: 'two' },
+ *   ],
+ * } as const;
+ *
+ * // A server answers with the whole report every time.
+ * const answer: PullReport = {
+ *   summary: { open: 2 },
+ *   pulls: [
+ *     { number: 1, title: 'one' },
+ *     { number: 2, title: 'two (edited)' },
+ *   ],
+ * } as const;
+ *
+ * const written = replaceEqualDeep(held, answer);
+ *
+ * assert.deepStrictEqual(written, answer);
+ *
+ * // What did not change is the object already held,
+ * assert.strictEqual(written.summary, held.summary);
+ *
+ * assert.strictEqual(written.pulls[0], held.pulls[0]);
+ *
+ * // and what changed is new.
+ * assert.notStrictEqual(written.pulls[1], held.pulls[1]);
+ *
+ * // An answer that changes nothing gives back the value held.
+ * assert.strictEqual(replaceEqualDeep(held, structuredClone(held)), held);
+ *
+ * // Match array items by key rather than by index.
+ * const opened = replaceEqualDeep(
+ *   held.pulls,
+ *   [{ number: 0, title: 'zero' }, ...structuredClone(held.pulls)],
+ *   {
+ *     key: (item) =>
+ *       isRecord(item) && hasKey(item, 'number') ? item.number : undefined,
+ *   },
+ * );
+ *
+ * assert.strictEqual(opened[1], held.pulls[0]);
+ *
+ * assert.strictEqual(opened[2], held.pulls[1]);
+ * ```
+ */
+export const replaceEqualDeep = <T,>(
+  current: T,
+  next: T,
+  options?: ReplaceEqualDeepOptions,
+): T =>
+  // The walk sees `unknown`; what it returns is `current`, `next`, or a copy
+  // of `next`'s shape whose parts are parts of either, so it is a `T`.
+  // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+  replace(current, next, options?.key) as T;
+
+/** Options of {@link replaceEqualDeep}. */
+export type ReplaceEqualDeepOptions = Readonly<{
+  /**
+   * The key an array item is matched by. Items it returns `undefined` for
+   * are matched by index. Keys are compared with `SameValueZero`, as `Map`
+   * compares them.
+   */
+  key?: (item: unknown) => unknown;
+}>;
+
+type Key = (item: unknown) => unknown;
+
+const replace = (
+  current: unknown,
+  next: unknown,
+  key: Key | undefined,
+): unknown =>
+  Object.is(current, next)
+    ? current
+    : isPlainArray(current) && isPlainArray(next)
+      ? replaceArray(current, next, key)
+      : isPlainObject(current) && isPlainObject(next)
+        ? replaceObject(current, next, key)
+        : fastDeepEqual(current, next)
+          ? current
+          : next;
+
+// Each walk returns `current` when every part of the result is the same part
+// of `current`, `next` when every part is the same part of `next` (nothing
+// was reused, so no copy is needed), and the copy otherwise.
+
+const replaceArray = (
+  current: readonly unknown[],
+  next: readonly unknown[],
+  key: Key | undefined,
+): readonly unknown[] => {
+  const byKey = key === undefined ? undefined : indexByKey(current, key);
+
+  let mut_isCurrent = current.length === next.length;
+
+  let mut_isNext = true;
+
+  const mut_shared: unknown[] = [];
+
+  for (let mut_index = 0; mut_index < next.length; mut_index += 1) {
+    const index = mut_index;
+
+    const item = next[index];
+
+    const itemKey = key?.(item);
+
+    const before =
+      itemKey === undefined || byKey === undefined
+        ? index < current.length
+          ? current[index]
+          : absent
+        : byKey.has(itemKey)
+          ? byKey.get(itemKey)
+          : absent;
+
+    const result = before === absent ? item : replace(before, item, key);
+
+    mut_isCurrent &&= Object.is(result, current[index]);
+
+    mut_isNext &&= Object.is(result, item);
+
+    mut_shared.push(result);
+  }
+
+  return mut_isCurrent ? current : mut_isNext ? next : mut_shared;
+};
+
+const replaceObject = (
+  current: UnknownRecord,
+  next: UnknownRecord,
+  key: Key | undefined,
+): UnknownRecord => {
+  const nextKeys = Object.keys(next);
+
+  let mut_isCurrent = Object.keys(current).length === nextKeys.length;
+
+  let mut_isNext = true;
+
+  const mut_shared: MutableRecord<string, unknown> = {};
+
+  for (const k of nextKeys) {
+    const value = next[k];
+
+    const has = hasKey(current, k);
+
+    const result = has ? replace(current[k], value, key) : value;
+
+    mut_isCurrent &&= has && Object.is(result, current[k]);
+
+    mut_isNext &&= Object.is(result, value);
+
+    mut_shared[k] = result;
+  }
+
+  return mut_isCurrent ? current : mut_isNext ? next : mut_shared;
+};
+
+// What an item of `next` is matched with when nothing of `current` is.
+const absent: unique symbol = Symbol('absent');
+
+const indexByKey = (
+  items: readonly unknown[],
+  key: Key,
+): ReadonlyMap<unknown, unknown> => {
+  const mut_byKey = new Map<unknown, unknown>();
+
+  for (const item of items) {
+    const itemKey = key(item);
+
+    if (itemKey !== undefined && !mut_byKey.has(itemKey)) {
+      mut_byKey.set(itemKey, item);
+    }
+  }
+
+  return mut_byKey;
+};
+
+const isPlainArray = (value: unknown): value is readonly unknown[] =>
+  Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype;
+
+const isPlainObject = (value: unknown): value is UnknownRecord =>
+  isRecord(value) && Object.getPrototypeOf(value) === Object.prototype;

package/src/others/replace-equal-deep.test.mts

@@ -0,0 +1,342 @@
+// A `Date` is one of the values compared whole, so the cases build some.
+/* eslint-disable unicorn/prefer-temporal */
+import type { DeepReadonly, ReadonlyRecord } from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
+import { hasKey, isRecord } from '../guard/index.mjs';
+import { replaceEqualDeep } from './replace-equal-deep.mjs';
+
+describe(replaceEqualDeep, () => {
+  test('returns the current value when the next one is deeply equal', () => {
+    const current = {
+      id: 1,
+      tags: ['a', 'b'],
+      owner: { name: 'x', roles: [{ role: 'admin' }] },
+    } as const;
+
+    const next = {
+      id: 1,
+      tags: ['a', 'b'],
+      owner: { name: 'x', roles: [{ role: 'admin' }] },
+    } as const;
+
+    assert.strictEqual(replaceEqualDeep(current, next), current);
+  });
+
+  test('keeps the branches that did not change and replaces the rest', () => {
+    const current: Snapshot = {
+      summary: { open: 3, merged: 1 },
+      queue: [{ number: 1 }, { number: 2 }],
+      readAt: 100,
+    } as const;
+
+    const next: Snapshot = {
+      summary: { open: 3, merged: 1 },
+      queue: [{ number: 1 }, { number: 3 }],
+      readAt: 200,
+    } as const;
+
+    const shared = replaceEqualDeep(current, next);
+
+    assert.deepStrictEqual(shared, next);
+
+    assert.notStrictEqual(shared, current);
+
+    assert.strictEqual(shared.summary, current.summary);
+
+    assert.notStrictEqual(shared.queue, current.queue);
+
+    assert.strictEqual(shared.queue[0], current.queue[0]);
+
+    assert.strictEqual(shared.queue[1], next.queue[1]);
+
+    assert.strictEqual(shared.readAt, 200);
+  });
+
+  test('returns the next primitive when it differs', () => {
+    assert.strictEqual(replaceEqualDeep(1, 2), 2);
+
+    assert.strictEqual(replaceEqualDeep('a', 'a'), 'a');
+
+    assert.isTrue(Number.isNaN(replaceEqualDeep(Number.NaN, Number.NaN)));
+  });
+
+  test('replaces a value whose kind changed whole', () => {
+    const next: unknown = { 0: 'a' } as const;
+
+    assert.strictEqual(replaceEqualDeep<unknown>(['a'], next), next);
+
+    const nextArray: unknown = ['a'] as const;
+
+    assert.strictEqual(
+      replaceEqualDeep<unknown>({ 0: 'a' }, nextArray),
+      nextArray,
+    );
+
+    const nextNull: unknown = null;
+
+    assert.strictEqual(replaceEqualDeep<unknown>({}, nextNull), null);
+  });
+
+  test('builds a new object when a property is added or removed', () => {
+    const inner = { x: 1 } as const;
+
+    const added = replaceEqualDeep<ReadonlyRecord<string, unknown>>(
+      { inner },
+      { inner: { x: 1 }, extra: true },
+    );
+
+    assert.deepStrictEqual(added, { inner: { x: 1 }, extra: true });
+
+    assert.strictEqual(added['inner'], inner);
+
+    const current: ReadonlyRecord<string, unknown> = {
+      inner,
+      gone: 1,
+    } as const;
+
+    const removed = replaceEqualDeep(current, { inner: { x: 1 } });
+
+    assert.deepStrictEqual(removed, { inner: { x: 1 } });
+
+    assert.notStrictEqual(removed, current);
+
+    assert.isFalse(Object.hasOwn(removed, 'gone'));
+
+    assert.strictEqual(removed['inner'], inner);
+  });
+
+  test('builds a new object when a property set to undefined goes missing', () => {
+    const current: Readonly<{ a?: number | undefined }> = {
+      a: undefined,
+    } as const;
+
+    const shared = replaceEqualDeep(current, {});
+
+    assert.notStrictEqual(shared, current);
+
+    assert.isFalse(Object.hasOwn(shared, 'a'));
+  });
+
+  test('matches array items by index by default', () => {
+    const one: Numbered = { number: 1 } as const;
+
+    const two: Numbered = { number: 2 } as const;
+
+    const current: readonly Numbered[] = [one, two] as const;
+
+    const shorter = replaceEqualDeep(current, [{ number: 1 }]);
+
+    assert.deepStrictEqual(shorter, [{ number: 1 }]);
+
+    assert.strictEqual(shorter[0], one);
+
+    const longer = replaceEqualDeep(current, [
+      { number: 1 },
+      { number: 2 },
+      { number: 3 },
+    ]);
+
+    assert.strictEqual(longer[0], one);
+
+    assert.strictEqual(longer[1], two);
+
+    // An item put in front moves every one after it, so nothing matches.
+    const shifted = replaceEqualDeep(current, [
+      { number: 0 },
+      { number: 1 },
+      { number: 2 },
+    ]);
+
+    assert.notStrictEqual(shifted[1], one);
+
+    assert.notStrictEqual(shifted[2], two);
+  });
+
+  test('matches array items by key when `key` returns one', () => {
+    const one: Pull = { number: 1, title: 'one' } as const;
+
+    const two: Pull = { number: 2, title: 'two' } as const;
+
+    const current: readonly Pull[] = [one, two] as const;
+
+    const key = (item: unknown): unknown =>
+      isRecord(item) && hasKey(item, 'number') ? item.number : undefined;
+
+    const shared = replaceEqualDeep(
+      current,
+      [
+        { number: 0, title: 'zero' },
+        { number: 1, title: 'one' },
+        { number: 2, title: 'two (edited)' },
+      ],
+      { key },
+    );
+
+    assert.strictEqual(shared[1], one);
+
+    assert.notStrictEqual(shared[2], two);
+
+    assert.deepStrictEqual(shared[2], { number: 2, title: 'two (edited)' });
+
+    const reordered = replaceEqualDeep(
+      current,
+      [
+        { number: 2, title: 'two' },
+        { number: 1, title: 'one' },
+      ],
+      { key },
+    );
+
+    assert.notStrictEqual(reordered, current);
+
+    assert.strictEqual(reordered[0], two);
+
+    assert.strictEqual(reordered[1], one);
+
+    const same = replaceEqualDeep(
+      current,
+      [
+        { number: 1, title: 'one' },
+        { number: 2, title: 'two' },
+      ],
+      { key },
+    );
+
+    assert.strictEqual(same, current);
+  });
+
+  test('matches by index the items `key` gives no key, at every depth', () => {
+    const key = (item: unknown): unknown =>
+      isRecord(item) && hasKey(item, 'id') ? item.id : undefined;
+
+    const labels: readonly string[] = ['bug', 'ui'] as const;
+
+    const current: readonly Labeled[] = [{ id: 'a', labels }] as const;
+
+    const shared = replaceEqualDeep(
+      current,
+      [
+        { id: 'b', labels: ['x'] },
+        { id: 'a', labels: ['bug', 'ui'] },
+      ],
+      { key },
+    );
+
+    assert.strictEqual(shared[1], current[0]);
+
+    assert.strictEqual(shared[1]?.labels, labels);
+  });
+
+  test('compares a Map, a Set, a Date or a class instance whole', () => {
+    const map = new Map([['a', { x: 1 }]]);
+
+    assert.strictEqual(replaceEqualDeep(map, new Map([['a', { x: 1 }]])), map);
+
+    const changedMap = new Map([
+      ['a', { x: 1 }],
+      ['b', { x: 2 }],
+    ]);
+
+    const sharedMap = replaceEqualDeep(map, changedMap);
+
+    assert.strictEqual(sharedMap, changedMap);
+
+    // Nothing inside is reused.
+    assert.notStrictEqual(sharedMap.get('a'), map.get('a'));
+
+    const set = new Set([1, 2]);
+
+    assert.strictEqual(replaceEqualDeep(set, new Set([1, 2])), set);
+
+    const date = new Date(0);
+
+    assert.strictEqual(replaceEqualDeep(date, new Date(0)), date);
+
+    const laterDate = new Date(1);
+
+    assert.strictEqual(replaceEqualDeep(date, laterDate), laterDate);
+
+    class Point {
+      readonly x: number;
+
+      readonly inner: Readonly<{ y: number }>;
+
+      constructor(x: number, y: number) {
+        this.x = x;
+
+        this.inner = { y };
+      }
+    }
+
+    const point = new Point(1, 2);
+
+    assert.strictEqual(replaceEqualDeep(point, new Point(1, 2)), point);
+
+    const moved = new Point(3, 2);
+
+    const sharedPoint = replaceEqualDeep(point, moved);
+
+    assert.strictEqual(sharedPoint, moved);
+
+    assert.notStrictEqual(sharedPoint.inner, point.inner);
+  });
+
+  test('reuses a Map compared whole inside a plain object', () => {
+    const map = new Map([['a', 1]]);
+
+    const current = { map, count: 1 } as const;
+
+    const shared = replaceEqualDeep(current, {
+      map: new Map([['a', 1]]),
+      count: 2,
+    });
+
+    assert.strictEqual(shared.map, map);
+
+    assert.strictEqual(shared.count, 2);
+  });
+
+  test('changes neither argument', () => {
+    const current: Listed = { list: [{ a: 1 }, { a: 2 }] } as const;
+
+    const next: Listed = { list: [{ a: 1 }, { a: 3 }] } as const;
+
+    const currentCopy = structuredClone(current);
+
+    const nextCopy = structuredClone(next);
+
+    replaceEqualDeep(current, next);
+
+    assert.deepStrictEqual(current, currentCopy);
+
+    assert.deepStrictEqual(next, nextCopy);
+  });
+
+  test('keeps the type of its arguments', () => {
+    type PullReport = Readonly<{
+      entries: readonly Readonly<{ number: number }>[];
+    }>;
+
+    const report: PullReport = { entries: [] } as const;
+
+    const shared = replaceEqualDeep(report, { entries: [{ number: 1 }] });
+
+    expectType<typeof shared, PullReport>('=');
+
+    assert.deepStrictEqual(shared, { entries: [{ number: 1 }] });
+  });
+});
+
+type Snapshot = DeepReadonly<{
+  summary: { open: number; merged: number };
+  queue: { number: number }[];
+  readAt: number;
+}>;
+
+type Numbered = Readonly<{ number: number }>;
+
+type Pull = Readonly<{ number: number; title: string }>;
+
+type Labeled = Readonly<{ id: string; labels: readonly string[] }>;
+
+type Listed = DeepReadonly<{ list: { a: number }[] }>;