@rohal12/spindle 0.59.3 → 0.59.5

package/src/store.ts

@@ -44,8 +44,16 @@ import {
   deletePlaythroughData as smDeletePlaythroughData,
 } from './saves/save-manager';
 
-import { deepClone, mergeKeys, mergesWith, shareEqual } from './structural';
-import { shallowCopy } from './utils/object-path';
+import {
+  changesBetween,
+  deepClone,
+  existingObjects,
+  locateObjects,
+  mergesWith,
+  shareEqual,
+  type PathChange,
+} from './structural';
+import { getByPath } from './utils/object-path';
 import { noPassageError, showRuntimeError } from './runtime-errors';
 import {
   snapshotPRNG,
@@ -708,11 +716,13 @@ function loadedEntryMoment(
  * the `beforesave` hooks) into the payload's snapshot of the saved moment. A
  * load restores that snapshot, the state on entering the passage, and runs
  * the passage again, so data a hook adds to a save would otherwise be lost
- * on load (#227). Only the property paths the hooks changed are written (into
- * copies of the objects on those paths, the rest staying shared): a
- * whole variable would bring along what the passage did to the rest of it,
- * which the passage then does again on load (#232). Only the payload's copy
- * changes: the live history keeps the recorded snapshot (#159).
+ * on load (#227). Only the property paths the hooks changed are written (see
+ * changesBetween): a whole variable would bring along what the passage did
+ * to the rest of it, which the passage then does again on load (#232). The
+ * references the hooks made stay: an object they put in two variables is one
+ * object in the snapshot, and one they made another variable refer to is the
+ * snapshot's own object of it (#302). Only the payload's copy changes: the
+ * live history keeps the recorded snapshot (#159).
  */
 function keepHookWrites(
   payload: SavePayload,
@@ -721,41 +731,67 @@ function keepHookWrites(
 ): void {
   const moment = payload.history[payload.historyIndex];
   if (!moment) return;
-  mergeHookWrites(moment.variables, before, after, new Set());
+  const changes = changesBetween(before, after, true);
+  if (changes.length === 0) return;
+  // A copy of its own, so the writes keep the snapshot's references (which
+  // the history shares with other moments) as they are
+  const work = deepClone(moment.variables);
+  const seen = existingObjects(locateObjects(after, changes), work);
+  const own = <T>(value: T): T => deepClone(value, { seen });
+  for (const change of changes) writeHookChange(work, after, change, own);
+  moment.variables = shareEqual(moment.variables, work);
 }
 
 /**
- * Apply the hooks' changes between `before` and `after`, two objects or two
- * arrays, to the snapshot's copy of them, `target` (see mergeKeys: array
- * elements merge by index). A changed value is merged key by key where the
- * snapshot holds the same kind of value. Where it lacks the key or holds
- * another kind (the passage created or replaced it), the hooks' whole value
- * is written.
+ * Write `change` (of the hooks, to `after`) into `work`. The value goes in at
+ * the first place `work` lacks the objects on the path of one of the kind
+ * `after` holds (the passage created or replaced it): there, the hooks' whole
+ * value of it is written. Into an array, elements removed from the end are
+ * removed at the same indices and elements added are appended; changes at
+ * indices the array lacks are dropped (it was resized, so its indices do not
+ * line up with the live ones).
  */
-function mergeHookWrites(
-  target: Record<string, unknown>,
-  before: Record<string, unknown>,
+function writeHookChange(
+  work: Record<string, unknown>,
   after: Record<string, unknown>,
-  ancestors: Set<object>,
+  change: PathChange,
+  own: <T>(value: T) => T,
 ): void {
-  ancestors.add(after);
-  mergeKeys(target, before, after, (key, b, a) => {
-    if (
-      !hasOwn(target, key) ||
-      !mergesWith(a, target[key], true) ||
-      // Stop at cycles: deepEqual() and deepClone() handle them
-      ancestors.has(a)
-    ) {
-      return false;
+  const { path } = change;
+  let holder: Record<string, unknown> = work;
+  let depth = 0;
+  for (; depth < path.length - 1; depth++) {
+    const key = path[depth]!;
+    const child = hasOwn(holder, key) ? holder[key] : undefined;
+    const held = getByPath(after, path.slice(0, depth + 1));
+    if (!mergesWith(child, held, true)) {
+      writeKey(holder, key, false, own(held));
+      return;
     }
-    // The snapshot's values are the history's own (immutable, see
-    // plainCopy): merge into a copy, made along the merged path only
-    const copy = shallowCopy(target[key] as object);
-    target[key] = copy;
-    mergeHookWrites(copy, b, a, ancestors);
-    return true;
-  });
-  ancestors.delete(after);
+    holder = child as Record<string, unknown>;
+  }
+  const key = path[depth]!;
+  if (change.deleted) writeKey(holder, key, true, undefined);
+  else writeKey(holder, key, false, own(change.value), change.appended);
+}
+
+function writeKey(
+  holder: Record<string, unknown>,
+  key: string,
+  deleted: boolean,
+  value: unknown,
+  appended?: boolean,
+): void {
+  if (Array.isArray(holder)) {
+    const index = Number(key);
+    if (deleted) holder.length = Math.min(holder.length, index);
+    else if (appended) holder.push(value);
+    else if (index < holder.length) holder[index] = value;
+  } else if (deleted) {
+    delete holder[key];
+  } else {
+    setOwn(holder, key, value);
+  }
 }
 
 /** Restore the PRNG from a snapshot, or reset it without one. */

package/src/story-api.ts

@@ -21,7 +21,11 @@ import {
 } from './saves/save-manager';
 import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
-import { frozenCopy, getActiveMutationScope } from './execute-mutation';
+import {
+  frozenCopy,
+  getActiveMutationScope,
+  mutateState,
+} from './execute-mutation';
 import { getByPath, setByPath } from './utils/object-path';
 import { changedNames, checkVariableName, ownValue } from './utils/namespace';
 import { historyQueries } from './expression';
@@ -298,6 +302,16 @@ function createStoryAPI(): StoryAPI {
       // while mutation code runs ({do}, ctx.mutate, watcher run actions), it
       // follows the code's own pending writes (program order, #215): see
       // routeStoreUpdate.
+      if (entries.some(([k]) => k.includes('.'))) {
+        // A write below a variable goes through the commit mutation code
+        // uses (nested in the running code, if any: it continues from the
+        // code's pending writes, and they are committed first): an update of a draft would give the written path new
+        // objects and leave the other references to the old ones (#295).
+        mutateState((work, adopt) => {
+          for (const [k, v] of entries) setOne(work, k, adopt(v));
+        });
+        return;
+      }
       useStoryStore.getState().updateVariables((draft) => {
         for (const [k, v] of entries) setOne(draft, k, v);
       });

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 key a Map is given in the copy and the key it was copied
+   * from; the key it returns is the one the copy takes (for a store draft,
+   * which Immer does not finalize in a Map key).
+   */
+  mapKey?: (copy: object, original: object) => object;
 }
 
 type TypedArrayCtor = new (
@@ -133,7 +139,14 @@ 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));
+        const key = clone(k);
+        const settle = options.mapKey;
+        copy.set(
+          settle && isObjectValue(key) && isObjectValue(k)
+            ? settle(key, k)
+            : key,
+          clone(v),
+        );
       }
       return copy;
     }
@@ -533,6 +546,8 @@ export type PathChange =
       path: string[];
       deleted: false;
       value: unknown;
+      /** Set for an element an array gained beyond the length it had. */
+      appended?: true;
       /**
        * Set where the value is the same content as before and only which
        * object the path refers to changed (see aliasChanges), so a store
@@ -545,11 +560,13 @@ export type PathChange =
 /**
  * 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>();
@@ -561,7 +578,7 @@ export function diffPaths(
     // Stop at cycles; shared (non-cyclic) references are visited per path.
     if (ancestors.has(a)) return;
     ancestors.add(a);
-    for (const change of keyChanges(b, a, false)) {
+    for (const change of keyChanges(b, a, arrays)) {
       const at = [...path, change.key];
       if (change.kind === 'nested') {
         walk(change.before, change.after, at);
@@ -569,7 +586,14 @@ export function diffPaths(
         changes.push(
           change.kind === 'deleted'
             ? { path: at, deleted: true }
-            : { path: at, deleted: false, value: change.after },
+            : {
+                path: at,
+                deleted: false,
+                value: change.after,
+                ...(change.kind === 'added' && Array.isArray(a)
+                  ? { appended: true as const }
+                  : {}),
+              },
         );
       }
     }
@@ -592,27 +616,124 @@ export function underChange(
   return false;
 }
 
+/** The segment standing for the entry `index` of a Map or Set in a path. */
+const entryKey = (kind: 'k' | 'v' | 's', index: number): string =>
+  `\0${kind}${index}`;
+
 /**
- * Where each object (or array, or other value) of `root` first appears, in
- * depth-first order. Plain objects are entered; arrays and other values are
- * leaves. A path at or below one of `skip` is left out.
+ * 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, so only to tell where an object is from.
  */
-function firstPaths(
-  root: Record<string, unknown>,
+function objectPaths(
+  root: object,
   skip: ReadonlySet<string> = new Set(),
-): Map<object, string[]> {
-  const found = new Map<object, string[]>();
-  (function walk(node: Record<string, unknown>, path: string[]): void {
+  entries = false,
+): Map<object, string[][]> {
+  const all = new Map<object, string[][]>();
+  const collections: [Map<unknown, unknown> | Set<unknown>, 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 && (value instanceof Map || value instanceof Set)) {
+      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) || found.has(value)) continue;
+      if (!isObjectValue(value)) continue;
       const at = [...path, key];
       if (skip.has(pathKey(at))) continue;
-      found.set(value, at);
-      if (isMergeable(value)) walk(value, at);
+      place(value, at);
+    }
+  }
+  walk(root as Record<string, unknown>, []);
+  for (const [collection, path] of collections) {
+    let index = 0;
+    for (const entry of collection.entries()) {
+      const [k, v] = entry as [unknown, unknown];
+      const parts: [unknown, string][] =
+        collection instanceof Set
+          ? [[k, entryKey('s', index)]]
+          : [
+              [k, entryKey('k', index)],
+              [v, entryKey('v', index)],
+            ];
+      for (const [value, segment] of parts) {
+        if (isObjectValue(value) && !all.has(value)) {
+          place(value, [...path, segment]);
+        }
+      }
+      index++;
     }
-  })(root, []);
-  return found;
+  }
+  return all;
+}
+
+/** Where each object of `root` first appears (see objectPaths). */
+function firstPaths(
+  root: object,
+  skip?: ReadonlySet<string>,
+  entries?: boolean,
+): Map<object, string[]> {
+  return new Map(
+    [...objectPaths(root, skip, entries)].map(([object, paths]) => [
+      object,
+      paths[0]!,
+    ]),
+  );
+}
+
+/**
+ * The objects `root` holds at more than one path (an object two variables
+ * refer to, or one that refers to itself), with every path they are at,
+ * parents before children.
+ */
+export function sharedPaths(root: object): string[][][] {
+  return [...objectPaths(root).values()].filter((paths) => paths.length > 1);
+}
+
+/**
+ * Whether the Map or Set `y` holds, at the position of an entry of `x`, another
+ * object than `x` did (as to where its first appearance is, see aliasChanges):
+ * `$map.set("k", $a)` over an equal object. Entries are compared by position,
+ * and only when both hold as many; other differences are changes of content.
+ */
+function entryAliasChanged(
+  x: object,
+  y: object,
+  earlier: ReadonlyMap<object, string[]>,
+  later: ReadonlyMap<object, string[]>,
+): boolean {
+  const isSet = x instanceof Set && y instanceof Set;
+  if (!isSet && !(x instanceof Map && y instanceof Map)) return false;
+  if (Object.getPrototypeOf(x) !== Object.getPrototypeOf(y)) return false;
+  if (x.size !== y.size) return false;
+  const moved = (a: unknown, b: unknown): boolean =>
+    isObjectValue(a) &&
+    isObjectValue(b) &&
+    pathKey(earlier.get(a)!) !== pathKey(later.get(b)!);
+  const ys = [...(y as Map<unknown, unknown>).entries()];
+  let index = 0;
+  for (const [k, v] of (x as Map<unknown, unknown>).entries()) {
+    const [k2, v2] = ys[index++]!;
+    if (moved(k, k2) || (!isSet && moved(v, v2))) return true;
+  }
+  return false;
 }
 
 /**
@@ -627,8 +748,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>,
@@ -646,31 +767,63 @@ 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 &&
+        entryAliasChanged(x, y, 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.
       if (
-        isMergeable(x) &&
-        mergesWith(x, y, false) &&
+        (isMergeable(x) || Array.isArray(x)) &&
+        mergesWith(x, y, true) &&
         pathKey(isAt) === k &&
         pathKey(wasAt) === k
       ) {
-        walk(x, y as Record<string, unknown>, at);
+        walk(x as Record<string, unknown>, y as Record<string, unknown>, at);
       }
     }
   })(before, after, []);
   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`.
  */
 export function locateObjects(
-  source: Record<string, unknown>,
+  source: object,
   changes: readonly PathChange[],
 ): Map<object, string[]> {
-  return firstPaths(source, new Set(changes.map((c) => pathKey(c.path))));
+  return firstPaths(
+    source as Record<string, unknown>,
+    new Set(changes.map((c) => pathKey(c.path))),
+  );
 }
 
 /**
@@ -682,7 +835,7 @@ export function locateObjects(
  */
 export function existingObjects(
   paths: ReadonlyMap<object, string[]>,
-  target: Record<string, unknown>,
+  target: object,
 ): Map<object, object> {
   return new (class extends Map<object, object> {
     override has(obj: object): boolean {
@@ -703,10 +856,7 @@ export function existingObjects(
 }
 
 /** Whether `target` already holds what `change` would write. */
-export function isApplied(
-  target: Record<string, unknown>,
-  change: PathChange,
-): boolean {
+export function isApplied(target: object, change: PathChange): boolean {
   const parent = getByPath(target, change.path.slice(0, -1));
   if (parent === null || typeof parent !== 'object') return change.deleted;
   const key = change.path[change.path.length - 1]!;
@@ -717,12 +867,10 @@ export function isApplied(
   );
 }
 
-export function applyChange(
-  target: Record<string, unknown>,
-  change: PathChange,
-): void {
-  if (change.deleted) deleteByPath(target, change.path);
-  else setByPath(target, change.path, change.value);
+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);
 }
 
 /**

package/src/utils/object-path.ts

@@ -9,10 +9,7 @@ import { atomicName } from './value-kinds';
  * reads as missing, as setByPath() treats it. Other inherited properties
  * (class getters, `size` of a Map) are read.
  */
-export function getByPath(
-  obj: Record<string, unknown>,
-  segments: readonly string[],
-): unknown {
+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;
@@ -38,7 +35,8 @@ const builtinName = atomicName;
  */
 export function shallowCopy(value: object): Record<string, unknown> {
   const copy = Array.isArray(value)
-    ? []
+    ? // Keep the length: trailing holes are not among the keys
+      new Array<unknown>(value.length)
     : (Object.create(Object.getPrototypeOf(value) as object | null) as object);
   // Define rather than assign (Object.assign), so that a "__proto__" key
   // stays a key instead of replacing the copy's prototype