@rohal12/spindle 0.52.2 → 0.52.4

package/src/settings.ts

@@ -1,5 +1,5 @@
 import { useStoryStore } from './store';
-import { createNamespace, ownValue } from './utils/namespace';
+import { createNamespace, hasOwn, ownValue } from './utils/namespace';
 
 export interface ToggleConfig {
   label: string;
@@ -76,29 +76,30 @@ function loadFromStorage(): void {
   }
 }
 
+/** Register a setting, starting from its default unless it has a value. */
+function define(name: string, def: SettingDef): void {
+  definitions.set(name, def);
+  if (!hasOwn(values, name)) values[name] = def.config.default;
+  loadFromStorage();
+}
+
+/** The value of setting `name` if it has the type of `fallback`, else that. */
+function valueOf<T>(name: string, fallback: T): T {
+  const v = ownValue(values, name);
+  return typeof v === typeof fallback ? (v as T) : fallback;
+}
+
 export const settings = {
   addToggle(name: string, config: ToggleConfig): void {
-    definitions.set(name, { type: 'toggle', config });
-    if (!Object.prototype.hasOwnProperty.call(values, name)) {
-      values[name] = config.default;
-    }
-    loadFromStorage();
+    define(name, { type: 'toggle', config });
   },
 
   addList(name: string, config: ListConfig): void {
-    definitions.set(name, { type: 'list', config });
-    if (!Object.prototype.hasOwnProperty.call(values, name)) {
-      values[name] = config.default;
-    }
-    loadFromStorage();
+    define(name, { type: 'list', config });
   },
 
   addRange(name: string, config: RangeConfig): void {
-    definitions.set(name, { type: 'range', config });
-    if (!Object.prototype.hasOwnProperty.call(values, name)) {
-      values[name] = config.default;
-    }
-    loadFromStorage();
+    define(name, { type: 'range', config });
   },
 
   get(name: string): unknown {
@@ -106,18 +107,15 @@ export const settings = {
   },
 
   getToggle(name: string): boolean {
-    const v = ownValue(values, name);
-    return typeof v === 'boolean' ? v : false;
+    return valueOf(name, false);
   },
 
   getList(name: string): string {
-    const v = ownValue(values, name);
-    return typeof v === 'string' ? v : '';
+    return valueOf(name, '');
   },
 
   getRange(name: string): number {
-    const v = ownValue(values, name);
-    return typeof v === 'number' ? v : 0;
+    return valueOf(name, 0);
   },
 
   set(name: string, value: unknown): void {

package/src/store.ts

@@ -62,11 +62,12 @@ import {
 } from './execute-mutation';
 import {
   checkVariableName,
+  createCounts,
   createNamespace,
   isNamespace,
+  type Counts,
   type Namespace,
 } from './utils/namespace';
-import { createCounts, type Counts } from './utils/counts';
 
 enablePatches();
 // Story state holds Map and Set values: Immer must be able to draft them

package/src/story-api.ts

@@ -23,8 +23,8 @@ import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
 import { frozenCopy, getActiveMutationScope } from './execute-mutation';
 import { getByPath, setByPath } from './utils/object-path';
-import { checkVariableName } from './utils/namespace';
-import { countOf } from './utils/counts';
+import { changedNames, checkVariableName, ownValue } from './utils/namespace';
+import { countQueries, currentPassage, previousPassage } from './expression';
 import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
@@ -83,35 +83,24 @@ function ensureVariableChangedSubscription(): void {
   let prevTrans = useStoryStore.getState().transient;
   useStoryStore.subscribe((state) => {
     const changed: Record<string, { from: unknown; to: unknown }> = {};
-    let hasChanges = false;
-
-    // Check $variables
-    const allVarKeys = new Set([
-      ...Object.keys(prevVars),
-      ...Object.keys(state.variables),
-    ]);
-    for (const key of allVarKeys) {
-      if (state.variables[key] !== prevVars[key]) {
-        changed[key] = { from: prevVars[key], to: state.variables[key] };
-        hasChanges = true;
+    const collect = (
+      prev: Record<string, unknown>,
+      next: Record<string, unknown>,
+      prefix: string,
+    ) => {
+      for (const key of changedNames(prev, next)) {
+        changed[prefix + key] = {
+          from: ownValue(prev, key),
+          to: ownValue(next, key),
+        };
       }
-    }
-
-    // Check %transient
-    const allTransKeys = new Set([
-      ...Object.keys(prevTrans),
-      ...Object.keys(state.transient),
-    ]);
-    for (const key of allTransKeys) {
-      if (state.transient[key] !== prevTrans[key]) {
-        changed[`%${key}`] = { from: prevTrans[key], to: state.transient[key] };
-        hasChanges = true;
-      }
-    }
+    };
+    collect(prevVars, state.variables, '');
+    collect(prevTrans, state.transient, '%');
 
     prevVars = state.variables;
     prevTrans = state.transient;
-    if (hasChanges) {
+    if (Object.keys(changed).length > 0) {
       emit('variableChanged', changed);
     }
   });
@@ -271,6 +260,8 @@ function setOne(draft: VariableNamespaces, name: string, value: unknown): void {
 }
 
 function createStoryAPI(): StoryAPI {
+  const visits = countQueries(() => useStoryStore.getState().visitCounts);
+  const renders = countQueries(() => useStoryStore.getState().renderCounts);
   return {
     get(name: string): unknown {
       const { isTransient, key } = parseName(name);
@@ -284,7 +275,7 @@ function createStoryAPI(): StoryAPI {
       const namespace = isTransient ? source.transient : source.variables;
       const value = key.includes('.')
         ? getByPath(namespace, key.split('.'))
-        : namespace[key];
+        : ownValue(namespace, key);
       return scope ? frozenCopy(value) : value;
     },
 
@@ -357,55 +348,16 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().importSave(data, slot);
     },
 
-    visited(name?: string): number {
-      const state = useStoryStore.getState();
-      return countOf(state.visitCounts, name ?? state.currentPassage);
-    },
-
-    hasVisited(name?: string): boolean {
-      return this.visited(name) > 0;
-    },
-
-    hasVisitedAny(...names: string[]): boolean {
-      const { visitCounts } = useStoryStore.getState();
-      return names.some((n) => countOf(visitCounts, n) > 0);
-    },
-
-    hasVisitedAll(...names: string[]): boolean {
-      const { visitCounts } = useStoryStore.getState();
-      return names.every((n) => countOf(visitCounts, n) > 0);
-    },
-
-    rendered(name?: string): number {
-      const state = useStoryStore.getState();
-      return countOf(state.renderCounts, name ?? state.currentPassage);
-    },
-
-    hasRendered(name?: string): boolean {
-      return this.rendered(name) > 0;
-    },
-
-    hasRenderedAny(...names: string[]): boolean {
-      const { renderCounts } = useStoryStore.getState();
-      return names.some((n) => countOf(renderCounts, n) > 0);
-    },
-
-    hasRenderedAll(...names: string[]): boolean {
-      const { renderCounts } = useStoryStore.getState();
-      return names.every((n) => countOf(renderCounts, n) > 0);
-    },
-
-    currentPassage(): Passage | undefined {
-      const state = useStoryStore.getState();
-      return state.storyData?.passages.get(state.currentPassage);
-    },
-
-    previousPassage(): Passage | undefined {
-      const state = useStoryStore.getState();
-      if (state.historyIndex <= 0) return undefined;
-      const prevName = state.history[state.historyIndex - 1]?.passage;
-      return prevName ? state.storyData?.passages.get(prevName) : undefined;
-    },
+    visited: visits.count,
+    hasVisited: visits.has,
+    hasVisitedAny: visits.any,
+    hasVisitedAll: visits.all,
+    rendered: renders.count,
+    hasRendered: renders.has,
+    hasRenderedAny: renders.any,
+    hasRenderedAll: renders.all,
+    currentPassage,
+    previousPassage,
 
     get title(): string {
       return useStoryStore.getState().storyData?.name || '';

package/src/story-variables.ts

@@ -3,7 +3,7 @@ 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';
+import { createNamespace, variableNameError } from './utils/namespace';
 
 export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
 
@@ -80,11 +80,8 @@ 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)`,
-      );
-    }
+    const nameError = variableNameError(name, sigil + name);
+    if (nameError) throw new Error(`${passageName}: ${nameError}`);
     let value: unknown;
     try {
       value = new Function('return (' + expr + ')')();
@@ -134,9 +131,8 @@ 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)`;
-  }
+  const nameError = variableNameError(rootName, '$' + rootName);
+  if (nameError) return nameError;
 
   // Skip for-loop locals
   if (forLocals.has(rootName)) return null;

package/src/utils/live-locals.ts

@@ -1,4 +1,4 @@
-import { createNamespace, ownValue } from './namespace';
+import { createNamespace, hasOwn, ownValue } from './namespace';
 
 /**
  * Read-only view of a locals scope that always reflects its current values.
@@ -16,9 +16,7 @@ export function liveLocalsView(
   return new Proxy(createNamespace(), {
     get: (_, key) =>
       typeof key === 'string' ? ownValue(getValues(), key) : undefined,
-    has: (_, key) =>
-      typeof key === 'string' &&
-      Object.prototype.hasOwnProperty.call(getValues(), key),
+    has: (_, key) => typeof key === 'string' && hasOwn(getValues(), key),
     ownKeys: () => Reflect.ownKeys(getValues()),
     getOwnPropertyDescriptor: (_, key) => {
       const desc = Object.getOwnPropertyDescriptor(getValues(), key);

package/src/utils/namespace.ts

@@ -1,14 +1,17 @@
 /**
- * Variable namespaces: the records holding $story variables, _temporary
- * variables, %transient variables and @locals, keyed by variable name.
+ * Name-keyed records: the variable namespaces ($story variables, _temporary
+ * variables, %transient variables and @locals), the passage counters and
+ * the other records keyed by names the author chooses.
  *
  * They have no prototype, so every name is plain storage: a variable may be
  * called `constructor`, `toString` or `hasOwnProperty`, and reading one
  * that was never set gives undefined rather than an Object.prototype
- * member. The one name they cannot hold is `__proto__`: story state (and so
- * saves) never holds a property by that name, and on an ordinary object
- * writing it would replace the prototype instead of storing a value. It is
- * refused wherever a variable name enters (checkVariableName).
+ * member. Records that may have a prototype (a loaded save, a caller's
+ * object) are read through ownValue(), which only sees their own entries.
+ * The one variable name a namespace cannot hold is `__proto__`: story state
+ * (and so saves) never holds a property by that name, and on an ordinary
+ * object writing it would replace the prototype instead of storing a value.
+ * It is refused wherever a variable name enters (checkVariableName).
  */
 
 export type Namespace = Record<string, unknown>;
@@ -17,31 +20,58 @@ export type Namespace = Record<string, unknown>;
 export const RESERVED_NAME = '__proto__';
 
 /**
- * Throw a TypeError if `name` (without its sigil) cannot be a variable
- * name. `label` is the name as the author wrote it (e.g. `$__proto__`).
+ * Why `name` (without its sigil) cannot be a variable name, or undefined if
+ * it can. `label` is the name as the author wrote it (e.g. `$__proto__`).
  */
+export function variableNameError(
+  name: string,
+  label = name,
+): string | undefined {
+  return name === RESERVED_NAME
+    ? `"${label}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`
+    : undefined;
+}
+
+/** Throw a TypeError if `name` cannot be a variable name. */
 export function checkVariableName(name: string, label = name): void {
-  if (name === RESERVED_NAME) {
-    throw new TypeError(
-      `spindle: "${label}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`,
-    );
-  }
+  const error = variableNameError(name, label);
+  if (error) throw new TypeError(`spindle: ${error}`);
 }
 
-/** A namespace with no prototype holding the own entries of `sources`. */
-export function createNamespace(
-  ...sources: readonly (object | null | undefined)[]
-): Namespace {
-  const ns = Object.create(null) as Namespace;
+/** Whether `obj` holds `key` as an own property. */
+export const hasOwn = (obj: object, key: PropertyKey): boolean =>
+  Object.prototype.hasOwnProperty.call(obj, key);
+
+/** `ns[key]` if `ns` holds it as an own property, else undefined. */
+export const ownValue = (
+  ns: object | null | undefined,
+  key: string,
+): unknown => (ns && hasOwn(ns, key) ? (ns as Namespace)[key] : undefined);
+
+/**
+ * A record with no prototype holding the own entries of `sources`, or only
+ * those whose value passes `keep`.
+ */
+function ownEntries<T>(
+  sources: readonly (object | null | undefined)[],
+  keep: (value: unknown) => boolean = () => true,
+): Record<string, T> {
+  const record = Object.create(null) as Record<string, T>;
   for (const source of sources) {
     if (!source) continue;
     for (const key of Object.keys(source)) {
-      ns[key] = (source as Namespace)[key];
+      const value = (source as Namespace)[key];
+      if (keep(value)) record[key] = value as T;
     }
   }
-  return ns;
+  return record;
 }
 
+/** A namespace with no prototype holding the own entries of `sources`. */
+export const createNamespace = (
+  ...sources: readonly (object | null | undefined)[]
+): Namespace => ownEntries(sources);
+
 /** Whether `value` is an object with no prototype. */
 export const isNamespace = (value: object): boolean =>
   Object.getPrototypeOf(value) === null;
@@ -64,8 +94,42 @@ export function withEntry(
 /** An empty namespace that cannot change. */
 export const EMPTY_NAMESPACE: Namespace = Object.freeze(createNamespace());
 
-/** `ns[key]` if `ns` holds it as an own property, else undefined. */
-export const ownValue = (ns: object, key: string): unknown =>
-  Object.prototype.hasOwnProperty.call(ns, key)
-    ? (ns as Namespace)[key]
-    : undefined;
+/** The names whose own entries differ between `a` and `b`, `a`'s first. */
+export function changedNames(a: object, b: object): string[] {
+  const names = new Set([...Object.keys(a), ...Object.keys(b)]);
+  return [...names].filter((name) => ownValue(a, name) !== ownValue(b, name));
+}
+
+/**
+ * Passage counters: the visit and render counts of the story state, keyed
+ * by passage name. A passage may have any name, `__proto__` included, so
+ * counting one stores an entry instead of replacing the prototype, and a
+ * passage that was never counted counts 0. 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 {
+  const value = ownValue(counts, 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 = ownEntries<number>([source], isCount);
+  if (name !== undefined) counts[name] = countOf(source, name) + 1;
+  return counts;
+}

package/src/utils/object-path.ts

@@ -1,7 +1,5 @@
 import { isDraft } from 'immer';
-
-const hasOwn = (obj: object, key: string): boolean =>
-  Object.prototype.hasOwnProperty.call(obj, key);
+import { hasOwn } from './namespace';
 
 /**
  * Traverse dot-path segments on an object and return the nested value.

package/src/utils/counts.ts

@@ -1,45 +0,0 @@
-/**
- * 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;
-}