@rohal12/spindle 0.52.8 → 0.53.0

package/src/structural.ts

@@ -2,12 +2,21 @@
 // and merging the differences between two versions of a value. Mutation
 // commits, history and save hooks all go through these, so they agree on
 // what a change is.
+//
+// They handle the value types a save holds (see serialize() in
+// class-registry.ts): plain and prototype-less objects, arrays (holes kept),
+// registered class instances, Date, RegExp, Map, Set, typed arrays,
+// ArrayBuffer, DataView, URL, URLSearchParams, boxed primitives, errors and
+// Temporal values, with shared references and cycles.
 
 import { registeredClassName } from './class-registry';
 import { hasOwn, setOwn } from './utils/namespace';
 import { deleteByPath, getByPath, setByPath } from './utils/object-path';
+import { isAtomic, isBoxed, isTemporal } from './utils/value-kinds';
 
-// --- Deep Clone ---
+export { isAtomic };
+
+// --- Value kinds ---
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (typeof value !== 'object' || value === null) return false;
@@ -15,6 +24,11 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
+/** Own keys of an error that are not enumerable but are data. */
+const ERROR_HIDDEN_KEYS = ['message', 'cause', 'errors'] as const;
+
+// --- Deep Clone ---
+
 export interface DeepCloneOptions {
   /**
    * Return instances of unregistered classes (DOM nodes, promises, other
@@ -24,31 +38,85 @@ export interface DeepCloneOptions {
   keepUnregistered?: boolean;
 }
 
+type TypedArrayCtor = new (
+  buffer: ArrayBufferLike,
+  byteOffset: number,
+  length: number,
+) => ArrayBufferView;
+
 export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
   const seen = new Map<object, object>();
 
+  /** Record `copy` as the copy of `obj` before its contents are copied. */
+  const keep = <C extends object>(obj: object, copy: C): C => {
+    seen.set(obj, copy);
+    return copy;
+  };
+
+  /** Copy the own (enumerable) keys of `obj` into `copy`. */
+  function copyKeys(obj: object, copy: object): object {
+    for (const key of Object.keys(obj)) {
+      setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
+    }
+    return copy;
+  }
+
+  function cloneBuiltin(val: object): object | undefined {
+    if (val instanceof Date) return keep(val, new Date(val.getTime()));
+    if (val instanceof RegExp) {
+      return keep(val, new RegExp(val.source, val.flags));
+    }
+    if (val instanceof ArrayBuffer) return keep(val, val.slice(0));
+    if (ArrayBuffer.isView(val)) {
+      // The buffer through the copies, so views of one buffer share it
+      const buffer = clone(val.buffer) as ArrayBuffer;
+      if (val instanceof DataView) {
+        return keep(val, new DataView(buffer, val.byteOffset, val.byteLength));
+      }
+      const ctor = val.constructor as TypedArrayCtor;
+      const length = (val as unknown as { length: number }).length;
+      return keep(val, new ctor(buffer, val.byteOffset, length));
+    }
+    if (val instanceof URL) return keep(val, new URL(val.href));
+    if (val instanceof URLSearchParams) {
+      return keep(val, new URLSearchParams(val));
+    }
+    if (isBoxed(val)) return keep(val, Object((val as Number).valueOf()));
+    if (isTemporal(val)) return val;
+    if (val instanceof Error) {
+      // Keeps its class (built-in, or a registered or other subclass)
+      const copy = keep(val, Object.create(Object.getPrototypeOf(val)));
+      for (const key of [...ERROR_HIDDEN_KEYS, 'stack']) {
+        if (hasOwn(val, key)) {
+          Object.defineProperty(copy, key, {
+            value: clone((val as unknown as Record<string, unknown>)[key]),
+            writable: true,
+            configurable: true,
+          });
+        }
+      }
+      return copyKeys(val, copy);
+    }
+    return undefined;
+  }
+
   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);
+      // Holes stay holes
+      const arr = keep(obj, new Array(val.length) as unknown[]);
       for (let i = 0; i < val.length; i++) {
-        arr[i] = clone(val[i]);
+        if (i in val) arr[i] = clone(val[i]);
       }
       return arr;
     }
 
     if (val instanceof Map) {
-      const copy = new Map();
-      seen.set(obj, copy);
+      const copy = keep(obj, new Map());
       for (const [k, v] of val) {
         copy.set(clone(k), clone(v));
       }
@@ -56,30 +124,29 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
     }
 
     if (val instanceof Set) {
-      const copy = new Set();
-      seen.set(obj, copy);
+      const copy = keep(obj, new Set());
       for (const v of val) {
         copy.add(clone(v));
       }
       return copy;
     }
 
