@rohal12/spindle 0.51.4 → 0.52.1

package/src/story-api.ts

@@ -18,20 +18,13 @@ import type {
 import {
   setTitleGenerator,
   getStorageInfo as _getStorageInfo,
-  clearGameData as _clearGameData,
-  clearAllData as _clearAllData,
-  deletePlaythroughData,
-  populateKnownSaves,
 } from './saves/save-manager';
 import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
-import {
-  frozenCopy,
-  getActiveMutationScope,
-  mirrorWriteToActiveScopes,
-  runWithCommittedMutations,
-} from './execute-mutation';
+import { frozenCopy, getActiveMutationScope } from './execute-mutation';
 import { getByPath, setByPath } from './utils/object-path';
+import { checkVariableName } from './utils/namespace';
+import { countOf } from './utils/counts';
 import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
@@ -85,8 +78,9 @@ let variableChangedSubActive = false;
 function ensureVariableChangedSubscription(): void {
   if (variableChangedSubActive) return;
   variableChangedSubActive = true;
-  let prevVars = { ...useStoryStore.getState().variables };
-  let prevTrans = { ...useStoryStore.getState().transient };
+  // Store namespaces are immutable snapshots: keep the references
+  let prevVars = useStoryStore.getState().variables;
+  let prevTrans = useStoryStore.getState().transient;
   useStoryStore.subscribe((state) => {
     const changed: Record<string, { from: unknown; to: unknown }> = {};
     let hasChanges = false;
@@ -115,8 +109,8 @@ function ensureVariableChangedSubscription(): void {
       }
     }
 
-    prevVars = { ...state.variables };
-    prevTrans = { ...state.transient };
+    prevVars = state.variables;
+    prevTrans = state.transient;
     if (hasChanges) {
       emit('variableChanged', changed);
     }
@@ -237,15 +231,17 @@ export function _resetDeclaredVariables(): void {
 /**
  * Split an API variable name into namespace and key. Accepts the bare name
  * (`hp`), the `$` sigil authors use in passages (`$hp`), and `%` for
- * transients (`%npcs`). Dot-paths are kept in the key.
+ * transients (`%npcs`). Dot-paths are kept in the key. A variable named
+ * `__proto__` throws a TypeError (see utils/namespace.ts).
  */
 function parseName(name: string): {
   isTransient: boolean;
   key: string;
 } {
-  if (name.startsWith('%')) return { isTransient: true, key: name.slice(1) };
-  if (name.startsWith('$')) return { isTransient: false, key: name.slice(1) };
-  return { isTransient: false, key: name };
+  const isTransient = name.startsWith('%');
+  const key = isTransient || name.startsWith('$') ? name.slice(1) : name;
+  checkVariableName(key.split('.')[0]!, name);
+  return { isTransient, key };
 }
 
 function warnIfUndeclared(isTransient: boolean, key: string): void {
@@ -301,51 +297,36 @@ function createStoryAPI(): StoryAPI {
         const { isTransient, key } = parseName(name);
         warnIfUndeclared(isTransient, key);
       }
-      // One store update for all keys, so watchers see them together
+      // One store update for all keys, so watchers see them together. Made
+      // while mutation code runs ({do}, ctx.mutate, watcher run actions), it
+      // follows the code's own pending writes (program order, #215): see
+      // routeStoreUpdate.
       useStoryStore.getState().updateVariables((draft) => {
         for (const [k, v] of entries) setOne(draft, k, v);
-        // Mutation code running now ({do}, ctx.mutate, watcher run actions)
-        // works on copies of the namespaces and commits the paths it changed
-        // when it finishes. Apply the write to those copies too, so the code
-        // sees it and its commit keeps it in program order (#215). This runs
-        // inside the update, before watchers it triggers write.
-        for (const [k, v] of entries) {
-          const { isTransient, key } = parseName(k);
-          mirrorWriteToActiveScopes(
-            draft,
-            isTransient ? 'transient' : 'variables',
-            key.split('.'),
-            v,
-          );
-        }
       });
     },
 
-    // Called from running mutation code, these commit the code's writes so
-    // far before they record, replace or save state, and the code goes on
-    // from the state they leave (see runWithCommittedMutations).
+    // Called from running mutation code, these store actions commit the
+    // code's writes so far before they record, replace or save state, and
+    // the code goes on from the state they leave (see storyStateGuard).
     goto(passageName: string): void {
-      runWithCommittedMutations(() =>
-        useStoryStore.getState().navigate(passageName),
-      );
+      useStoryStore.getState().navigate(passageName);
     },
 
     back(): void {
-      runWithCommittedMutations(() => useStoryStore.getState().goBack());
+      useStoryStore.getState().goBack();
     },
 
     forward(): void {
-      runWithCommittedMutations(() => useStoryStore.getState().goForward());
+      useStoryStore.getState().goForward();
     },
 
     restart(): void {
-      runWithCommittedMutations(() => useStoryStore.getState().restart());
+      useStoryStore.getState().restart();
     },
 
     save(slot?: string, custom?: Record<string, unknown>): Promise<void> {
-      return runWithCommittedMutations(() =>
-        useStoryStore.getState().save(slot, custom),
-      );
+      return useStoryStore.getState().save(slot, custom);
     },
 
     load(slot?: string): Promise<void> {
@@ -378,7 +359,7 @@ function createStoryAPI(): StoryAPI {
 
     visited(name?: string): number {
       const state = useStoryStore.getState();
-      return state.visitCounts[name ?? state.currentPassage] ?? 0;
+      return countOf(state.visitCounts, name ?? state.currentPassage);
     },
 
     hasVisited(name?: string): boolean {
@@ -387,17 +368,17 @@ function createStoryAPI(): StoryAPI {
 
     hasVisitedAny(...names: string[]): boolean {
       const { visitCounts } = useStoryStore.getState();
-      return names.some((n) => (visitCounts[n] ?? 0) > 0);
+      return names.some((n) => countOf(visitCounts, n) > 0);
     },
 
     hasVisitedAll(...names: string[]): boolean {
       const { visitCounts } = useStoryStore.getState();
-      return names.every((n) => (visitCounts[n] ?? 0) > 0);
+      return names.every((n) => countOf(visitCounts, n) > 0);
     },
 
     rendered(name?: string): number {
       const state = useStoryStore.getState();
-      return state.renderCounts[name ?? state.currentPassage] ?? 0;
+      return countOf(state.renderCounts, name ?? state.currentPassage);
     },
 
     hasRendered(name?: string): boolean {
@@ -406,12 +387,12 @@ function createStoryAPI(): StoryAPI {
 
     hasRenderedAny(...names: string[]): boolean {
       const { renderCounts } = useStoryStore.getState();
-      return names.some((n) => (renderCounts[n] ?? 0) > 0);
+      return names.some((n) => countOf(renderCounts, n) > 0);
     },
 
     hasRenderedAll(...names: string[]): boolean {
       const { renderCounts } = useStoryStore.getState();
-      return names.every((n) => (renderCounts[n] ?? 0) > 0);
+      return names.every((n) => countOf(renderCounts, n) > 0);
     },
 
     currentPassage(): Passage | undefined {
@@ -483,32 +464,16 @@ function createStoryAPI(): StoryAPI {
         return { usage: 0, quota: 0, estimateSupported: false };
       },
 
-      async clearGameData(): Promise<void> {
-        const ifid = useStoryStore.getState().storyData?.ifid;
-        if (!ifid) return;
-        await _clearGameData(ifid);
-        useStoryStore.setState((state) => {
-          state.knownSaves = {};
-        });
-        useStoryStore.getState().restart();
+      clearGameData(): Promise<void> {
+        return useStoryStore.getState().clearGameData();
       },
 
-      async clearAllData(): Promise<void> {
-        await _clearAllData();
-        useStoryStore.setState((state) => {
-          state.knownSaves = {};
-        });
-        useStoryStore.getState().restart();
+      clearAllData(): Promise<void> {
+        return useStoryStore.getState().clearAllData();
       },
 
-      async deletePlaythrough(playthroughId: string): Promise<void> {
-        const { storyData } = useStoryStore.getState();
-        if (!storyData) return;
-        await deletePlaythroughData(storyData.ifid, playthroughId);
-        const known = await populateKnownSaves(storyData.ifid);
-        useStoryStore.setState((state) => {
-          state.knownSaves = known;
-        });
+      deletePlaythrough(playthroughId: string): Promise<void> {
+        return useStoryStore.getState().deletePlaythrough(playthroughId);
       },
 
       get backend() {

package/src/story-init.ts

@@ -47,7 +47,7 @@ export function executeStoryInit() {
     document.body.appendChild(container);
     storyInitContainer = container;
     render(
-      h(() => renderNodes(ast) as any, null),
+      h(() => renderNodes(ast), null),
       container,
     );
 

package/src/story-variables.ts

@@ -1,5 +1,9 @@
 import type { Passage } from './parser';
-import { tokenize } from './markup/tokenizer';
+import { tokenize, type Token } from './markup/tokenizer';
+import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
+import { errorMessage } from './utils/error-message';
+import { lexJs, scanStringLiteral, type JsGoal } from './js-lexer';
+import { createNamespace, RESERVED_NAME } from './utils/namespace';
 
 export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
 
@@ -17,9 +21,8 @@ function declarationRegex(sigil: string): RegExp {
   const escaped = sigil.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   return new RegExp(`^${escaped}(\\w+)\\s*=\\s*(.+)$`);
 }
-const VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
-/** `{` followed by a sigil starts an interpolation block inside literal text. */
-const INTERP_START_RE = /^[$_@%]\w/;
+/** A `$name` reference with its dot path, at a `$` the lexer found. */
+const VAR_PATH_RE = /\$(\w+(?:\.\w+)*)/y;
 /** Quoted first argument of an input macro naming a story variable. */
 const QUOTED_VAR_ARG_RE = /^["']\$(\w+(?:\.\w+)*)["']?$/;
 const FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
@@ -77,12 +80,17 @@ export function parseStoryVariables(
     }
 
     const [, name, expr] = match as [string, string, string];
+    if (name === RESERVED_NAME) {
+      throw new Error(
+        `${passageName}: "${sigil}${name}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`,
+      );
+    }
     let value: unknown;
     try {
       value = new Function('return (' + expr + ')')();
     } catch (err) {
       throw new Error(
-        `${passageName}: Failed to evaluate "${sigil}${name} = ${expr}": ${err instanceof Error ? err.message : err}`,
+        `${passageName}: Failed to evaluate "${sigil}${name} = ${expr}": ${errorMessage(err)}`,
       );
     }
 
@@ -90,9 +98,7 @@ export function parseStoryVariables(
     try {
       fieldSchema = inferSchema(value);
     } catch (err) {
-      throw new Error(
-        `${passageName}: ${err instanceof Error ? err.message : err}`,
-      );
+      throw new Error(`${passageName}: ${errorMessage(err)}`);
     }
     schema.set(name, { ...fieldSchema, name, default: value });
   }
@@ -128,6 +134,10 @@ function validateRef(
   const parts = ref.split('.');
   const rootName = parts[0]!;
 
+  if (rootName === RESERVED_NAME) {
+    return `"$${rootName}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`;
+  }
+
   // Skip for-loop locals
   if (forLocals.has(rootName)) return null;
 
@@ -187,107 +197,81 @@ const BUILTIN_STORE_VAR_MACROS: readonly string[] = [
 
 type RefCallback = (ref: string) => void;
 
-/** Report every `$var.path` in a code segment free of strings/comments. */
-function scanRefs(segment: string, onRef: RefCallback): void {
-  for (const match of segment.matchAll(VAR_REF_RE)) onRef(match[1]!);
-}
-
-/** Index of the quote closing the string opened at `start` (or the end). */
-function findClosingQuote(code: string, start: number): number {
-  const quote = code[start];
-  let i = start + 1;
-  while (i < code.length && code[i] !== quote) {
-    i += code[i] === '\\' ? 2 : 1;
-  }
-  return Math.min(i, code.length);
-}
+const NO_STORE_VAR_MACROS: ReadonlySet<string> = new Set();
 
 /**
- * Scan literal text (string contents, HTML attribute values) for `{$…}`
- * interpolation blocks, which interpolating macros and HTML attributes
- * resolve at runtime. A bare `$word` in literal text is not a reference.
+ * Scan the value of a code attribute (`onclick`, see isCodeAttribute) for
+ * the `{$…}` references resolved in it; its other braces are code.
  */
-function scanInterpolations(text: string, onRef: RefCallback): void {
-  let i = text.indexOf('{');
-  while (i !== -1) {
-    const next = INTERP_START_RE.test(text.slice(i + 1, i + 3))
-      ? scanCode(text, i + 1, onRef, true)
-      : i + 1;
-    i = text.indexOf('{', next);
+function scanSigilReferences(value: string, onRef: RefCallback): void {
+  for (const part of splitSigilTemplate(value)) {
+    if ('expr' in part) scanCode(part.expr, onRef);
   }
 }
 
 /**
- * Scan a template literal starting just after its opening backtick: literal
- * parts are text, `${…}` parts are code. Returns the index just past the
- * closing backtick.
+ * Scan literal text (string contents, HTML attribute values) for the markup
+ * that labels and HTML attributes evaluate at runtime: `{$…}` displays,
+ * expressions and macros, read as in passage text. A bare `$word` in
+ * literal text is not a reference.
  */
-function scanTemplate(code: string, start: number, onRef: RefCallback): number {
-  let i = start;
-  let textStart = start;
-  while (i < code.length) {
-    const ch = code[i];
-    if (ch === '\\') {
-      i += 2;
-    } else if (ch === '`') {
-      scanInterpolations(code.slice(textStart, i), onRef);
-      return i + 1;
-    } else if (ch === '$' && code[i + 1] === '{') {
-      scanInterpolations(code.slice(textStart, i), onRef);
-      i = textStart = scanCode(code, i + 2, onRef, true);
-    } else {
-      i++;
-    }
-  }
-  scanInterpolations(code.slice(textStart), onRef);
-  return code.length;
+function scanInterpolations(
+  text: string,
+  onRef: RefCallback,
+  storeVarMacros: ReadonlySet<string> = NO_STORE_VAR_MACROS,
+): void {
+  if (!text.includes('{')) return;
+  collectTokenRefs(text, tokenize(text, { text: true }), storeVarMacros, onRef);
 }
 
 /**
- * Report `$var` references in JavaScript code. Like the string-aware
- * expression transformer, sigils inside string literals are left alone while
- * template-literal `${…}` parts are code; comments are skipped too. When
- * `nested`, stops at the `}` closing the enclosing block and returns the index
- * just past it.
+ * Report `$var` references in JavaScript code, lexed as the expression
+ * engine lexes it (`lexJs`): references in code, but none inside string or
+ * regex literals or comments, nor property names (`a.$b`, `{ $b: 1 }`).
+ * The text of string and template literals is scanned for the markup that
+ * labels evaluate (`{$…}`); the `${…}` parts of template literals are code.
  */
 function scanCode(
   code: string,
-  start: number,
   onRef: RefCallback,
-  nested = false,
-): number {
-  let i = start;
-  let segStart = start;
-  let depth = 0;
-  while (i < code.length) {
-    const ch = code[i];
-    const next = code[i + 1];
-    const isComment = ch === '/' && (next === '/' || next === '*');
-    if (ch === '"' || ch === "'" || ch === '`' || isComment) {
-      scanRefs(code.slice(segStart, i), onRef);
-      if (ch === '`') {
-        i = scanTemplate(code, i + 1, onRef);
-      } else if (isComment) {
-        const close = code.indexOf(next === '/' ? '\n' : '*/', i + 2);
-        i = close === -1 ? code.length : next === '/' ? close : close + 2;
-      } else {
-        const close = findClosingQuote(code, i);
-        scanInterpolations(code.slice(i + 1, close), onRef);
-        i = Math.min(close + 1, code.length);
-      }
-      segStart = i;
-      continue;
-    }
-    if (nested && ch === '{') {
-      depth++;
-    } else if (nested && ch === '}' && depth-- === 0) {
-      scanRefs(code.slice(segStart, i), onRef);
-      return i + 1;
-    }
-    i++;
-  }
-  scanRefs(code.slice(segStart), onRef);
-  return code.length;
+  goal: JsGoal = 'expression',
+): void {
+  /** Open template literals: their text so far, null in an interpolation. */
+  const templates: { nesting: number; text: string | null }[] = [];
+  lexJs(
+    code,
+    {
+      variable(sigil, _name, index) {
+        if (sigil !== '$') return;
+        VAR_PATH_RE.lastIndex = index;
+        onRef(VAR_PATH_RE.exec(code)![1]!);
+      },
+      literal(text, _index, nesting) {
+        const template = templates[templates.length - 1];
+        if (template?.nesting === nesting) {
+          if (template.text === null) {
+            // The `}` ending an interpolation: back to the template's text
+            template.text = '';
+          } else if (text === '`' || text === '${') {
+            scanInterpolations(template.text, onRef);
+            if (text === '`') templates.pop();
+            else template.text = null;
+          } else {
+            template.text += text;
+          }
+        } else if (text === '`') {
+          templates.push({ nesting, text: '' });
+        } else if (text[0] === '"' || text[0] === "'") {
+          const { closed } = scanStringLiteral(text, 0);
+          scanInterpolations(text.slice(1, closed ? -1 : undefined), onRef);
+        }
+        // Regex literals and comments hold no references
+      },
+    },
+    goal,
+  );
+  // An unterminated template literal's text
+  for (const t of templates) if (t.text) scanInterpolations(t.text, onRef);
 }
 
 /**
@@ -301,19 +285,29 @@ function collectPassageRefs(
   storeVarMacros: ReadonlySet<string>,
   onRef: RefCallback,
 ): void {
-  const tokens = tokenize(content);
+  collectTokenRefs(content, tokenize(content), storeVarMacros, onRef);
+}
+
+/** Report the `$var` references in the tokens of `content`. */
+function collectTokenRefs(
+  content: string,
+  tokens: Token[],
+  storeVarMacros: ReadonlySet<string>,
+  onRef: RefCallback,
+): void {
   for (let t = 0; t < tokens.length; t++) {
     const token = tokens[t]!;
     if (token.type === 'variable') {
       if (token.scope === 'variable' && token.name) onRef(token.name);
     } else if (token.type === 'expression') {
-      scanCode(token.expression, 0, onRef);
+      scanCode(token.expression, onRef);
     } else if (token.type === 'html') {
-      for (const value of Object.values(token.attributes)) {
-        scanInterpolations(value, onRef);
+      for (const [name, value] of Object.entries(token.attributes)) {
+        if (isCodeAttribute(name)) scanSigilReferences(value, onRef);
+        else scanInterpolations(value, onRef, storeVarMacros);
       }
     } else if (token.type === 'macro' && !token.isClose) {
-      scanCode(token.rawArgs, 0, onRef);
+      scanCode(token.rawArgs, onRef);
 
       if (storeVarMacros.has(token.name.toLowerCase())) {
         const first = token.rawArgs.trim().split(/\s+/)[0] ?? '';
@@ -331,7 +325,8 @@ function collectPassageRefs(
           close++;
         }
         if (close < tokens.length) {
-          scanCode(content.slice(token.end, tokens[close]!.start), 0, onRef);
+          const body = content.slice(token.end, tokens[close]!.start);
+          scanCode(body, onRef, 'statements');
           t = close;
         }
       }
@@ -374,12 +369,13 @@ export function validatePassages(
 }
 
 /**
- * Extract default values from the schema as a plain object.
+ * Extract default values from the schema as a record without a prototype,
+ * like the namespaces it initializes (see utils/namespace.ts).
  */
 export function extractDefaults(
   schema: Map<string, VariableSchema>,
 ): Record<string, unknown> {
-  const defaults: Record<string, unknown> = {};
+  const defaults = createNamespace();
   for (const [name, varSchema] of schema) {
     defaults[name] = varSchema.default;
   }

package/src/triggers.ts

@@ -1,5 +1,5 @@
 import { evaluate } from './expression';
-import { executeMutation, runWithCommittedMutations } from './execute-mutation';
+import { executeMutation, readState } from './execute-mutation';
 import { useStoryStore } from './store';
 
 export interface WatchOptions {
@@ -19,7 +19,6 @@ export interface QueuedDialog {
 }
 
 interface Trigger {
-  id: number;
   name?: string;
   condition: string;
   callback?: () => void;
@@ -30,7 +29,6 @@ interface Trigger {
   macroKey?: string;
 }
 
-let nextId = 0;
 let triggers: Trigger[] = [];
 let checking = false;
 
@@ -46,8 +44,9 @@ interface DialogHostCallbacks {
 }
 let dialogHostCallbacks: DialogHostCallbacks | null = null;
 
+/** A condition's value in program order (see readState). */
 function evalCondition(condition: string): boolean {
-  const state = useStoryStore.getState();
+  const state = readState();
   try {
     return !!evaluate(
       condition,
@@ -66,13 +65,11 @@ function registerTrigger(
   callbackOrOptions: (() => void) | WatchOptions,
   macroKey?: string,
 ): () => void {
-  const id = nextId++;
   const isCallback = typeof callbackOrOptions === 'function';
   const options = isCallback ? undefined : callbackOrOptions;
   const callback = isCallback ? callbackOrOptions : undefined;
 
   const trigger: Trigger = {
-    id,
     name: options?.name,
     condition,
     callback,
@@ -85,8 +82,10 @@ function registerTrigger(
   triggers.push(trigger);
   triggers.sort((a, b) => b.priority - a.priority);
 
+  // By identity: an unsubscribe kept across a restart (resetTriggers) must
+  // not remove a watcher added since
   return () => {
-    triggers = triggers.filter((t) => t.id !== id);
+    triggers = triggers.filter((t) => t !== trigger);
   };
 }
 
@@ -150,9 +149,9 @@ function fireTrigger(trigger: Trigger): void {
 
   if (options.goto) {
     // A watcher fired by a Story.set in running code navigates after that
-    // code's writes so far, so they are part of the moment it leaves.
-    const passage = options.goto;
-    runWithCommittedMutations(() => useStoryStore.getState().navigate(passage));
+    // code's writes so far, so they are part of the moment it leaves (the
+    // store commits them first).
+    useStoryStore.getState().navigate(options.goto);
   }
 }
 
@@ -176,7 +175,7 @@ function runCheckLoop(): void {
         anyFired = true;
 
         if (trigger.options?.once) {
-          triggers = triggers.filter((t) => t.id !== trigger.id);
+          triggers = triggers.filter((t) => t !== trigger);
         }
 
         fireTrigger(trigger);
@@ -266,7 +265,6 @@ export function reinitTriggerState(): void {
 export function resetTriggers(): void {
   triggers = [];
   dialogQueue = [];
-  nextId = 0;
   dialogHostCallbacks?.closeAll();
 }
 

package/src/utils/counts.ts

@@ -0,0 +1,45 @@
+/**
+ * Passage counters: the visit and render counts of the story state, keyed
+ * by passage name.
+ *
+ * A passage may have any name, including `constructor`, `toString` or
+ * `__proto__`, so the counters only ever read their own entries: a passage
+ * that was never counted counts 0, never an Object.prototype member. The
+ * store keeps them without a prototype, so writing the count of a passage
+ * named `__proto__` stores an entry instead of replacing the prototype.
+ * Counters from outside the store (a loaded save) go through
+ * createCounts(), which keeps only their own entries that are counts.
+ */
+
+export type Counts = Record<string, number>;
+
+const isCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 0;
+
+/** The count of `name` in `counts`: its own entry, or 0. */
+export function countOf(
+  counts: object | null | undefined,
+  name: string,
+): number {
+  if (!counts || !Object.prototype.hasOwnProperty.call(counts, name)) return 0;
+  const value = (counts as Record<string, unknown>)[name];
+  return isCount(value) ? value : 0;
+}
+
+/**
+ * Counters with no prototype holding the own entries of `source` that are
+ * counts, with `name` (if given) counted once more. Immer copies the
+ * counters on every write anyway, so counting into a fresh copy costs no
+ * more than counting in place.
+ */
+export function createCounts(source?: object | null, name?: string): Counts {
+  const counts = Object.create(null) as Counts;
+  if (source) {
+    for (const key of Object.keys(source)) {
+      const value = (source as Record<string, unknown>)[key];
+      if (isCount(value)) counts[key] = value;
+    }
+  }
+  if (name !== undefined) counts[name] = countOf(source, name) + 1;
+  return counts;
+}

package/src/utils/error-message.ts

@@ -0,0 +1,12 @@
+/**
+ * The message to show for a caught value. Anything can be thrown, not only
+ * Errors: an Error gives its message, a string is its own message, and any
+ * other value gives `fallback` when one is passed, else its string form
+ * (never `undefined`). An empty message also gives `fallback`, or for an
+ * Error its string form (e.g. "Error").
+ */
+export function errorMessage(err: unknown, fallback?: string): string {
+  if (err instanceof Error) return err.message || fallback || String(err);
+  if (typeof err === 'string' && err !== '') return err;
+  return fallback ?? String(err);
+}