ts-data-forge 14.9.0 → 14.10.1

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 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;
+
+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;
+
+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;
+};
+
+// 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');

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

@@ -0,0 +1,348 @@
+// 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<string, Readonly<{ x: number }>>([['a', { x: 1 }]]);
+
+    assert.strictEqual(
+      replaceEqualDeep(
+        map,
+        new Map<string, Readonly<{ x: number }>>([['a', { x: 1 }]]),
+      ),
+      map,
+    );
+
+    const changedMap = new Map<string, Readonly<{ x: number }>>([
+      ['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<number>([1, 2]);
+
+    assert.strictEqual(replaceEqualDeep(set, new Set<number>([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<string, number>([['a', 1]]);
+
+    const current = { map, count: 1 } as const;
+
+    const shared = replaceEqualDeep(current, {
+      map: new Map<string, number>([['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 }[] }>;

package/src/string/str.mts

@@ -522,8 +522,8 @@ export namespace Str {
    * `NonEmptyString` is an alias of `MinLengthString<1>`, so this is the
    * length-1 specialization of {@link asMinLengthString}. Use this instead of
    * writing `s as unknown as NonEmptyString`: the length is verified at
-   * runtime, and the original string type (e.g. literal types) is preserved
-   * via intersection.
+   * runtime, and the original string type (e.g. literal types) is preserved via
+   * intersection.
    *
    * @example
    *