+    const builtin = cloneBuiltin(obj);
+    if (builtin !== undefined) return builtin;
+
     // A registered class instance keeps its class, and a plain object its
     // prototype (which may be null). An instance of an unregistered class
     // is treated as plain, unless it is kept by reference.
     const keepsProto =
       registeredClassName(obj) !== undefined || isPlainObject(val);
     if (!keepsProto && options.keepUnregistered) return val;
-    const copy = (
+    const copy = keep(
+      obj,
       keepsProto
         ? 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 copyKeys(obj, copy);
   }
 
   return clone(value) as T;
@@ -88,27 +155,179 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): 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).
+ * Structural equality over the value types deepClone() supports, nested at
+ * any depth and with cycles. Objects must have the same prototype. Map and
+ * Set entries are compared in insertion order, so reordering one is a
+ * change. Arrays are compared by length and index; a hole differs from an
+ * undefined element. Errors are compared by class, message, cause, errors
+ * and own keys (not their stack).
  */
 export function deepEqual(a: unknown, b: unknown): boolean {
-  return equal(a, b, new Map());
+  return equal(a, b, loosePairs());
 }
 
 /**
- * `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.
+ * Called on meeting the pair (a, b) of objects to compare: true when the
+ * pair is already being compared (a cycle: assume it equal), false when it
+ * cannot be equal, undefined to compare it.
  */
