@rohal12/spindle 0.51.3 → 0.51.4

package/src/execute-mutation.ts

@@ -1,27 +1,287 @@
+import { current as currentDraft, freeze, isDraft } from 'immer';
 import { useStoryStore } from './store';
+import type { VariableNamespaces } from './store';
 import { execute } from './expression';
 import { deepClone, deepEqual } from './class-registry';
+import { deleteByPath, getByPath, setByPath } from './utils/object-path';
+
+type NamespaceName = keyof VariableNamespaces;
+
+const NAMESPACES: readonly NamespaceName[] = [
+  'variables',
+  'temporary',
+  '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
+ * execution (Story.set, the commits of nested mutations) applied to both,
+ * so diffing `work` against `base` yields exactly the code's own changes,
+ * and a write made elsewhere after the code's own write to the same path
+ * leaves no difference there: the later write wins.
+ */
+interface MutationScope {
+  work: VariableNamespaces;
+  base: VariableNamespaces;
+}
+
+/** The mutations now executing, innermost last. */
+const activeScopes: MutationScope[] = [];
+
+/**
+ * The working copies of the store namespaces that the innermost executing
+ * mutation reads and writes, or undefined outside of one. Story.get reads
+ * them so the code sees its own pending writes.
+ */
+export function getActiveMutationScope(): VariableNamespaces | undefined {
+  return activeScopes[activeScopes.length - 1]?.work;
+}
+
+const cloneValue = <T>(value: T): T =>
+  deepClone(value, { keepUnregistered: true });
+
+/**
+ * A frozen copy of a value read from a working copy, matching what reads
+ * from the (frozen) store return: writing to it fails instead of changing
+ * the code's pending state behind its back.
+ */
+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).
+ */
+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 (
+      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);
+}
 
 /**
- * Write the keys `code` changed (`clone` vs the pre-execution `before`) into
- * an Immer draft of the same namespace, and delete the keys it removed.
- * Untouched keys are left alone, so updates made during execution survive.
+ * Apply a write that reached the store while mutations execute to their
+ * `work` and `base` copies (see MutationScope), so the code sees it and
+ * its commit neither drops it nor reverts it. Called from inside the store
+ * update that makes the write, before subscribers (watchers) run, so writes
+ * those make land in the copies after this one. When a copy cannot take the
+ * path (the code replaced or deleted an intermediate object), its root is
+ * replaced with the store's root as written.
  */
