@rohal12/spindle 0.52.4 → 0.52.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.52.4",
+  "version": "0.52.5",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/class-registry.ts

@@ -1,5 +1,11 @@
 // Class registry for preserving class instances across clone/save/load cycles.
 
+import { setOwn } from './structural';
+import { hasOwn } from './utils/namespace';
+
+// Copying and comparing story values live with the structural diff
+export { deepClone, deepEqual, type DeepCloneOptions } from './structural';
+
 type Constructor = new (...args: any[]) => any;
 
 const registry = new Map<string, Constructor>();
@@ -33,188 +39,6 @@ export function clearRegistry(): void {
   ctorToName.clear();
 }
 
-// --- Deep Clone ---
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== 'object' || value === null) return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-}
-
-/**
- * Set an own enumerable property. A "__proto__" key is defined as an own
- * property (as JSON.parse does) instead of replacing the prototype.
- */
-function setOwn(target: object, key: string, value: unknown): void {
-  if (key === '__proto__') {
-    Object.defineProperty(target, key, {
-      value,
-      enumerable: true,
-      writable: true,
-      configurable: true,
-    });
-  } else {
-    (target as Record<string, unknown>)[key] = value;
-  }
-}
-
-export interface DeepCloneOptions {
-  /**
-   * Return instances of unregistered classes (DOM nodes, promises, other
-   * library objects) by reference instead of copying their own keys into a
-   * plain object, which would lose their prototype and identity.
-   */
-  keepUnregistered?: boolean;
-}
-
-export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
-  const seen = new Map<object, object>();
-
-  function clone(val: unknown): unknown {
-    if (val === null || typeof val !== 'object') return val;
-
-    const obj = val as object;
-    if (seen.has(obj)) return seen.get(obj);
-
-    if (val instanceof Date) return new Date(val.getTime()) as unknown;
-    if (val instanceof RegExp)
-      return new RegExp(val.source, val.flags) as unknown;
-
-    if (Array.isArray(val)) {
-      const arr: unknown[] = [];
-      seen.set(obj, arr);
-      for (let i = 0; i < val.length; i++) {
-        arr[i] = clone(val[i]);
-      }
-      return arr;
-    }
-
-    if (val instanceof Map) {
-      const copy = new Map();
-      seen.set(obj, copy);
-      for (const [k, v] of val) {
-        copy.set(clone(k), clone(v));
-      }
-      return copy;
-    }
-
-    if (val instanceof Set) {
-      const copy = new Set();
-      seen.set(obj, copy);
-      for (const v of val) {
-        copy.add(clone(v));
-      }
-      return copy;
-    }
-
-    // Registered class instance
-    const name = registeredClassName(obj);
-    if (name !== undefined) {
-      const copy = Object.create(Object.getPrototypeOf(obj)) as Record<
-        string,
-        unknown
-      >;
-      seen.set(obj, copy);
-      for (const key of Object.keys(obj)) {
-        setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
-      }
-      return copy;
-    }
-
-    // Plain object (or unregistered class — treat as plain). A plain object
-    // keeps its prototype, which may be null.
-    const plain = isPlainObject(val);
-    if (!plain && options.keepUnregistered) return val;
-    const copy = (
-      plain ? Object.create(Object.getPrototypeOf(obj) as object | null) : {}
-    ) as Record<string, unknown>;
-    seen.set(obj, copy);
-    for (const key of Object.keys(obj)) {
-      setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
-    }
-    return copy;
-  }
-
-  return clone(value) as T;
-}
-
-// --- Deep Equal ---
-
-/**
- * Structural equality over the value types deepClone() supports: primitives,
- * arrays, plain objects, class instances, Date, RegExp, Map and Set (nested
- * at any depth). Map and Set entries are compared in insertion order. Arrays
- * are compared by length and index, so a hole equals an undefined element
- * (deepClone() and save/load turn holes into undefined elements).
- */
-export function deepEqual(a: unknown, b: unknown): boolean {
-  return equal(a, b, new Map());
-}
-
-/**
- * `assumed` holds the pairs already being compared: meeting one again (a
- * cycle) assumes it equal. Every object may pair with several others, since
- * cycles of different lengths can still unfold to the same value.
- */
-function equal(
-  a: unknown,
-  b: unknown,
-  assumed: Map<object, Set<object>>,
-): boolean {
-  if (Object.is(a, b)) return true;
-  if (
-    a === null ||
-    b === null ||
-    typeof a !== 'object' ||
-    typeof b !== 'object'
-  ) {
-    return false;
-  }
-  if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
-  const pairs = assumed.get(a);
-  if (pairs?.has(b)) return true;
-  if (pairs) pairs.add(b);
-  else assumed.set(a, new Set([b]));
-
-  if (a instanceof Date) return Object.is(a.getTime(), (b as Date).getTime());
-  if (a instanceof RegExp) return String(a) === String(b);
-  if (a instanceof Map || a instanceof Set) {
-    const bc = b as Map<unknown, unknown> | Set<unknown>;
-    if (a.size !== bc.size) return false;
-    const ai = a.entries();
-    const bi = bc.entries();
-    for (
-      let x = ai.next(), y = bi.next();
-      !x.done;
-      x = ai.next(), y = bi.next()
-    ) {
-      if (!equal(x.value, y.value, assumed)) return false;
-    }
-    return true;
-  }
-
-  if (Array.isArray(a)) {
-    const bc = b as unknown[];
-    if (a.length !== bc.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!equal(a[i], bc[i], assumed)) return false;
-    }
-    return true;
-  }
-
-  const ao = a as Record<string, unknown>;
-  const bo = b as Record<string, unknown>;
-  const keys = Object.keys(ao);
-  if (keys.length !== Object.keys(bo).length) return false;
-  for (const key of keys) {
-    if (!hasOwn(bo, key) || !equal(ao[key], bo[key], assumed)) return false;
-  }
-  return true;
-}
-
-const hasOwn = (obj: object, key: string): boolean =>
-  Object.prototype.hasOwnProperty.call(obj, key);
-
 // --- Serialize ---
 
 const CLASS_TAG = '__spindle_class__';

