@rohal12/spindle 0.59.4 → 0.59.6

package/src/structural.ts

@@ -42,6 +42,12 @@ export interface DeepCloneOptions {
    * is the copy already made. The map is filled as values are copied.
    */
   seen?: Map<object, object>;
+  /**
+   * Called with each Map key and Set member in the copy and the object it
+   * was copied from; the object it returns is the one the copy takes (for a
+   * store draft, which Immer does not finalize there).
+   */
+  settle?: (copy: object, original: object) => object;
 }
 
 type TypedArrayCtor = new (
@@ -103,8 +109,9 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
       const copy = keep(val, Object.create(Object.getPrototypeOf(val)));
       for (const key of [...ERROR_HIDDEN_KEYS, 'stack']) {
         if (hasOwn(val, key)) {
+          const held = (val as unknown as Record<string, unknown>)[key];
           Object.defineProperty(copy, key, {
-            value: clone((val as unknown as Record<string, unknown>)[key]),
+            value: settled(clone(held), held),
             writable: true,
             configurable: true,
           });
@@ -115,6 +122,13 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
     return undefined;
   }
 
+  function settled(copy: unknown, original: unknown): unknown {
+    const settle = options.settle;
+    return settle && isObjectValue(copy) && isObjectValue(original)
+      ? settle(copy, original)
+      : copy;
+  }
+
   function clone(val: unknown): unknown {
     if (val === null || typeof val !== 'object') return val;
 
@@ -132,17 +146,13 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
 
     if (val instanceof Map) {
       const copy = keep(obj, new Map());
-      for (const [k, v] of val) {
-        copy.set(clone(k), clone(v));
-      }
+      for (const [k, v] of val) copy.set(settled(clone(k), k), clone(v));
       return copy;
     }
 
     if (val instanceof Set) {
       const copy = keep(obj, new Set());
-      for (const v of val) {
-        copy.add(clone(v));
-      }
+      for (const v of val) copy.add(settled(clone(v), v));
       return copy;
     }
 
@@ -463,8 +473,15 @@ export function mergesWith(
 
 /** How a value differs from an earlier version at one key. */
 export type KeyChange =
-  | { key: string; kind: 'added' | 'changed'; after: unknown }
-  | { key: string; kind: 'deleted' }
+  | {
+      key: string;
+      kind: 'added' | 'changed';
+      after: unknown;
+      /** Holes between this element an array gained and the one before. */
+      gap?: number;
+    }
+  | { key: string; kind: 'deleted'; hole?: true }
+  | { key: string; kind: 'holes'; after: number }
   | {
       key: string;
       kind: 'nested';
@@ -480,7 +497,9 @@ export type KeyChange =
  * is none either. Values that merge are reported as 'nested', to be
  * compared key by key; they may still be equal. With `arrays`, arrays
  * merge too: elements at the indices both hold are compared, and the
- * elements one has beyond the other's length are added or deleted.
+ * elements one has beyond the other's length are added or deleted. An
+ * index that holds no element (a hole) is no element, not an undefined one,
+ * and holes the length gained at the end are the change of `length`, by how many.
  */
 export function keyChanges(
   before: Record<string, unknown>,
@@ -506,14 +525,31 @@ export function keyChanges(
     const b = before as unknown as unknown[];
     const a = after as unknown[];
     for (let i = 0; i < Math.min(b.length, a.length); i++) {
-      compare(String(i), b[i], a[i]);
+      // A hole is no element: not the same as an undefined one
+      const key = String(i);
+      if (i in b && i in a) compare(key, b[i], a[i]);
+      else if (i in b) changes.push({ key, kind: 'deleted', hole: true });
+      else if (i in a) changes.push({ key, kind: 'added', after: a[i] });
     }
+    let next = b.length;
     for (let i = b.length; i < a.length; i++) {
-      changes.push({ key: String(i), kind: 'added', after: a[i] });
+      if (!(i in a)) continue;
+      const gap = i - next;
+      changes.push({
+        key: String(i),
+        kind: 'added',
+        after: a[i],
+        ...(gap ? { gap } : {}),
+      });
+      next = i + 1;
     }
     for (let i = a.length; i < b.length; i++) {
       changes.push({ key: String(i), kind: 'deleted' });
     }
+    // Holes at the end are in no index, only in the length
+    if (a.length > next) {
+      changes.push({ key: 'length', kind: 'holes', after: a.length - next });
+    }
     return changes;
   }
 
@@ -533,6 +569,10 @@ export type PathChange =
       path: string[];
       deleted: false;
       value: unknown;
+      /** Set for an element an array gained beyond the length it had. */
+      appended?: true;
+      /** Holes an appended element follows (the array is sparse). */
+      gap?: number;
       /**
        * Set where the value is the same content as before and only which
        * object the path refers to changed (see aliasChanges), so a store
@@ -540,39 +580,79 @@ export type PathChange =
        */
       alias?: true;
     }
-  | { path: string[]; deleted: true };
+  | {
+      path: string[];
+      deleted: true;
+      /** Set for an element an array lost without shrinking: a hole. */
+      hole?: true;
+    };
 
 /**
  * The property paths where `after` differs from `before`, two objects of
  * one class: objects that merge (see isMergeable) are compared property by
- * property, any other value as a whole.
+ * property, any other value as a whole; with `arrays`, arrays are compared
+ * by index too (see keyChanges).
  */
 export function diffPaths(
   before: Record<string, unknown>,
   after: Record<string, unknown>,
+  arrays = false,
 ): PathChange[] {
   const changes: PathChange[] = [];
   const ancestors = new Set<object>();
+  // Pairs found equal, so a graph that shares objects is not walked once per
+  // path to them (exponentially many), and how often a walk met a cycle
+  const unchanged = new WeakMap<object, Set<object>>();
+  let cuts = 0;
   (function walk(
     b: Record<string, unknown>,
     a: Record<string, unknown>,
     path: string[],
   ): void {
-    // Stop at cycles; shared (non-cyclic) references are visited per path.
-    if (ancestors.has(a)) return;
+    // Stop at cycles; shared (non-cyclic) references that differ are visited
+    // per path, as each is a change there.
+    if (ancestors.has(a)) {
+      cuts++;
+      return;
+    }
+    if (unchanged.get(a)?.has(b)) return;
     ancestors.add(a);
-    for (const change of keyChanges(b, a, false)) {
+    const found = changes.length;
+    const cutsBefore = cuts;
+    for (const change of keyChanges(b, a, arrays)) {
       const at = [...path, change.key];
       if (change.kind === 'nested') {
         walk(change.before, change.after, at);
       } else {
         changes.push(
           change.kind === 'deleted'
-            ? { path: at, deleted: true }
-            : { path: at, deleted: false, value: change.after },
+            ? {
+                path: at,
+                deleted: true,
+                ...(change.hole ? { hole: true } : {}),
+              }
+            : {
+                path: at,
+                deleted: false,
+                value: change.after,
+                ...(change.kind === 'added' &&
+                Array.isArray(a) &&
+                Number(change.key) >= (b as unknown as unknown[]).length
+                  ? {
+                      appended: true as const,
+                      ...(change.gap ? { gap: change.gap } : {}),
+                    }
+                  : {}),
+              },
         );
       }
     }
+    // A walk that met a cycle depends on the ancestors it was reached by
+    if (changes.length === found && cuts === cutsBefore) {
+      const seen = unchanged.get(a) ?? new Set<object>();
+      seen.add(b);
+      unchanged.set(a, seen);
+    }
     ancestors.delete(a);
   })(before, after, []);
   return changes;
@@ -592,35 +672,132 @@ export function underChange(
   return false;
 }
 
+/**
+ * The segment standing for the entry `index` of a Map or Set in a path, or
+ * for the `cause` or `errors` of an Error ('c', 'e').
+ */
+const entryKey = (kind: 'k' | 'v' | 's' | 'c' | 'e', index: number): string =>
+  `\0${kind}${index}`;
+
+export const isEntryKey = (segment: string): boolean =>
+  segment.startsWith('\0');
+
+/**
+ * What a Map, Set or Error holds in place of properties (keys and values,
+ * members, `cause` and `errors`), each with the segment standing for it in
+ * a path (see entryKey); undefined for any other value.
+ */
+function entryChildren(value: object): [string, unknown][] | undefined {
+  const children: [string, unknown][] = [];
+  if (value instanceof Map) {
+    let index = 0;
+    for (const [k, v] of value) {
+      children.push([entryKey('k', index), k], [entryKey('v', index), v]);
+      index++;
+    }
+  } else if (value instanceof Set) {
+    let index = 0;
+    for (const member of value) children.push([entryKey('s', index++), member]);
+  } else if (value instanceof Error) {
+    for (const key of ['cause', 'errors'] as const) {
+      if (hasOwn(value, key)) {
+        children.push([
+          entryKey(key === 'cause' ? 'c' : 'e', 0),
+          (value as any)[key],
+        ]);
+      }
+    }
+  } else {
+    return undefined;
+  }
+  return children;
+}
+
+/**
+ * The value at `path` below `root`, where a path may go through the entries
+ * of Maps, Sets and Errors (see objectPaths) as well as properties.
+ */
+export function getByEntryPath(root: object, path: readonly string[]): unknown {
+  let current: unknown = root;
+  let start = 0;
+  for (let i = 0; i < path.length; i++) {
+    if (!isEntryKey(path[i]!)) continue;
+    current = getByPath(current as object, path.slice(start, i));
+    if (!isObjectValue(current)) return undefined;
+    current = entryChildren(current)?.find(([at]) => at === path[i])?.[1];
+    start = i + 1;
+  }
+  return start === path.length
+    ? current
+    : getByPath(current as object, path.slice(start));
+}
+
+/**
+ * Write `value` at the path of an object a Map holds as a value (see
+ * objectPaths); other entries are not replaced, as a key or member cannot
+ * change without the entry moving. Returns whether it wrote.
+ */
+function setEntryValue(
+  root: object,
+  path: readonly string[],
+  value: unknown,
+): boolean {
+  const holder = getByEntryPath(root, path.slice(0, -1));
+  const match = /^\0v(\d+)$/.exec(path[path.length - 1]!);
+  if (!(holder instanceof Map) || !match) return false;
+  const key = [...holder.keys()][Number(match[1])];
+  holder.set(key, value);
+  return true;
+}
+
 /**
  * Every path each object (or array, or other value) of `root` is at, the
  * first appearance first, in depth-first order. Plain objects and arrays are
  * entered, where first met only (an object held in an array is one object,
  * however it was reached); other values are leaves. A path at or below one
  * of `skip` is left out.
+ *
+ * With `entries`, the objects held in a Map or Set (as key, value or member)
+ * are placed too, after everything else: one met nowhere else is at the path
+ * of its Map or Set and the entry's segment (see entryKey), which is no path
+ * a value can be read at (see getByEntryPath), so only to tell where an
+ * object is from; so are the `cause` and `errors` of an Error.
  */
 function objectPaths(
   root: object,
   skip: ReadonlySet<string> = new Set(),
+  entries = false,
 ): Map<object, string[][]> {
   const all = new Map<object, string[][]>();
-  (function walk(node: Record<string, unknown>, path: string[]): void {
+  const collections: [object, string[]][] = [];
+  function place(value: object, at: string[]): void {
+    const known = all.get(value);
+    if (known) {
+      known.push(at);
+      return;
+    }
+    all.set(value, [at]);
+    if (isMergeable(value) || Array.isArray(value)) {
+      walk(value as Record<string, unknown>, at);
+    } else if (entries && entryChildren(value)) {
+      collections.push([value, at]);
+    }
+  }
+  function walk(node: Record<string, unknown>, path: string[]): void {
     for (const key of Object.keys(node)) {
       const value = node[key];
       if (!isObjectValue(value)) continue;
       const at = [...path, key];
       if (skip.has(pathKey(at))) continue;
-      const known = all.get(value);
-      if (known) {
-        known.push(at);
-        continue;
-      }
-      all.set(value, [at]);
-      if (isMergeable(value) || Array.isArray(value)) {
-        walk(value as Record<string, unknown>, at);
-      }
+      place(value, at);
+    }
+  }
+  walk(root as Record<string, unknown>, []);
+  for (const [collection, path] of collections) {
+    for (const [segment, value] of entryChildren(collection)!) {
+      if (isObjectValue(value)) place(value, [...path, segment]);
     }
-  })(root as Record<string, unknown>, []);
+  }
   return all;
 }
 
@@ -628,9 +805,13 @@ function objectPaths(
 function firstPaths(
   root: object,
   skip?: ReadonlySet<string>,
+  entries?: boolean,
 ): Map<object, string[]> {
   return new Map(
-    [...objectPaths(root, skip)].map(([object, paths]) => [object, paths[0]!]),
+    [...objectPaths(root, skip, entries)].map(([object, paths]) => [
+      object,
+      paths[0]!,
+    ]),
   );
 }
 
@@ -640,7 +821,55 @@ function firstPaths(
  * parents before children.
  */
 export function sharedPaths(root: object): string[][][] {
-  return [...objectPaths(root).values()].filter((paths) => paths.length > 1);
+  return [...objectPaths(root, undefined, true).values()].filter(
+    (paths) => paths.length > 1,
+  );
+}
+
+/**
+ * Whether `y`, which takes the place of `x` at `at` (the first appearance of
+ * both), holds an object elsewhere than `x` did, below an entry of a Map, Set
+ * or Error (see aliasChanges): `$map.set("k", $a)` over an equal object, or
+ * `$map.get("k").child = $a`. Entries are compared by position, and only
+ * where both hold as many; other differences are changes of content. Below
+ * an entry, objects that merge are compared key by key.
+ */
+function aliasMoved(
+  x: object,
+  y: object,
+  at: string[],
+  earlier: ReadonlyMap<object, string[]>,
+  later: ReadonlyMap<object, string[]>,
+): boolean {
+  const pairs: [string, unknown, unknown][] = [];
+  const xs = entryChildren(x);
+  const ys = entryChildren(y);
+  if (xs && ys) {
+    if (Object.getPrototypeOf(x) !== Object.getPrototypeOf(y)) return false;
+    if (x instanceof Map || x instanceof Set) {
+      if (x.size !== (y as Map<unknown, unknown>).size) return false;
+    }
+    const held = new Map(ys);
+    for (const [segment, a] of xs) {
+      if (held.has(segment)) pairs.push([segment, a, held.get(segment)]);
+    }
+  } else if ((isMergeable(x) || Array.isArray(x)) && mergesWith(x, y, true)) {
+    for (const key of Object.keys(y)) {
+      if (hasOwn(x, key)) {
+        pairs.push([key, (x as any)[key], (y as any)[key]]);
+      }
+    }
+  }
+  return pairs.some(([segment, a, b]) => {
+    if (!isObjectValue(a) || !isObjectValue(b)) return false;
+    const here = [...at, segment];
+    const isAt = later.get(b)!;
+    return (
+      pathKey(earlier.get(a)!) !== pathKey(isAt) ||
+      (pathKey(isAt) === pathKey(here) &&
+        aliasMoved(a, b, here, earlier, later))
+    );
+  });
 }
 
 /**
@@ -655,8 +884,8 @@ export function aliasChanges(
   before: Record<string, unknown>,
   after: Record<string, unknown>,
 ): PathChange[] {
-  const earlier = firstPaths(before);
-  const later = firstPaths(after);
+  const earlier = firstPaths(before, undefined, true);
+  const later = firstPaths(after, undefined, true);
   const changes: PathChange[] = [];
   (function walk(
     b: Record<string, unknown>,
@@ -674,6 +903,12 @@ export function aliasChanges(
       const k = pathKey(at);
       if (pathKey(wasAt) !== pathKey(isAt)) {
         changes.push({ path: at, deleted: false, value: y, alias: true });
+      } else if (
+        pathKey(isAt) === k &&
+        entryChildren(x) &&
+        aliasMoved(x, y, at, earlier, later)
+      ) {
+        changes.push({ path: at, deleted: false, value: y, alias: true });
       }
       // Only paths that are first appearances are entered: elsewhere the
       // contents are those of the object met first.
@@ -690,6 +925,30 @@ export function aliasChanges(
   return changes;
 }
 
+/**
+ * The changes from `before` to `after`, as paths below them: the property
+ * paths that differ (see diffPaths), and those that hold equal content but
+ * another object than they did (see aliasChanges), those first. Compared as
+ * one object, so an object that two of their keys share is one object,
+ * whichever of them it is reached through.
+ */
+export function changesBetween(
+  before: Record<string, unknown>,
+  after: Record<string, unknown>,
+  arrays = false,
+): PathChange[] {
+  const written = diffPaths(before, after, arrays);
+  const keys = new Set(written.map((c) => pathKey(c.path)));
+  const aliases: PathChange[] = [];
+  for (const change of aliasChanges(before, after)) {
+    // Written whole by a change at it or above it
+    if (underChange(change.path, keys)) continue;
+    keys.add(pathKey(change.path));
+    aliases.push(change);
+  }
+  return [...aliases, ...written];
+}
+
 /**
  * Where the objects of `source` are, other than at or below the paths of
  * `changes` (which write something new there), for `existingObjects`.
@@ -701,6 +960,7 @@ export function locateObjects(
   return firstPaths(
     source as Record<string, unknown>,
     new Set(changes.map((c) => pathKey(c.path))),
+    true,
   );
 }
 
@@ -720,7 +980,7 @@ export function existingObjects(
       if (super.has(obj)) return true;
       const path = paths.get(obj);
       if (!path) return false;
-      const found = getByPath(target, path);
+      const found = getByEntryPath(target, path);
       const like =
         isObjectValue(found) &&
         (Array.isArray(found)
@@ -745,50 +1005,22 @@ export function isApplied(target: object, change: PathChange): boolean {
   );
 }
 
+/**
+ * Make `path` below `root` hold `object` (an object that `sharedPaths` found
+ * at several paths): a property is written like setByPath() does, a Map's
+ * value replaced; an entry that is a key or member is left as it is.
+ */
+export function relinkPath(
+  root: Record<string, unknown>,
+  path: readonly string[],
+  object: object,
+): void {
+  if (path.some(isEntryKey)) setEntryValue(root, path, object);
+  else setByPath(root, path, object);
+}
+
 export function applyChange(target: object, change: PathChange): void {
   const root = target as Record<string, unknown>;
   if (change.deleted) deleteByPath(root, change.path);
   else setByPath(root, change.path, change.value);
 }
-
-/**
- * Write how `after` differs from `before` (see keyChanges; arrays merge by
- * index) into `target`, another version of the same object or array.
- * Values that changed are written whole, as deep copies; for values that
- * merge, `mergeNested` may merge them into `target` instead, returning
- * whether it did. Into an array, elements removed from the end are removed
- * at the same indices and elements added are appended, and changes at
- * indices `target` lacks are dropped: where `target` was resized, its
- * indices do not line up with `before`'s.
- */
-export function mergeKeys(
-  target: Record<string, unknown>,
-  before: Record<string, unknown>,
-  after: Record<string, unknown>,
-  mergeNested?: (
-    key: string,
-    before: Record<string, unknown>,
-    after: Record<string, unknown>,
-  ) => boolean,
-): void {
-  const list = Array.isArray(target) ? (target as unknown[]) : undefined;
-  for (const change of keyChanges(before, after, true)) {
-    const { key } = change;
-    if (change.kind === 'deleted') {
-      if (list) list.length = Math.min(list.length, Number(key));
-      else delete target[key];
-    } else if (list && change.kind === 'added') {
-      list.push(deepClone(change.after));
-    } else if (list && Number(key) >= list.length) {
-      continue;
-    } else if (
-      change.kind !== 'nested' ||
-      !(
-        mergeNested?.(key, change.before, change.after) ||
-        deepEqual(change.before, change.after)
-      )
-    ) {
-      target[key] = deepClone(change.after);
-    }
-  }
-}

package/src/utils/object-path.ts

@@ -7,13 +7,16 @@ import { atomicName } from './value-kinds';
  * Members of Object.prototype (`constructor`, `toString`, `__proto__`, ...)
  * are not story state: unless an object holds one as its own property, it
  * reads as missing, as setByPath() treats it. Other inherited properties
- * (class getters, `size` of a Map) are read.
+ * (class getters, `size` of a Map) are read, and so are those of a string,
+ * number or boolean (`length` of a string), as JavaScript boxes them.
  */
 export function getByPath(obj: object, segments: readonly string[]): unknown {
   let current: unknown = obj;
   for (const seg of segments) {
-    if (current == null || typeof current !== 'object') return undefined;
-    if (seg in Object.prototype && !hasOwn(current, seg)) return undefined;
+    if (current == null) return undefined;
+    if (seg in Object.prototype && !hasOwn(Object(current), seg)) {
+      return undefined;
+    }
     current = (current as Record<string, unknown>)[seg];
   }
   return current;