-function commitNamespace(
-  draft: Record<string, unknown>,
-  clone: Record<string, unknown>,
-  before: Record<string, unknown>,
+function mirror(
+  draft: VariableNamespaces,
+  ns: NamespaceName,
+  change: PathChange,
+  scopes: readonly MutationScope[] = activeScopes,
 ): void {
-  for (const key of Object.keys(clone)) {
-    if (!deepEqual(clone[key], before[key])) {
-      draft[key] = clone[key];
+  const root = change.path[0]!;
+  for (const scope of scopes) {
+    for (const copy of [scope.work[ns], scope.base[ns]]) {
+      try {
+        applyChange(
+          copy,
+          change.deleted
+            ? change
+            : { ...change, value: cloneValue(change.value) },
+        );
+      } catch {
+        const stored = draft[ns][root];
+        if (hasOwn(draft[ns], root)) {
+          copy[root] = cloneValue(
+            isDraft(stored) ? currentDraft(stored) : stored,
+          );
+        } else {
+          delete copy[root];
+        }
+      }
     }
   }
-  for (const key of Object.keys(before)) {
-    if (!(key in clone)) {
-      delete draft[key];
+}
+
+/**
+ * Mirror a Story.set write into every executing mutation (see mirror()).
+ * Call it inside the store update that writes `value` at `path` of `ns`.
+ */
+export function mirrorWriteToActiveScopes(
+  draft: VariableNamespaces,
+  ns: 'variables' | 'transient',
+  path: string[],
+  value: unknown,
+): void {
+  if (activeScopes.length === 0) return;
+  mirror(draft, ns, { path, deleted: false, value });
+}
+
+const cloneNamespaces = (from: VariableNamespaces): VariableNamespaces => ({
+  variables: deepClone(from.variables),
+  temporary: deepClone(from.temporary),
+  transient: deepClone(from.transient),
+});
+
+/**
+ * Commit the property paths `scope`'s code changed (work vs base) on top of
+ * the current store state, so writes made elsewhere during execution to
+ * other paths of the same objects survive, and hand them to the `enclosing`
+ * mutations. With `keepRunning`, the code goes on running after the commit:
+ * its working copy must stay its own (the store freezes what it is given),
+ * and its base is moved up to the working copy so nothing commits twice.
+ */
+function commitScope(
+  scope: MutationScope,
+  enclosing: readonly MutationScope[],
+  keepRunning: boolean,
+): void {
+  const changes = NAMESPACES.map((ns) => {
+    const list: PathChange[] = [];
+    diff(scope.base[ns], scope.work[ns], [], list, new Set());
+    return [ns, list] as const;
+  });
+  if (changes.every(([, list]) => list.length === 0)) return;
+  // Before the store update: watchers it fires may commit again (a goto)
+  if (keepRunning) scope.base = cloneNamespaces(scope.work);
+  const own = <T>(value: T): T => (keepRunning ? cloneValue(value) : value);
+  const current = useStoryStore.getState();
+
+  // One store update for everything: watchers must see the whole mutation,
+  // and a watcher's run action must not be overwritten by paths this commit
+  // writes after it fired.
+  current.updateVariables((draft) => {
+    for (const [ns, list] of changes) {
+      const replaced = new Set<string>();
+      for (const change of list) {
+        const root = change.path[0]!;
+        // A changed path already holding the value keeps its reference
+        if (replaced.has(root) || isApplied(current[ns], change)) continue;
+        try {
+          applyChange(
+            draft[ns],
+            change.deleted ? change : { ...change, value: own(change.value) },
+          );
+        } catch {
+          // An intermediate object the code wrote into is gone from the
+          // store: the code's view of the whole root wins.
+          draft[ns][root] = own(scope.work[ns][root]);
+          replaced.add(root);
+        }
+      }
+      // Hand the changes to the mutations this one runs inside, before
+      // watchers fired by this update run.
+      for (const change of list) mirror(draft, ns, change, enclosing);
+    }
+  });
+}
+
+/**
+ * Bring a suspended mutation's copies up to the store after an action
+ * replaced or changed state under it (navigation clears temporaries, back
+ * and restart replace variables). Roots that still match keep the objects
+ * the code may hold.
+ */
+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]);
+      }
     }
   }