package/src/execute-mutation.ts

@@ -9,9 +9,18 @@ import {
 import { useStoryStore } from './store';
 import type { StoryState, VariableNamespaces } from './store';
 import { execute } from './expression';
-import { deepClone, deepEqual } from './class-registry';
-import { deleteByPath, getByPath, setByPath } from './utils/object-path';
-import { asNamespace } from './utils/namespace';
+import {
+  applyChange,
+  deepClone,
+  deepEqual,
+  diffPaths,
+  isApplied,
+  isMergeable,
+  mergeKeys,
+  type PathChange,
+} from './structural';
+import { getByPath } from './utils/object-path';
+import { asNamespace, hasOwn } from './utils/namespace';
 
 type NamespaceName = keyof VariableNamespaces;
 
@@ -21,11 +30,6 @@ const NAMESPACES: readonly NamespaceName[] = [
   'transient',
 ];
 
-/** A write to one property path of a namespace, or its deletion. */
-type PathChange =
-  | { path: string[]; deleted: false; value: unknown }
-  | { path: string[]; deleted: true };
-
 /**
  * The state of one executing mutation. The code reads and writes `work`.
  * `base` is what `work` started as, with every write made elsewhere during
@@ -76,80 +80,6 @@ export function frozenCopy<T>(value: T): T {
   return freeze(cloneValue(value), true);
 }
 
-/**
- * Objects merged property by property: plain objects and (registered)
- * class instances. Arrays, Map, Set, Date and RegExp are values that are
- * replaced as a whole, since their elements have no stable identity to
- * merge by (a shift moves every index).
- */
-export function isMergeable(value: unknown): value is Record<string, unknown> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    !Array.isArray(value) &&
-    !(value instanceof Map) &&
-    !(value instanceof Set) &&
-    !(value instanceof Date) &&
-    !(value instanceof RegExp)
-  );
-}
-
-const hasOwn = (obj: object, key: string): boolean =>
-  Object.prototype.hasOwnProperty.call(obj, key);
-
-/** Collect the property paths where `work` differs from `base`. */
-function diff(
-  base: Record<string, unknown>,
-  work: Record<string, unknown>,
-  path: string[],
-  changes: PathChange[],
-  ancestors: Set<object>,
-): void {
-  // Stop at cycles; shared (non-cyclic) references are visited per path.
-  if (ancestors.has(work)) return;
-  ancestors.add(work);
-  for (const key of Object.keys(work)) {
-    const b = base[key];
-    const w = work[key];
-    if (!hasOwn(base, key)) {
-      changes.push({ path: [...path, key], deleted: false, value: w });
-    } else if (Object.is(b, w)) {
-      // The same value (an untouched subtree of an Immer update)
-      continue;
-    } else if (
-      isMergeable(b) &&
-      isMergeable(w) &&
-      Object.getPrototypeOf(b) === Object.getPrototypeOf(w)
-    ) {
-      diff(b, w, [...path, key], changes, ancestors);
-    } else if (!deepEqual(b, w)) {
-      changes.push({ path: [...path, key], deleted: false, value: w });
-    }
-  }
-  for (const key of Object.keys(base)) {
-    if (!hasOwn(work, key))
-      changes.push({ path: [...path, key], deleted: true });
-  }
-  ancestors.delete(work);
-}
-
-/** Whether `ns` already holds what `change` would write. */
-function isApplied(ns: Record<string, unknown>, change: PathChange): boolean {
-  const parent = getByPath(ns, change.path.slice(0, -1));
-  if (parent === null || typeof parent !== 'object') return change.deleted;
-  const key = change.path[change.path.length - 1]!;
-  if (!hasOwn(parent, key)) return change.deleted;
-  return (
-    !change.deleted &&
-    deepEqual((parent as Record<string, unknown>)[key], change.value)
-  );
-}
-
-function applyChange(ns: Record<string, unknown>, change: PathChange): void {
-  if (change.deleted) deleteByPath(ns, change.path);
-  else setByPath(ns, change.path, change.value);
-}
-
 /**
  * Apply a write that reached the store while mutations execute to their
  * `work` and `base` copies (see MutationScope), so the code sees it and
@@ -381,11 +311,9 @@ function commitScopes(commits: readonly Commit[]): void {
   const all = commits.map(({ scope, keepRunning }) => ({
     scope,
     keepRunning,
-    changes: NAMESPACES.map((ns) => {
-      const list: PathChange[] = [];
-      diff(scope.base[ns], scope.work[ns], [], list, new Set());
-      return [ns, list] as const;
-    }),
+    changes: NAMESPACES.map(
+      (ns) => [ns, diffPaths(scope.base[ns], scope.work[ns])] as const,
+    ),
   }));
   const changed = all.filter(({ changes }) =>
     changes.some(([, list]) => list.length > 0),
@@ -450,16 +378,8 @@ const running = (): Commit[] =>
 function resync(scope: MutationScope): void {
   const state = useStoryStore.getState();
   for (const ns of NAMESPACES) {
-    const work = scope.work[ns];
-    const stored = state[ns];
-    for (const key of Object.keys(work)) {
-      if (!hasOwn(stored, key)) delete work[key];
-    }
-    for (const key of Object.keys(stored)) {
-      if (!hasOwn(work, key) || !deepEqual(work[key], stored[key])) {
-        work[key] = deepClone(stored[key]);
-      }
-    }
+    // Root by root: a root that differs is replaced with a copy of the store's
+    mergeKeys(scope.work[ns], scope.work[ns], state[ns]);
   }
   scope.base = cloneNamespaces(state);
 }