-function equal(
-  a: unknown,
-  b: unknown,
-  assumed: Map<object, Set<object>>,
-): boolean {
-  if (Object.is(a, b)) return true;
+type Pairs = ((a: object, b: object) => boolean | undefined) & {
+  /** Identical objects are paired and compared too, not taken as equal. */
+  strict?: boolean;
+};
+
+/**
+ * Pairs for deepEqual(). Every object may pair with several others, since
+ * cycles of different lengths can still unfold to the same value, and
+ * shared references may equal distinct copies.
+ */
+function loosePairs(): Pairs {
+  const assumed = new Map<object, Set<object>>();
+  return (a, b) => {
+    const pairs = assumed.get(a);
+    if (pairs?.has(b)) return true;
+    if (pairs) pairs.add(b);
+    else assumed.set(a, new Set([b]));
+    return undefined;
+  };
+}
+
+/**
+ * Pairs that also require the same reference structure: each object of one
+ * value pairs with exactly one of the other, so shared references and
+ * cycles are shared at the same places.
+ */
+function strictPairs(): Pairs {
+  const ab = new Map<object, object>();
+  const ba = new Map<object, object>();
+  const pairs: Pairs = (a, b) => {
+    const known = ab.get(a);
+    if (known !== undefined) return known === b;
+    if (ba.has(b)) return false;
+    ab.set(a, b);
+    ba.set(b, a);
+    return undefined;
+  };
+  pairs.strict = true;
+  return pairs;
+}
+
+/**
+ * Whether `a` and `b` are equal as deepEqual() has it and also share
+ * references at the same places (a save of one loads as the other).
+ */
+export function deepEqualStrict(a: unknown, b: unknown): boolean {
+  return equal(a, b, strictPairs());
+}
+
+/**
+ * `curr` with each part that equals (see deepEqualStrict) the part of
+ * `prev` at the same place replaced by `prev`'s: the history moments of a
+ * save then share what did not change between them, which a save stores
+ * once. Containers on the way to a change are copied; neither value is
+ * changed. Shared references and cycles within `curr` stay so.
+ */
+export function shareEqual<T>(prev: unknown, curr: T): T {
+  const done = new Map<object, unknown>();
+  function share(p: unknown, c: unknown): unknown {
+    if (p === c || !isObjectValue(c) || !isObjectValue(p)) return c;
+    if (done.has(c)) return done.get(c);
+    if (deepEqualStrict(p, c)) {
+      done.set(c, p);
+      return p;
+    }
+    if (c instanceof Map && p instanceof Map) {
+      const out = new Map();
+      done.set(c, out);
+      for (const [k, v] of c) out.set(k, p.has(k) ? share(p.get(k), v) : v);
+      return out;
+    }
+    if (Array.isArray(c) && Array.isArray(p)) {
+      const out = new Array(c.length) as unknown[];
+      done.set(c, out);
+      for (let i = 0; i < c.length; i++) {
+        if (i in c) out[i] = i < p.length ? share(p[i], c[i]) : c[i];
+      }
+      return out;
+    }
+    if (mergesWith(p, c, false)) {
+      const out = Object.create(Object.getPrototypeOf(c) as object | null);
+      done.set(c, out);
+      const cr = c as Record<string, unknown>;
+      for (const key of Object.keys(cr)) {
+        setOwn(out, key, hasOwn(p, key) ? share(p[key], cr[key]) : cr[key]);
+      }
+      return out;
+    }
+    done.set(c, c);
+    return c;
+  }
+  return share(prev, curr) as T;
+}
+
+const isObjectValue = (v: unknown): v is object =>
+  typeof v === 'object' && v !== null;
+
+function equalBytes(a: ArrayBufferView | ArrayBuffer, b: typeof a): boolean {
+  const x = ArrayBuffer.isView(a)
+    ? new Uint8Array(a.buffer, a.byteOffset, a.byteLength)
+    : new Uint8Array(a);
+  const y = ArrayBuffer.isView(b)
+    ? new Uint8Array(b.buffer, b.byteOffset, b.byteLength)
+    : new Uint8Array(b as ArrayBuffer);
+  if (x.length !== y.length) return false;
+  for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
+  return true;
+}
+
+/** Equality of the content of atomic built-ins (see isAtomic) but Map/Set. */
+function equalBuiltin(
+  a: object,
+  b: object,
+  assumed: Pairs,
+): boolean | undefined {
+  if (a instanceof Date) return Object.is(a.getTime(), (b as Date).getTime());
+  if (a instanceof RegExp) return String(a) === String(b);
+  if (ArrayBuffer.isView(a) || a instanceof ArrayBuffer) {
+    return equalBytes(a, b as ArrayBuffer);
+  }
+  if (a instanceof URL || a instanceof URLSearchParams) {
+    return String(a) === String(b);
+  }
+  if (isBoxed(a)) {
+    return Object.is((a as Number).valueOf(), (b as Number).valueOf());
+  }
+  if (isTemporal(a)) return String(a) === String(b);
+  if (a instanceof Error) {
+    return (
+      ERROR_HIDDEN_KEYS.every(
+        (key) =>
+          hasOwn(a, key) === hasOwn(b, key) &&
+          equal(
+            (a as unknown as Record<string, unknown>)[key],
+            (b as unknown as Record<string, unknown>)[key],
+            assumed,
+          ),
+      ) && equalKeys(a, b, assumed)
+    );
+  }
+  return undefined;
+}
+
+function equalKeys(a: object, b: object, assumed: Pairs): boolean {
+  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;
+}
+
+/** `assumed` tracks the pairs of objects met (see Pairs). */
+function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
+  if (Object.is(a, b) && !(assumed.strict && isObjectValue(a))) return true;
   if (
     a === null ||
     b === null ||
@@ -118,13 +337,9 @@ function equal(
     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]));
+  const met = assumed(a, b);
+  if (met !== undefined) return met;
 
-  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;
@@ -140,42 +355,36 @@ function equal(
     return true;
   }
 
+  const builtin = equalBuiltin(a, b, assumed);
+  if (builtin !== undefined) return builtin;
+
   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;
+      if (i in a !== i in bc || !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;
+  return equalKeys(a, b, assumed);
 }
 
 // --- Structural diff ---
 
 /**
  * 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).
+ * class instances. Arrays and atomic built-ins (Map, Set, Date, typed
+ * arrays, errors..., see isAtomic) are values that are replaced as a whole,
+ * since their elements have no stable identity to merge by (a shift moves
+ * every index) or their content is not in their keys.
  */
 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)
+    !isAtomic(value)
   );
 }
 

package/src/styles.css

@@ -118,6 +118,51 @@ tw-storydata {
   background: rgba(239, 83, 80, 0.1);
 }
 