+  scope.base = cloneNamespaces(state);
+}
+
+/**
+ * Run an action that snapshots or replaces story state (saving, navigating,
+ * restarting) in program order with mutation code running now: the code's
+ * writes so far are committed first, the action runs against the store with
+ * no mutation active, and the code then continues from the resulting state.
+ * Outside mutation code the action just runs.
+ */
+export function runWithCommittedMutations<T>(action: () => T): T {
+  if (activeScopes.length === 0) return action();
+  const scopes = [...activeScopes];
+  // Innermost first: each commit hands its changes to the enclosing ones
+  for (let i = scopes.length - 1; i >= 0; i--) {
+    commitScope(scopes[i]!, scopes.slice(0, i), true);
+  }
+  const suspended = activeScopes.splice(0);
+  try {
+    return action();
+  } finally {
+    activeScopes.push(...suspended);
+    for (const scope of suspended) resync(scope);
+  }
 }
 
 export function executeMutation(
@@ -29,10 +289,14 @@ export function executeMutation(
   mergedLocals: Record<string, unknown>,
   scopeUpdate: (key: string, value: unknown) => void,
 ): void {
-  const state = useStoryStore.getState();
-  const vars = deepClone(state.variables);
-  const temps = deepClone(state.temporary);
-  const trans = deepClone(state.transient);
+  // A mutation started while another executes (a watcher run action fired
+  // by a Story.set in its code) continues from the enclosing code's pending
+  // state rather than the store, as a direct call at that point would.
+  const start = getActiveMutationScope() ?? useStoryStore.getState();
+  const scope: MutationScope = {
+    work: cloneNamespaces(start),
+    base: cloneNamespaces(start),
+  };
   // Locals are deep-cloned like the store namespaces: a loop item or widget
   // argument taken from story state is Immer-frozen, and an unfrozen object
   // mutated in place would keep its reference, so a nested assignment
@@ -40,16 +304,20 @@ export function executeMutation(
   // Unregistered class instances (DOM nodes etc.) stay shared by reference.
   const localsClone = deepClone(mergedLocals, { keepUnregistered: true });
 
-  execute(code, vars, temps, localsClone, trans);
+  activeScopes.push(scope);
+  try {
+    execute(
+      code,
+      scope.work.variables,
+      scope.work.temporary,
+      localsClone,
+      scope.work.transient,
+    );
+  } finally {
+    activeScopes.pop();
+  }
 
-  // Commit every store change in one update: watchers must see the whole
-  // mutation, and a watcher's run action must not be overwritten by keys
-  // this commit writes after it fired.
-  state.updateVariables((draft) => {
-    commitNamespace(draft.variables, vars, state.variables);
-    commitNamespace(draft.temporary, temps, state.temporary);
-    commitNamespace(draft.transient, trans, state.transient);
-  });
+  commitScope(scope, activeScopes, false);
 
   for (const key of Object.keys(localsClone)) {
     if (!deepEqual(localsClone[key], mergedLocals[key])) {

package/src/expression.ts

@@ -2,6 +2,7 @@ import type { StoryState } from './store';
 import { useStoryStore } from './store';
 import type { Passage } from './parser';
 import { random, randomInt } from './prng';
+import { lexJs } from './js-lexer';
 
 interface ExpressionFns {
   currentPassage: () => Passage | undefined;
@@ -31,39 +32,15 @@ const fnCache = new Map<string, CompiledExpression>();
 
 /**
  * Transform expression: $var → variables["var"], _var → temporary["var"],
- * @var → locals["var"]
- * Only transforms when sigils appear as a word boundary (not inside strings naively,
- * but authors already have full JS access so this is acceptable).
- * `%var` → transient["var"] is handled by `transform` itself, because `%` is
- * also the modulo operator and only an operand position makes it a sigil.
+ * @var → locals["var"], %var → transient["var"].
+ * Only transforms when sigils appear as a word boundary, and only in code:
+ * string, template and regex literal text and comments are left untouched.
+ * `%var` is recognised by the lexer (`lexJs`), because `%` is also the modulo
+ * operator and only an operand position makes it a sigil.
  */
 const VAR_RE = /\$(\w+)/g;
 const TEMP_RE = /(?<![.\w])_(\w+)/g;
 const LOCAL_RE = /@(\w+)/g;
-/** Transient name after `%`: an identifier, so `%3` is never a reference. */
-const TRANS_NAME_RE = /[A-Za-z_]\w*/y;
-/** Characters of identifiers, numbers and sigil variable references. */
-const WORD_CHAR_RE = /[\w$@]/;
-const SPACE_RE = /\s/;
-/** Keywords followed by an operand rather than an operator. */
-const OPERAND_KEYWORDS = new Set([
-  'await',
-  'case',
-  'delete',
-  'do',
-  'else',
-  'in',
-  'instanceof',
-  'new',
-  'of',
-  'return',
-  'throw',
-  'typeof',
-  'void',
-  'yield',
-]);
-/** Keywords whose parenthesised header is followed by a statement. */
-const HEADER_KEYWORDS = new Set(['for', 'if', 'while', 'with']);
 
 function transformSegment(segment: string): string {
   return segment
@@ -73,26 +50,13 @@ function transformSegment(segment: string): string {
 }
 
 /**
- * String-aware expression transformer. Walks the expression character by
- * character so that variable sigils ($, _, @, %) inside string literals are
- * left untouched while code — including expressions inside template-literal
- * `${…}` interpolations — is transformed.
- *
- * It also tracks whether the next token is an operand or an operator, so that
- * `%name` in operand position is a transient reference while `%` after an
- * operand — `($n)%3`, `$a[i] %2`, `$a%$b` — stays the modulo operator.
+ * Rewrite sigil references in `expr`. The lexer passes literal text and
+ * comments through untouched; each run of code between them (including the
+ * code of template-literal `${…}` interpolations) is transformed as a whole.
  */
 function transform(expr: string): string {
   let result = '';
   let code = ''; // accumulates code characters to be transformed
-  let i = 0;
-
-  let operandNext = true; // an operand (not an operator) comes next
-  let word = ''; // identifier/number currently being read
-  let afterDot = false; // `word` is a property name, never a keyword
-  let afterHeaderKeyword = false; // last token was if/while/for/with
-  let lastPunct = '';
-  const parenIsHeader: boolean[] = []; // per open `(`: closes a header?
 
   function flushCode() {
     if (code) {
@@ -101,199 +65,19 @@ function transform(expr: string): string {
     }
   }
 
-  function endWord() {
-    if (!word) return;
-    operandNext = !afterDot && OPERAND_KEYWORDS.has(word);
-    afterHeaderKeyword = !afterDot && HEADER_KEYWORDS.has(word);
-    afterDot = false;
-    lastPunct = '';
-    word = '';
-  }
-
-  /** A string or template literal, or a transient reference, just ended. */
-  function endOperand() {
-    endWord();
-    operandNext = false;
-    afterHeaderKeyword = false;
-    afterDot = false;
-    lastPunct = '';
-  }
-
-  function trackCode(c: string) {
-    if (WORD_CHAR_RE.test(c)) {
-      word += c;
-      return;
-    }
-    endWord();
-    // A line may start a new statement such as `%x = 1`.
-    if (c === '\n') operandNext = true;
-    if (SPACE_RE.test(c)) return;
-    if (c === '(') parenIsHeader.push(afterHeaderKeyword);
-    if (c === ')') {
-      // `if (…) %x = 1` vs `($n)%3`
-      operandNext = parenIsHeader.pop() ?? false;
-    } else if (c === '.') {
-      // Property access, unless it is the spread `...`
-      operandNext = lastPunct === '.';
-    } else {
-      // `]` ends an operand; `}` closes a block, so a statement may follow.
-      operandNext = c !== ']';
-    }
-    afterDot = c === '.';
-    afterHeaderKeyword = false;
-    lastPunct = c;
-  }
-
-  while (i < expr.length) {
-    const ch = expr.charAt(i);
-
-    // Single or double quoted string — skip entirely
-    if (ch === '"' || ch === "'") {
+  lexJs(expr, {
+    code(ch) {
+      code += ch;
+    },
+    literal(text) {
       flushCode();
-      const quote = ch;
-      let str = quote;
-      i++;
-      while (i < expr.length) {
-        const c = expr.charAt(i);
-        if (c === '\\' && i + 1 < expr.length) {
-          str += c + expr.charAt(i + 1);
-          i += 2;
-        } else if (c === quote) {
-          str += quote;
-          i++;
-          break;
-        } else {
-          str += c;
-          i++;
-        }
-      }
-      result += str;
-      endOperand();
-      continue;
-    }
-
-    // Template literal — preserve literal parts, transform interpolations
-    if (ch === '`') {
+      result += text;
+    },
+    transient(name) {
       flushCode();
-      result += '`';
-      i++;
-      while (i < expr.length) {
-        const c = expr.charAt(i);
-        if (c === '\\' && i + 1 < expr.length) {
-          result += c + expr.charAt(i + 1);
-          i += 2;
-        } else if (c === '$' && expr.charAt(i + 1) === '{') {
-          // Template interpolation — collect the inner expression and
-          // recursively transform it
-          result += '${';
-          i += 2;
-          let depth = 1;
-          let inner = '';
-          while (i < expr.length && depth > 0) {
-            const ic = expr.charAt(i);
-            if (ic === '{') {
-              depth++;
-              inner += ic;
-            } else if (ic === '}') {
-              depth--;
-              if (depth === 0) break;
-              inner += ic;
-            } else if (ic === '\\' && i + 1 < expr.length) {
-              inner += ic + expr.charAt(i + 1);
-              i++;
-            } else if (ic === '"' || ic === "'") {
-              // Skip quoted strings — braces inside are not depth-relevant
-              inner += ic;
-              i++;
-              while (i < expr.length) {
-                const sc = expr.charAt(i);
-                if (sc === '\\' && i + 1 < expr.length) {
-                  inner += sc + expr.charAt(i + 1);
-                  i += 2;
-                } else if (sc === ic) {
-                  inner += sc;
-                  i++;
-                  break;
-                } else {
-                  inner += sc;
-                  i++;
-                }
-              }
-              continue; // skip the i++ at the end
-            } else if (ic === '`') {
-              // Nested template literal — consume entirely
-              inner += ic;
-              i++;
-              while (i < expr.length) {
-                const tc = expr.charAt(i);
-                if (tc === '\\' && i + 1 < expr.length) {
-                  inner += tc + expr.charAt(i + 1);
-                  i += 2;
-                } else if (tc === '$' && expr.charAt(i + 1) === '{') {
-                  // Nested interpolation — track brace depth
-                  inner += '${';
-                  i += 2;
-                  let nestedDepth = 1;
-                  while (i < expr.length && nestedDepth > 0) {
-                    const nc = expr.charAt(i);
-                    if (nc === '{') nestedDepth++;
-                    else if (nc === '}') nestedDepth--;
-                    if (nestedDepth > 0) inner += nc;
-                    i++;
-                  }
-                  inner += '}';
-                } else if (tc === '`') {
-                  inner += tc;
-                  i++;
-                  break;
-                } else {
-                  inner += tc;
-                  i++;
-                }
-              }
-              continue; // skip the i++ at the end
-            } else {
-              inner += ic;
-            }
-            i++;
-          }
-          result += transform(inner); // recursive transform
-          if (i < expr.length && expr.charAt(i) === '}') {
-            result += '}';
-            i++;
-          }
-        } else if (c === '`') {
-          result += '`';
-          i++;
-          break;
-        } else {
-          result += c;
-          i++;
-        }
-      }
-      endOperand();
-      continue;
-    }
-
-    // Transient reference — only where an operand is expected
-    if (ch === '%') {
-      endWord();
-      TRANS_NAME_RE.lastIndex = i + 1;
-      const name = operandNext ? TRANS_NAME_RE.exec(expr)?.[0] : undefined;
-      if (name) {
-        flushCode();
-        result += `transient["${name}"]`;
-        i += 1 + name.length;
-        endOperand();
-        continue;
-      }
-    }
-
-    // Regular code character
-    trackCode(ch);
-    code += ch;
-    i++;
-  }
+      result += `transient["${name}"]`;
+    },
+  });
   flushCode();
   return result;
 }
@@ -401,7 +185,8 @@ export function evaluate(
   transient: Record<string, unknown> = {},
 ): unknown {
   const transformed = transform(expr);
-  const body = `return (${transformed});`;
+  // The line break keeps a trailing `// comment` from swallowing the `)`.
+  const body = `return (${transformed}\n);`;
   const fn = getOrCompile(body, body);
   return fn(variables, temporary, locals, buildExpressionFns(), transient);
 }