@rohal12/spindle 0.52.7 → 0.52.9

package/src/registry.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from 'preact';
 import type { ASTNode, Branch } from './markup/ast';
+import { NameMap, NameSet } from './utils/macro-names';
 
 export interface MacroProps {
   rawArgs: string;
@@ -9,17 +10,17 @@ export interface MacroProps {
   branches?: Branch[];
 }
 
-const registry = new Map<string, ComponentType<MacroProps>>();
+const registry = new NameMap<ComponentType<MacroProps>>();
 
 export function registerMacro(
   name: string,
   component: ComponentType<MacroProps>,
 ): void {
-  registry.set(name.toLowerCase(), component);
+  registry.set(name, component);
 }
 
 export function getMacro(name: string): ComponentType<MacroProps> | undefined {
-  return registry.get(name.toLowerCase());
+  return registry.get(name);
 }
 
 /**
@@ -42,29 +43,29 @@ export type MacroTextRenderer = (
   ctx: MacroTextContext,
 ) => string;
 
-const textRegistry = new Map<string, MacroTextRenderer>();
+const textRegistry = new NameMap<MacroTextRenderer>();
 
 /** Register (or, with undefined, remove) the text form of a macro. */
 export function registerMacroText(
   name: string,
   text: MacroTextRenderer | undefined,
 ): void {
-  if (text) textRegistry.set(name.toLowerCase(), text);
-  else textRegistry.delete(name.toLowerCase());
+  if (text) textRegistry.set(name, text);
+  else textRegistry.delete(name);
 }
 
 export function getMacroText(name: string): MacroTextRenderer | undefined {
-  return textRegistry.get(name.toLowerCase());
+  return textRegistry.get(name);
 }
 
-const subMacros = new Set<string>();
+const subMacros = new NameSet();
 
 export function registerSubMacro(name: string): void {
-  subMacros.add(name.toLowerCase());
+  subMacros.add(name);
 }
 
 export function isSubMacro(name: string): boolean {
-  return subMacros.has(name.toLowerCase());
+  return subMacros.has(name);
 }
 
 /**
@@ -133,13 +134,13 @@ export interface MacroMetadata {
   parameters?: ParameterDef[];
 }
 
-const metadataRegistry = new Map<string, MacroMetadata>();
+const metadataRegistry = new NameMap<MacroMetadata>();
 
 export function registerMacroMetadata(
   name: string,
   metadata: MacroMetadata,
 ): void {
-  metadataRegistry.set(name.toLowerCase(), metadata);
+  metadataRegistry.set(name, metadata);
 }
 
 export function getMacroRegistry(): MacroMetadata[] {

package/src/saves/save-manager.ts

@@ -9,7 +9,8 @@ import type {
 } from './types';
 import { estimatePayloadBytes, isSaveExport, isSavePayload } from './types';
 import { getBackend, resetBackend } from './storage';
-import { deepClone, serialize, deserialize } from '../class-registry';
+import { serialize, deserialize } from '../class-registry';
+import { deepClone } from '../structural';
 import { emit } from '../event-emitter';
 import { withoutDraws } from '../prng';
 
@@ -101,6 +102,18 @@ function queued<A extends unknown[], R>(
   return (...args) => inOrder(() => op(...args));
 }
 
+/** An operation passing the save `saveId`, if it is stored, to `read`. */
+const readingSave = <R>(read: (record: SaveRecord | undefined) => R) =>
+  queued(async (saveId: string) =>
+    read(await (await getBackend()).getSave(saveId)),
+  );
+
+/** An operation passing the save a slot holds, if any, to `read`. */
+const readingSlot = <R>(read: (record: SaveRecord | undefined) => R) =>
+  queued(async (ifid: string, slot?: string) =>
+    read(await slotRecord(ifid, slot)),
+  );
+
 // --- Playthroughs ---
 
 /**
@@ -371,9 +384,7 @@ export function deserializePayload(payload: SavePayload): SavePayload {
 const livePayload = (record: SaveRecord | undefined) =>
   record && deserializePayload(record.payload);
 
-export const loadSave = queued(async (saveId: string) =>
-  livePayload(await (await getBackend()).getSave(saveId)),
-);
+export const loadSave = readingSave(livePayload);
 
 /**
  * Delete a save record. If the default slot or a named slot holds it, that
@@ -623,9 +634,7 @@ async function hasQuickSaveNow(ifid: string, slot?: string): Promise<boolean> {
   return (await slotRecord(ifid, slot)) !== undefined;
 }
 
-export const loadQuickSave = queued(async (ifid: string, slot?: string) =>
-  livePayload(await slotRecord(ifid, slot)),
-);
+export const loadQuickSave = readingSlot(livePayload);
 
 /**
  * Read the save held in a slot (the default slot when `slot` is omitted) for
@@ -753,9 +762,7 @@ function toExport(record: SaveRecord | undefined): SaveExport | undefined {
   };
 }
 
-export const exportSave = queued(async (saveId: string) =>
-  toExport(await (await getBackend()).getSave(saveId)),
-);
+export const exportSave = readingSave(toExport);
 
 /**
  * Validate an export against the running story and build the record to store:
@@ -812,9 +819,7 @@ export function importSave(
  * Export the save held in a slot (default autosave slot when `slot` is omitted).
  * Returns undefined if the slot is empty.
  */
-export const exportSlotSave = queued(async (ifid: string, slot?: string) =>
-  toExport(await slotRecord(ifid, slot)),
-);
+export const exportSlotSave = readingSlot(toExport);
 
 /**
  * Import an exported save into a slot (default autosave slot when `slot` is

package/src/saves/storage.ts

@@ -256,6 +256,19 @@ export function createLocalStorageBackend(): StorageBackend {
 const IDB_DB_NAME = 'spindle';
 const IDB_DB_VERSION = 1;
 
+/** Each object store's key path, and the key path of each of its indexes. */
+const IDB_STORES: Record<
+  TableName,
+  { keyPath: string; indexes: Record<string, string> }
+> = {
+  saves: {
+    keyPath: 'meta.id',
+    indexes: { ifid: 'meta.ifid', playthroughId: 'meta.playthroughId' },
+  },
+  playthroughs: { keyPath: 'id', indexes: { ifid: 'ifid' } },
+  meta: { keyPath: 'key', indexes: {} },
+};
+
 function createIDBBackend(): StorageBackend {
   let dbPromise: Promise<IDBDatabase> | null = null;
 
@@ -267,26 +280,12 @@ function createIDBBackend(): StorageBackend {
 
       req.onupgradeneeded = () => {
         const db = req.result;
-
-        if (!db.objectStoreNames.contains('saves')) {
-          const savesStore = db.createObjectStore('saves', {
-            keyPath: 'meta.id',
-          });
-          savesStore.createIndex('ifid', 'meta.ifid', { unique: false });
-          savesStore.createIndex('playthroughId', 'meta.playthroughId', {
-            unique: false,
-          });
-        }
-
-        if (!db.objectStoreNames.contains('playthroughs')) {
-          const ptStore = db.createObjectStore('playthroughs', {
-            keyPath: 'id',
-          });
-          ptStore.createIndex('ifid', 'ifid', { unique: false });
-        }
-
-        if (!db.objectStoreNames.contains('meta')) {
-          db.createObjectStore('meta', { keyPath: 'key' });
+        for (const [name, { keyPath, indexes }] of Object.entries(IDB_STORES)) {
+          if (db.objectStoreNames.contains(name)) continue;
+          const store = db.createObjectStore(name, { keyPath });
+          for (const [index, path] of Object.entries(indexes)) {
+            store.createIndex(index, path, { unique: false });
+          }
         }
       };
 

package/src/story-api.ts

@@ -1,5 +1,5 @@
 import { useStoryStore, trackRuntimeUnsub } from './store';
-import type { VariableNamespaces } from './store';
+import type { StoryState, VariableNamespaces } from './store';
 import {
   on as emitterOn,
   emit,
@@ -24,7 +24,7 @@ import { registerClass } from './class-registry';
 import { frozenCopy, getActiveMutationScope } from './execute-mutation';
 import { getByPath, setByPath } from './utils/object-path';
 import { changedNames, checkVariableName, ownValue } from './utils/namespace';
-import { countQueries, currentPassage, previousPassage } from './expression';
+import { historyQueries } from './expression';
 import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
@@ -259,9 +259,15 @@ function setOne(draft: VariableNamespaces, name: string, value: unknown): void {
   }
 }
 
+/** A method calling the store action `name`, as the store holds it then. */
+function storeAction<K extends keyof StoryState>(name: K): StoryState[K] {
+  return ((...args: unknown[]) =>
+    (useStoryStore.getState()[name] as (...args: unknown[]) => unknown)(
+      ...args,
+    )) as StoryState[K];
+}
+
 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);
@@ -300,64 +306,23 @@ function createStoryAPI(): StoryAPI {
     // 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 {
-      useStoryStore.getState().navigate(passageName);
-    },
-
-    back(): void {
-      useStoryStore.getState().goBack();
-    },
-
-    forward(): void {
-      useStoryStore.getState().goForward();
-    },
-
-    restart(): void {
-      useStoryStore.getState().restart();
-    },
-
-    save(slot?: string, custom?: Record<string, unknown>): Promise<void> {
-      return useStoryStore.getState().save(slot, custom);
-    },
-
-    load(slot?: string): Promise<void> {
-      return useStoryStore.getState().load(slot);
-    },
-
-    hasSave(slot?: string): boolean {
-      return useStoryStore.getState().hasSave(slot);
-    },
-
-    getSaveInfo(slot?: string): Promise<SaveInfo | null> {
-      return useStoryStore.getState().getSaveInfo(slot);
-    },
-
-    listSaves(): Promise<SaveInfo[]> {
-      return useStoryStore.getState().listSaves();
-    },
-
-    deleteSave(slot?: string): Promise<void> {
-      return useStoryStore.getState().deleteSave(slot);
-    },
-
-    exportSave(slot?: string): Promise<SaveExport | null> {
-      return useStoryStore.getState().exportSave(slot);
-    },
-
-    importSave(data: unknown, slot?: string): Promise<SaveInfo> {
-      return useStoryStore.getState().importSave(data, slot);
-    },
-
-    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,
+    goto: storeAction('navigate'),
+    back: storeAction('goBack'),
+    forward: storeAction('goForward'),
+    restart: storeAction('restart'),
+    save: storeAction('save'),
+    load: storeAction('load'),
+    hasSave: storeAction('hasSave'),
+    getSaveInfo: storeAction('getSaveInfo'),
+    listSaves: storeAction('listSaves'),
+    deleteSave: storeAction('deleteSave'),
+    exportSave: storeAction('exportSave'),
+    importSave: storeAction('importSave'),
+
+    ...historyQueries(
+      () => useStoryStore.getState().visitCounts,
+      () => useStoryStore.getState().renderCounts,
+    ),
 
     get title(): string {
       return useStoryStore.getState().storyData?.name || '';
@@ -416,17 +381,9 @@ function createStoryAPI(): StoryAPI {
         return { usage: 0, quota: 0, estimateSupported: false };
       },
 
-      clearGameData(): Promise<void> {
-        return useStoryStore.getState().clearGameData();
-      },
-
-      clearAllData(): Promise<void> {
-        return useStoryStore.getState().clearAllData();
-      },
-
-      deletePlaythrough(playthroughId: string): Promise<void> {
-        return useStoryStore.getState().deletePlaythrough(playthroughId);
-      },
+      clearGameData: storeAction('clearGameData'),
+      clearAllData: storeAction('clearAllData'),
+      deletePlaythrough: storeAction('deletePlaythrough'),
 
       get backend() {
         return getBackendType();

package/src/structural.ts

@@ -4,26 +4,9 @@
 // what a change is.
 
 import { registeredClassName } from './class-registry';
-import { hasOwn } from './utils/namespace';
+import { hasOwn, setOwn } from './utils/namespace';
 import { deleteByPath, getByPath, setByPath } from './utils/object-path';
 
-/**
- * Set an own enumerable property. A "__proto__" key is defined as an own
- * property (as JSON.parse does) instead of replacing the prototype.
- */
-export function setOwn(target: object, key: string, value: unknown): void {
-  if (key === '__proto__') {
-    Object.defineProperty(target, key, {
-      value,
-      enumerable: true,
-      writable: true,
-      configurable: true,
-    });
-  } else {
-    (target as Record<string, unknown>)[key] = value;
-  }
-}
-
 // --- Deep Clone ---
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {

package/src/types-drift-check.ts

@@ -1,62 +1,61 @@
 /**
- * Compile-time check: the hand-written types/index.d.ts must stay in sync
- * with the source StoryAPI interface.  If this file fails to compile,
- * the published types have drifted from the implementation.
+ * Compile-time check: the hand-written published types (types/*.d.ts) must
+ * stay in sync with the source they describe. If this file fails to
+ * compile, the published types have drifted from the implementation.
  *
  * Run: npx tsc --noEmit
  */
 import type { StoryAPI as SourceAPI } from './story-api';
-import type { StoryAPI as PublishedAPI } from '../types/index';
-
-// Both directions — if either fails, the types have drifted.
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _sourceToPublished: PublishedAPI = {} as SourceAPI;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _publishedToSource: SourceAPI = {} as PublishedAPI;
-
-// Tooling entry point (`@rohal12/spindle/tooling`): types/tooling.d.ts must
-// match the parser that dist/pkg/tooling.js re-exports.
 import type { parseStoryVariables as SourceParse } from './story-variables';
-import type { parseStoryVariables as PublishedParse } from '../types/tooling';
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _parseSourceToPublished: typeof PublishedParse = {} as typeof SourceParse;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _parsePublishedToSource: typeof SourceParse = {} as typeof PublishedParse;
-
-// Custom macro API: the published MacroContext/MacroDefinition must match the
-// ones defineMacro() actually passes and accepts.
 import type {
   MacroContext as SourceMacroContext,
   MacroDefinition as SourceMacroDefinition,
 } from './define-macro';
 import type { MacroProps as SourceMacroProps } from './registry';
 import type { ASTNode as SourceASTNode } from './markup/ast';
+import type { bootStory as SourceBootStory } from './headless';
 import type {
+  StoryAPI as PublishedAPI,
   MacroContext as PublishedMacroContext,
   MacroDefinition as PublishedMacroDefinition,
   MacroProps as PublishedMacroProps,
   ASTNode as PublishedASTNode,
 } from '../types/index';
+import type { parseStoryVariables as PublishedParse } from '../types/tooling';
+import type { bootStory as PublishedBootStory } from '../types/headless';
 
+/** What the source declares, by published name. */
+interface Source {
+  StoryAPI: SourceAPI;
+  // Tooling entry point (`@rohal12/spindle/tooling`): the parser that
+  // dist/pkg/tooling.js re-exports.
+  parseStoryVariables: typeof SourceParse;
+  // Custom macro API: the MacroContext/MacroDefinition defineMacro()
+  // actually passes and accepts.
+  MacroContext: SourceMacroContext;
+  MacroDefinition: SourceMacroDefinition;
+  MacroProps: SourceMacroProps;
+  ASTNode: SourceASTNode;
+  // Headless entry point (`@rohal12/spindle/headless`).
+  bootStory: typeof SourceBootStory;
+}
+
+/** What types/index.d.ts, tooling.d.ts and headless.d.ts publish. */
+interface Published {
+  StoryAPI: PublishedAPI;
+  parseStoryVariables: typeof PublishedParse;
+  MacroContext: PublishedMacroContext;
+  MacroDefinition: PublishedMacroDefinition;
+  MacroProps: PublishedMacroProps;
+  ASTNode: PublishedASTNode;
+  bootStory: typeof PublishedBootStory;
+}
+
+// Both directions — if either fails, the types have drifted.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _ctxSourceToPublished: PublishedMacroContext = {} as SourceMacroContext;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _ctxPublishedToSource: SourceMacroContext = {} as PublishedMacroContext;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _defSourceToPublished: PublishedMacroDefinition =
-  {} as SourceMacroDefinition;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _defPublishedToSource: SourceMacroDefinition =
-  {} as PublishedMacroDefinition;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _propsSourceToPublished: PublishedMacroProps = {} as SourceMacroProps;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _propsPublishedToSource: SourceMacroProps = {} as PublishedMacroProps;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _astSourceToPublished: PublishedASTNode = {} as SourceASTNode;
+const _sourceToPublished: Published = {} as Source;
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _astPublishedToSource: SourceASTNode = {} as PublishedASTNode;
+const _publishedToSource: Source = {} as Published;
 
 // A typical custom macro written against the published types must type-check,
 // and misuse of the hooks must not (no `any` leaking through).
@@ -91,15 +90,3 @@ const _exampleMacro: PublishedMacroDefinition = {
     );
   },
 };
-
-// Headless entry point (`@rohal12/spindle/headless`): types/headless.d.ts must
-// match src/headless.ts.
-import type { bootStory as SourceBootStory } from './headless';
-import type { bootStory as PublishedBootStory } from '../types/headless';
-
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _bootSourceToPublished: typeof PublishedBootStory =
-  {} as typeof SourceBootStory;
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-const _bootPublishedToSource: typeof SourceBootStory =
-  {} as typeof PublishedBootStory;

package/src/utils/macro-names.ts

@@ -0,0 +1,40 @@
+/**
+ * Macro and widget names are case-insensitive: `{StatusBar}` invokes the
+ * widget defined as `statusbar`. A NameMap keys its entries by the lowercased
+ * name.
+ */
+export class NameMap<V> extends Map<string, V> {
+  override get(name: string): V | undefined {
+    return super.get(name.toLowerCase());
+  }
+  override set(name: string, value: V): this {
+    return super.set(name.toLowerCase(), value);
+  }
+  override has(name: string): boolean {
+    return super.has(name.toLowerCase());
+  }
+  override delete(name: string): boolean {
+    return super.delete(name.toLowerCase());
+  }
+}
+
+/** A set of macro or widget names (see NameMap). */
+export class NameSet {
+  private readonly names = new NameMap<true>();
+
+  constructor(names: Iterable<string> = []) {
+    for (const name of names) this.add(name);
+  }
+
+  add(name: string): void {
+    this.names.set(name, true);
+  }
+
+  has(name: string): boolean {
+    return this.names.has(name);
+  }
+
+  delete(name: string): void {
+    this.names.delete(name);
+  }
+}

package/src/utils/namespace.ts

@@ -48,6 +48,23 @@ export const ownValue = (
   key: string,
 ): unknown => (ns && hasOwn(ns, key) ? (ns as Namespace)[key] : undefined);
 
+/**
+ * Set an own enumerable property. A "__proto__" key is defined as an own
+ * property (as JSON.parse does) instead of replacing the prototype.
+ */
+export function setOwn(target: object, key: string, value: unknown): void {
+  if (key === '__proto__') {
+    Object.defineProperty(target, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  } else {
+    (target as Record<string, unknown>)[key] = value;
+  }
+}
+
 /**
  * A record with no prototype holding the own entries of `sources`, or only
  * those whose value passes `keep`.

package/src/widgets/widget-registry.ts

@@ -1,5 +1,6 @@
 import type { ASTNode } from '../markup/ast';
 import { checkVariableName } from '../utils/namespace';
+import { NameMap } from '../utils/macro-names';
 
 interface WidgetEntry {
   body: ASTNode[];
@@ -7,7 +8,7 @@ interface WidgetEntry {
   isBlock: boolean;
 }
 
-const widgets = new Map<string, WidgetEntry>();
+const widgets = new NameMap<WidgetEntry>();
 
 /**
  * Register a widget. Its `@` parameters become locals of its body, so one
@@ -24,7 +25,7 @@ export function registerWidget(
   for (const param of filteredParams) {
     if (param.startsWith('@')) checkVariableName(param.slice(1), param);
   }
-  widgets.set(name.toLowerCase(), {
+  widgets.set(name, {
     body: bodyAST,
     params: filteredParams,
     isBlock,
@@ -32,11 +33,11 @@ export function registerWidget(
 }
 
 export function getWidget(name: string): WidgetEntry | undefined {
-  return widgets.get(name.toLowerCase());
+  return widgets.get(name);
 }
 
 export function isBlockWidget(name: string): boolean {
-  return widgets.get(name.toLowerCase())?.isBlock ?? false;
+  return widgets.get(name)?.isBlock ?? false;
 }
 
 export function clearWidgets(): void {