@rohal12/spindle 0.59.14 → 0.59.16

package/src/utils/control-edits.ts

@@ -1,48 +1,99 @@
+import { createContext } from 'preact';
+import { readState } from '../execute-mutation';
+import { diffPaths } from '../structural';
 import { getByPath } from './object-path';
+import type { VariableNamespaces } from '../store';
 
 /**
- * Records the edits a reader made through a control bound to a story
- * variable (`{textbox}`, `{checkbox}`, ...). {for} tells these apart from a
- * list that is replaced: typing into a control inside an iteration changes
- * its item, but must not remount the iteration and drop the control's focus.
+ * Records the edits made to the items of a list from inside a {for}
+ * iteration, which {for} tells apart from a list that is replaced:
+ *
+ * - a reader editing a variable through a control (`{textbox}`,
+ *   `{checkbox}`, ...): typing into a control inside an iteration changes
+ *   its item, but must not remount the iteration and drop the control's
+ *   focus (#369);
+ * - mutation code an iteration runs as it renders (`{set $party[@i].hp +=
+ *   1}`): remounting would run the iteration's mount-only macros, and so the
+ *   write, again for every write it makes (#400).
+ *
  * An edit is attributed to the variable path it wrote, so a replacement made
- * elsewhere (a watcher reacting to the edit) still remounts.
+ * elsewhere (a watcher reacting to the edit, a button outside the loop)
+ * still remounts.
  */
 let version = 0;
-const MAX_LOG = 256;
-const log: { version: number; segments: readonly string[] }[] = [];
+const MAX_LOG = 4096;
+/** Edits in the order made: paths below the namespaces (`['variables', 'a']`). */
+const log: { version: number; path: readonly string[] }[] = [];
 