+/* Runtime errors shown on the page (see src/components/RuntimeErrors.tsx) */
+.spindle-error-banners {
+  position: fixed;
+  top: 0.75em;
+  left: 50%;
+  z-index: 300;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5em;
+  width: min(42em, calc(100% - 1.5em));
+  transform: translateX(-50%);
+}
+
+.spindle-error-banner {
+  position: relative;
+  padding: 0.75em 2.75em 0.75em 1em;
+  border: 1px solid #ef5350;
+  border-radius: 4px;
+  background: #2b1a1e;
+  color: #ffcdd2;
+  font-size: 0.9em;
+  line-height: 1.5;
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.5);
+}
+
+.spindle-error-banner-message {
+  font-family: monospace;
+  color: #ef9a9a;
+}
+
+.spindle-error-banner-dismiss {
+  position: absolute;
+  top: 0.5em;
+  right: 0.5em;
+  background: transparent;
+  border: none;
+  color: inherit;
+  font-size: 1em;
+  cursor: pointer;
+}
+
+.spindle-error-banner-dismiss:hover {
+  color: #fff;
+}
+
 .loading {
   text-align: center;
   padding: 2em;

package/src/utils/object-path.ts

@@ -1,5 +1,6 @@
-import { isDraft } from 'immer';
+import { current as draftState, isDraft } from 'immer';
 import { hasOwn } from './namespace';
+import { atomicName } from './value-kinds';
 
 /**
  * Traverse dot-path segments on an object and return the nested value.
@@ -29,22 +30,13 @@ const isArrayKey = (key: string): boolean =>
  * Built-ins whose content is not their properties: a property written into
  * one would be dropped by clones and saves (and by Immer, for Map and Set).
  */
-const builtinName = (value: object): string | undefined =>
-  value instanceof Map
-    ? 'a Map'
-    : value instanceof Set
-      ? 'a Set'
-      : value instanceof Date
-        ? 'a Date'
-        : value instanceof RegExp
-          ? 'a RegExp'
-          : undefined;
+const builtinName = atomicName;
 
 /**
  * Shallow copy that keeps the prototype, so a registered class instance
  * stays an instance of its class (with the same own keys deepClone copies).
  */
-function shallowCopy(value: object): Record<string, unknown> {
+export function shallowCopy(value: object): Record<string, unknown> {
   const copy = Array.isArray(value)
     ? []
     : (Object.create(Object.getPrototypeOf(value) as object | null) as object);
@@ -120,6 +112,15 @@ export function deleteByPath(
     return;
   }
   const parent = walkToParent(root, segments, false);
+  if (Array.isArray(parent) && isDraft(parent) && segments.length > 1) {
+    // Immer turns `delete` of an array element into writing undefined: to
+    // leave a hole, as `delete` does, put in a copy of the array with one
+    const copy = (draftState(parent) as unknown[]).slice();
+    delete copy[Number(last)];
+    const holder = walkToParent(root, segments.slice(0, -1), false);
+    holder[segments[segments.length - 2]!] = copy;
+    return;
+  }
   delete parent[last];
 }
 

package/src/utils/stable-key.ts

@@ -55,7 +55,8 @@ function keyOf(val: unknown, ancestors: object[]): string {
   try {
     if (Array.isArray(val)) {
       // Array.from reads a hole as undefined (map would skip it, giving
-      // `[,]` the key of `[]`), matching deepClone, which fills holes.
+      // `[,]` the key of `[]`): as JSON.stringify, a key does not tell a
+      // hole from an undefined element (deepEqual does)
       return `[${Array.from(val, (v) => keyOf(v, ancestors)).join(',')}]`;
     }
     if (val instanceof Map) {

package/src/utils/value-kinds.ts

@@ -0,0 +1,45 @@
+// Kinds of story values that structural operations (clone, equality, merge)
+// and property paths treat as a whole, by their content.
+
+export const toStringTag = (value: object): string =>
+  Object.prototype.toString.call(value).slice(8, -1);
+
+/** Temporal values are immutable: copies may share them. */
+export const isTemporal = (value: object): boolean =>
+  toStringTag(value).startsWith('Temporal.');
+
+/** new Number(), new String(), new Boolean(), Object(1n). */
+export const isBoxed = (value: object): boolean =>
+  value instanceof Number ||
+  value instanceof String ||
+  value instanceof Boolean ||
+  toStringTag(value) === 'BigInt';
+
+/**
+ * Values compared and copied as a whole, by their content: they have no
+ * own keys to merge by, or their keys are not the data (a property written
+ * into one would be dropped by clones and saves, and by Immer for Map and
+ * Set).
+ */
+export function isAtomic(value: object): boolean {
+  return (
+    value instanceof Date ||
+    value instanceof RegExp ||
+    value instanceof Map ||
+    value instanceof Set ||
+    ArrayBuffer.isView(value) ||
+    value instanceof ArrayBuffer ||
+    value instanceof URL ||
+    value instanceof URLSearchParams ||
+    value instanceof Error ||
+    isBoxed(value) ||
+    isTemporal(value)
+  );
+}
+
+/** "a Map", "an Error", ... for an atomic value (see isAtomic), else undefined. */
+export function atomicName(value: object): string | undefined {
+  if (!isAtomic(value)) return undefined;
+  const tag = value instanceof Error ? 'Error' : toStringTag(value);
+  return `${/^[AEIOU]/.test(tag) ? 'an' : 'a'} ${tag}`;
+}

package/types/index.d.ts

@@ -575,7 +575,18 @@ export interface SaveMeta {
  */
 export interface SaveRecord {
   meta: SaveMeta;
-  payload: SavePayload;
+  /** The payload as stored: serialized in one piece, with its format version. */
+  payload: EncodedPayload;
+}
+
+/**
+ * A save payload as stored. `data` is opaque serialized text; read it with
+ * the Story API (loading a save), not directly.
+ */
+export interface EncodedPayload {
+  /** The save format version `data` was written in. */
+  formatVersion: number;
+  data: string;
 }
 
 /**
@@ -584,7 +595,8 @@ export interface SaveRecord {
  * @see {@link ../../src/saves/types.ts} for the implementation.
  */
 export interface SaveExport {
-  version: 1;
+  /** The save format version of the export. */
+  formatVersion: number;
   /** IFID of the story the save belongs to. Imports into other stories are rejected. */
   ifid: string;
   /** ISO 8601 timestamp of the export. */
@@ -614,13 +626,18 @@ export interface StoryAPI {
   set(name: string, value: unknown): void;
   set(vars: Record<string, unknown>): void;
 
-  /** Navigate to a passage by name. */
+  /**
+   * Navigate to a passage by name. Writes the session: if the variables hold
+   * a value a save cannot hold (a function, an instance of an unregistered
+   * class, a unique symbol), the navigation completes and then throws an
+   * error naming the variable.
+   */
   goto(passageName: string): void;
 
-  /** Go back one step in history. */
+  /** Go back one step in history. Throws like `goto()`. */
   back(): void;
 
-  /** Go forward one step in history. */
+  /** Go forward one step in history. Throws like `goto()`. */
   forward(): void;
 
   /** Restart the story from the beginning. */
@@ -629,7 +646,9 @@ export interface StoryAPI {
   /**
    * Save the current state. Pass `slot` for a named save, `custom` for metadata.
    * Resolves once the save is persisted (after `aftersave` handlers ran and
-   * `hasSave(slot)` is true); rejects if persisting fails.
+   * `hasSave(slot)` is true); rejects if persisting fails, or if the state
+   * holds a value a save cannot hold (a function, an instance of an
+   * unregistered class, a unique symbol, a symbol key), naming it.
    */
   save(slot?: string, custom?: Record<string, unknown>): Promise<void>;
 
@@ -638,7 +657,8 @@ export interface StoryAPI {
    * playthrough, in call order: a save issued after the load belongs to it.
    * Resolves once the loaded state is applied (immediately if the slot is
    * empty, without loading if a restart was issued after the load); rejects
-   * if loading fails.
+   * if loading fails, e.g. for a save holding an instance of a class that is
+   * not registered, or one from an incompatible save format version.
    */
   load(slot?: string): Promise<void>;
 
@@ -744,7 +764,11 @@ export interface StoryAPI {
   /** Check whether any dialog is currently open. */
   isDialogOpen(): boolean;
 
-  /** Register a class constructor for use in story expressions. */
+  /**
+   * Register a class so its instances keep their class through clones,
+   * history, saves and loads. A save refuses instances of classes that are
+   * not registered.
+   */
   registerClass(name: string, ctor: new (...args: any[]) => any): void;
 
   /** Register a custom macro. */