-export function noteControlEdit(segments: readonly string[]): void {
-  log.push({ version: ++version, segments });
+function note(path: readonly string[]): void {
+  log.push({ version: ++version, path });
   if (log.length > MAX_LOG) log.shift();
 }
 
+/** Note an edit a control made to the story variable at `segments`. */
+export function noteControlEdit(segments: readonly string[]): void {
+  note(['variables', ...segments]);
+}
+
+/**
+ * Whether mutation code runs inside a {for} iteration: {for} provides true
+ * around its iterations, and the writes of such code are noted as edits of
+ * the items they reach (see runAsItemEdit).
+ */
+export const ItemEditContext = createContext(false);
+
+const NAMESPACES = ['variables', 'temporary', 'transient'] as const;
+
+/** Run `run`, noting each variable path it changes as an edit. */
+export function runAsItemEdit(run: () => void): void {
+  const before = readState();
+  try {
+    run();
+  } finally {
+    const after = readState();
+    for (const ns of NAMESPACES) {
+      if (before[ns] === after[ns]) continue;
+      for (const { path } of diffPaths(before[ns], after[ns], true)) {
+        note([ns, ...path]);
+      }
+    }
+  }
+}
+
 export function controlEditVersion(): number {
   return version;
 }
 
 /**
- * Whether an edit since `since` wrote inside `item`, element `index` of
- * `list`: the path leads through the item (compared by reference in
- * `variables`), or, for a primitive item, ends at its slot in the list.
+ * A test of whether an edit made since `since` wrote inside `item`, element
+ * `index` of `list`: the path leads through the item (compared by reference
+ * in `state`), or, for a primitive item, ends at its slot in the list.
  */
-export function editedItem(
+export function editedItems(
   since: number,
-  variables: object,
-  list: readonly unknown[],
-  item: unknown,
-  index: number,
-): boolean {
-  return log.some(({ version: v, segments }) => {
-    if (v <= since) return false;
-    if (typeof item === 'object' && item !== null) {
-      return segments.some(
-        (_, n) => getByPath(variables, segments.slice(0, n + 1)) === item,
-      );
-    }
-    return (
-      segments[segments.length - 1] === String(index) &&
-      getByPath(variables, segments.slice(0, -1)) === list
-    );
-  });
+  state: VariableNamespaces,
+): (list: readonly unknown[], item: unknown, index: number) => boolean {
+  // The objects the paths lead through, and the keys they end at
+  const through = new Set<unknown>();
+  const ends = new Map<unknown, Set<string>>();
+  for (let i = log.length - 1; i >= 0 && log[i]!.version > since; i--) {
+    const { path } = log[i]!;
+    let node: unknown = state;
+    path.forEach((seg, n) => {
+      if (n === path.length - 1 && node !== null && typeof node === 'object') {
+        const keys = ends.get(node) ?? new Set<string>();
+        keys.add(seg);
+        ends.set(node, keys);
+      }
+      node =
+        node !== null && typeof node === 'object'
+          ? getByPath(node, [seg])
+          : undefined;
+      if (node !== null && typeof node === 'object') through.add(node);
+    });
+  }
+  return (list, item, index) =>
+    typeof item === 'object' && item !== null
+      ? through.has(item)
+      : ends.get(list)?.has(String(index)) === true;
 }

package/src/utils/listeners.ts

@@ -0,0 +1,23 @@
+/**
+ * A set of listeners to call when something happens: `subscribe` adds one and
+ * returns the function that removes it, `notify` calls each one. A listener
+ * removed or added while they are called is called or not as the set was
+ * when `notify` started.
+ */
+export function createListeners(): {
+  subscribe: (listener: () => void) => () => void;
+  notify: () => void;
+} {
+  const listeners = new Set<() => void>();
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    notify() {
+      for (const listener of [...listeners]) listener();
+    },
+  };
+}

package/src/utils/object-path.ts

@@ -1,4 +1,5 @@
 import { current as draftState, isDraft } from 'immer';
+import { registeredClassName } from '../class-registry';
 import { hasOwn } from './namespace';
 import { atomicName } from './value-kinds';
 
@@ -74,10 +75,12 @@ export interface SetByPathOptions {
  * written in place.
  *
  * The path goes through own properties of plain objects, class instances
- * and arrays (by index); anything else throws a TypeError rather than
- * writing where no clone or save would see it: an inherited property such
- * as a method counts as missing, and Map, Set, Date and RegExp values and
- * other keys of arrays are refused, as is a "__proto__" segment.
+ * and arrays (by index), and, outside a draft, any key of an instance of a
+ * registered subclass of a built-in (#408); anything else throws a
+ * TypeError rather than writing where no clone or save would see it: an
+ * inherited property such as a method counts as missing, and Map, Set,
+ * Date and RegExp values and other keys of arrays are refused, as is a
+ * "__proto__" segment.
  */
 export function setByPath(
   root: Record<string, unknown>,
@@ -134,13 +137,21 @@ function checkSegments(segments: readonly string[]): void {
   }
 }
 
-/** Throw unless `holder` can take `key` as story state (see setByPath). */
+/**
+ * Throw unless `holder` can take `key` as story state (see setByPath). An
+ * instance of a registered subclass of a built-in keeps its own fields
+ * through clones and saves, so it takes any key (#408) when written in
+ * place: a draft of one, or one a draft shares, is refused as other
+ * built-ins are, and the caller writes the whole value instead.
+ */
 function checkHolder(
   holder: object,
   key: string,
   segments: readonly string[],
   depth: number,
+  inPlace: boolean,
 ): void {
+  if (inPlace && registeredClassName(holder) !== undefined) return;
   const builtin = builtinName(holder);
   const kind =
     builtin ?? (Array.isArray(holder) && !isArrayKey(key) ? 'an array' : '');
@@ -167,7 +178,7 @@ function walkToParent(
   let current: Record<string, unknown> = root;
   for (let i = 0; i < segments.length - 1; i++) {
     const seg = segments[i]!;
-    checkHolder(current, seg, segments, i);
+    checkHolder(current, seg, segments, i, !copyOnWrite);
     // An inherited property (a method, "constructor") counts as missing
     let next = hasOwn(current, seg) ? current[seg] : undefined;
     if (next == null || typeof next !== 'object') {
@@ -189,6 +200,7 @@ function walkToParent(
     segments[segments.length - 1]!,
     segments,
     segments.length - 1,
+    !copyOnWrite,
   );
   return current;
 }

package/src/utils/stable-key.ts

@@ -1,27 +1,37 @@
 import { registeredClassName } from '../class-registry';
+import { extraKeys, mapEntries, setMembers } from './value-kinds';
 
 /**
  * Content-derived string key for a value, used to remount components when
  * the value's contents change (e.g. {for} iterations, #45).
  *
- * JSON-compatible values (strings, finite numbers, booleans, null, arrays and
- * plain objects of those) produce exactly their `JSON.stringify` output. Other
- * values get distinct, unambiguous markers so their contents are reflected
- * too: Map and Set entries (nested at any depth), Date, RegExp, BigInt,
- * undefined, NaN/±Infinity, symbols (by description), functions (by name)
- * and registered class instances. A hole in an array reads as undefined.
- * Cyclic references become a back-reference marker instead of throwing,
- * and the function never throws.
+ * A tree of JSON-compatible values (strings, finite numbers, booleans, null,
+ * arrays and plain objects of those) produces exactly its `JSON.stringify`
+ * output. Other values get distinct, unambiguous markers so their contents
+ * are reflected too: Map and Set entries (nested at any depth), Date,
+ * RegExp, BigInt, undefined, NaN/±Infinity, symbols (by description),
+ * functions (by name) and registered class instances, with the class name
+ * and, for a subclass of a built-in, its own fields (#407). A hole in an
+ * array reads as undefined.
+ *
+ * An object met again, through a cycle or a second reference to it, is a
+ * marker naming where it was first met rather than another copy of its
+ * contents, so the key grows with the objects a value holds, not with the
+ * paths to them (#406). The function never throws.
  */
 export function stableKey(value: unknown): string {
   try {
-    return keyOf(value, []);
+    return keyOf(value, new Map());
   } catch {
     return '<unkeyable>';
   }
 }
 
-function keyOf(val: unknown, ancestors: object[]): string {
+/**
+ * The key of `val`. `seen` numbers the objects keyed so far, in the order
+ * they were first met.
+ */
+function keyOf(val: unknown, seen: Map<object, number>): string {
   switch (typeof val) {
     case 'string':
       return JSON.stringify(val);
@@ -45,39 +55,62 @@ function keyOf(val: unknown, ancestors: object[]): string {
   if (val === null) return 'null';
 
   const obj = val as object;
-  const depth = ancestors.indexOf(obj);
-  if (depth !== -1) return `<cycle ${ancestors.length - depth}>`;
+  const first = seen.get(obj);
+  if (first !== undefined) return `<ref ${first}>`;
 
-  if (val instanceof Date) return `Date(${val.getTime()})`;
-  if (val instanceof RegExp) return `RegExp(${String(val)}@${val.lastIndex})`;
+  const className = registeredClassName(obj);
+  const named = (key: string) =>
+    className === undefined ? key : `Class(${JSON.stringify(className)})${key}`;
+  // The own fields of a registered subclass of a built-in, which clones and
+  // saves keep with its contents
+  const withFields = (key: string) => {
+    const keys = className === undefined ? [] : extraKeys(obj);
+    return named(keys.length ? `${key}${fieldsOf(obj, keys, seen)}` : key);
+  };
 
-  ancestors.push(obj);
-  try {
-    if (Array.isArray(val)) {
-      // Array.from reads a hole as undefined (map would skip it, giving
-      // `[,]` 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) {
-      const entries = [...val].map(
-        ([k, v]) => `[${keyOf(k, ancestors)},${keyOf(v, ancestors)}]`,
-      );
-      return `Map[${entries.join(',')}]`;
-    }
-    if (val instanceof Set) {
-      return `Set[${[...val].map((v) => keyOf(v, ancestors)).join(',')}]`;
+  // Read with the built-in methods: a subclass may override them. A Date or
+  // RegExp holds no other value, so it needs no number unless it has fields.
+  if (val instanceof Date || val instanceof RegExp) {
+    if (className !== undefined && extraKeys(obj).length) {
+      seen.set(obj, seen.size);
     }
+    return withFields(
+      val instanceof Date
+        ? `Date(${Date.prototype.getTime.call(val)})`
+        : `RegExp(${RegExp.prototype.toString.call(val)}@${val.lastIndex})`,
+    );
+  }
 
-    const record = obj as Record<string, unknown>;
-    const body = Object.keys(record)
-      .map((k) => `${JSON.stringify(k)}:${keyOf(record[k], ancestors)}`)
-      .join(',');
-    const className = registeredClassName(obj);
-    return className === undefined
-      ? `{${body}}`
-      : `Class(${JSON.stringify(className)}){${body}}`;
-  } finally {
-    ancestors.pop();
+  seen.set(obj, seen.size);
+  if (Array.isArray(val)) {
+    // Array.from reads a hole as undefined (map would skip it, giving
+    // `[,]` the key of `[]`): as JSON.stringify, a key does not tell a
+    // hole from an undefined element (deepEqual does)
+    return withFields(`[${Array.from(val, (v) => keyOf(v, seen)).join(',')}]`);
+  }
+  if (val instanceof Map) {
+    const entries = Array.from(
+      mapEntries(val),
+      ([k, v]) => `[${keyOf(k, seen)},${keyOf(v, seen)}]`,
+    );
+    return withFields(`Map[${entries.join(',')}]`);
+  }
+  if (val instanceof Set) {
+    const members = Array.from(setMembers(val), (v) => keyOf(v, seen));
+    return withFields(`Set[${members.join(',')}]`);
   }
+  return named(fieldsOf(obj, Object.keys(obj), seen));
+}
+
+/** `{"key":value,...}` for the `keys` of `obj`. */
+function fieldsOf(
+  obj: object,
+  keys: readonly string[],
+  seen: Map<object, number>,
+): string {
+  const record = obj as Record<string, unknown>;
+  const body = keys.map(
+    (k) => `${JSON.stringify(k)}:${keyOf(record[k], seen)}`,
+  );
+  return `{${body.join(',')}}`;
 }

package/src/utils/value-kinds.ts

@@ -1,6 +1,8 @@
 // Kinds of story values that structural operations (clone, equality, merge)
 // and property paths treat as a whole, by their content.
 
+import { isDraft } from 'immer';
+
 export const toStringTag = (value: object): string =>
   Object.prototype.toString.call(value).slice(8, -1);
 
@@ -57,3 +59,43 @@ export function extraKeys(collection: object): string[] {
   const keys = Object.keys(collection);
   return Array.isArray(collection) ? keys.filter((k) => !isIndexKey(k)) : keys;
 }
+
+// A subclass of Map or Set may override how it is iterated, read or written
+// (an inventory that iterates only the items on hand). What it holds is in
+// its built-in slots, so structural operations read and write those with the
+// built-in methods (#391, #394). An Immer draft keeps its entries in its own
+// state instead, so it is read through its methods.
+
+/** The entries of a Map, as the built-in iterator gives them. */
+export function mapEntries<K, V>(map: Map<K, V>): MapIterator<[K, V]> {
+  return isDraft(map)
+    ? map.entries()
+    : (Map.prototype.entries.call(map) as MapIterator<[K, V]>);
+}
+
+/** The members of a Set, as the built-in iterator gives them. */
+export function setMembers<T>(set: Set<T>): SetIterator<T> {
+  return isDraft(set)
+    ? set.values()
+    : (Set.prototype.values.call(set) as SetIterator<T>);
+}
+
+/** The number of entries of a Map or members of a Set. */
+export function collectionSize(
+  collection: Map<unknown, unknown> | Set<unknown>,
+) {
+  if (isDraft(collection)) return collection.size;
+  const proto = collection instanceof Map ? Map.prototype : Set.prototype;
+  return Reflect.get(proto, 'size', collection) as number;
+}
+
+/** The value a Map holds for `key`. */
+export function mapGet<K, V>(map: Map<K, V>, key: K): V | undefined {
+  return isDraft(map) ? map.get(key) : Map.prototype.get.call(map, key);
+}
+
+/** Make a Map hold `value` for `key`. */
+export function mapSet<K, V>(map: Map<K, V>, key: K, value: V): void {
+  if (isDraft(map)) map.set(key, value);
+  else Map.prototype.set.call(map, key, value);
+}

package/types/index.d.ts

@@ -794,7 +794,9 @@ export interface StoryAPI {
   /**
    * 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.
+   * not registered. A class may extend Array, Map, Set, Date, RegExp or
+   * Error; one extending another built-in whose value a save cannot hold (a
+   * typed array, URL, Promise...) throws.
    */
   registerClass(name: string, ctor: new (...args: any[]) => any): void;
 
@@ -864,7 +866,10 @@ export interface StoryAPI {
   /** Set a one-time transition for the next navigation only. Pass `null` to clear. */
   setNextTransition(config: TransitionConfig | null): void;
 
-  /** Defer initial passage rendering until `ready()` is called. */
+  /**
+   * Defer initial passage rendering until `ready()` is called. Calling it
+   * again before `ready()` keeps the one deferral: a single `ready()` ends it.
+   */
   deferRender(): void;
 
   /** Unblock deferred rendering (call after `deferRender()`). */

package/types/tooling.d.ts

@@ -111,7 +111,11 @@ export type VarType =
 /** Inferred shape of a declared variable (or one of its object fields). */
 export interface FieldSchema {
   type: VarType;
-  /** Field schemas, only present for objects. */
+  /**
+   * Field schemas, only present for objects. An object the default refers
+   * to more than once has one schema, so a cyclic default (`node.self =
+   * node`) gives a schema that refers to itself.
+   */
   fields?: Map<string, FieldSchema>;
 }