preact-sigma 5.0.0 → 6.0.0

package/docs/persist.md

@@ -2,11 +2,11 @@
 
 ## Overview
 
-`preact-sigma/persist` persists and restores committed top-level sigma state without moving storage, scheduling, or migration policy into `SigmaType`.
+`preact-sigma/persist` persists and restores committed top-level sigma state without moving storage, scheduling, or migration policy into `Sigma` classes.
 
 The module builds on the core committed-state helpers:
 
-- `sigma.getState(instance)` reads the current committed snapshot.
+- `sigma.captureState(instance)` reads the current committed snapshot.
 - `sigma.replaceState(instance, nextState)` restores a committed snapshot.
 - `sigma.subscribe(instance, handler)` observes future committed publishes.
 
@@ -15,52 +15,53 @@ Use the persist module when those primitives are the right boundary, but you do
 ## When to Use
 
 - State should survive reloads, navigation, or app restarts.
-- Persistence needs to stay instance-specific instead of becoming part of the model definition.
+- Persistence needs to stay instance-specific instead of becoming part of the model class.
 - Storage may be synchronous or asynchronous.
 - Stored payloads need versioning, migration, or partial persistence.
 - Restore and future persistence should share one small lifecycle helper.
 
 ## When Not to Use
 
-- A one-off snapshot or replay flow is enough. Use `sigma.getState(...)` and `sigma.replaceState(...)` directly.
+- A one-off snapshot or replay flow is enough. Use `sigma.captureState(...)` and `sigma.replaceState(...)` directly.
 - The data is really a remote cache, normalization layer, or conflict-resolution problem.
 - You need unpublished drafts, computeds, queries, setup resources, or emitted events persisted.
 - The model should start side effects before async restore completes. Sequence that explicitly outside `useSigma(...)`.
 
 ## Core Pieces
 
-- Store: owns `read`, `write`, and `remove` for persisted records.
+- Store: owns `get`, `set`, and `delete` for persisted records. These names match [Keyv](https://github.com/jaredwray/keyv) and `Map`.
 - Codec: owns payload shape, versioning, and migration logic between stored data and a full committed snapshot.
-- Helper: owns restore sequencing, subscription lifecycle, and write scheduling for one sigma-state instance.
+- Pick options: persist selected top-level keys without writing a custom codec.
+- Helper: owns restore sequencing, subscription lifecycle, and write scheduling for one sigma instance.
 
 ## Common Tasks -> Recommended APIs
 
-- Restore once through an async store: `restoreState(instance, options)`
-- Restore once through a sync store: `restoreStateSync(instance, options)`
-- Persist future committed changes only: `persistState(instance, options)`
-- Restore first, then persist future changes: `bindPersistence(instance, options)` or `bindPersistenceSync(instance, options)`
-- Persist only selected top-level keys while restoring the full state shape: `pickStateCodec(keys)`
+- Restore once through an async store: `restore(instance, options)`
+- Restore once through a sync store: `restoreSync(instance, options)`
+- Persist future committed changes only: `persist(instance, options)`
+- Restore first, then persist future changes: `hydrate(instance, options)` or `hydrateSync(instance, options)`
+- Persist only selected top-level keys while restoring the full state shape: pass `pick: ["key"]`
 
 ## Scheduling and Lifecycle
 
 - Persistence helpers only read and write committed snapshots. Unpublished drafts never reach storage.
-- `persistState(...)` defaults to `"microtask"` scheduling so multiple same-turn publishes can coalesce into one write.
+- `persist(...)` defaults to `"microtask"` scheduling so multiple same-turn publishes can coalesce into one write.
 - `writeInitial` defaults to `false`, which prevents a new binding from overwriting an older record before restore runs.
 - `flush()` waits for scheduled or active writes to finish.
 - `clear()` removes the stored record and keeps the binding usable for later writes.
-- `stop()` unsubscribes the binding and waits for any in-flight write to settle.
-- `bindPersistence(...)` starts future persistence only after restore resolves successfully.
+- `stop()` unsubscribes the binding, cancels unwritten scheduled state, and waits for any active write to settle.
+- `hydrate(...)` starts future persistence only after restore resolves successfully.
 
 ## Constraints
 
-- `sigma.replaceState(...)` still requires a plain object with the exact top-level state-key shape.
-- Partial persistence codecs must reconstruct a full replacement snapshot before restore finishes.
+- `sigma.replaceState(...)` requires a plain object replacement snapshot. In supported TypeScript usage, pass the class's full `TState` shape.
+- Custom partial persistence codecs should reconstruct a full replacement snapshot before restore finishes.
 - Nested sigma-state values are stored only if the chosen codec and payload format support them explicitly.
-- Async restore failures reject through `restoreState(...)` or the `restored` promise from `bindPersistence(...)`.
+- Async restore failures reject through `restore(...)` or the `restored` promise from `hydrate(...)`.
 - Background write failures route through `onWriteError(...)` without automatically stopping persistence.
 
 ## Example Routes
 
-- [`examples/persist-search-draft.ts`](../examples/persist-search-draft.ts): sync restore-first persistence with `bindPersistenceSync(...)` and `pickStateCodec(...)`
+- [`examples/persist-search-draft.ts`](../examples/persist-search-draft.ts): sync restore-first persistence with `hydrateSync(...)` and `pick`
 - [`examples/observe-and-restore.ts`](../examples/observe-and-restore.ts): direct snapshot and restore without the persist subpath
 - [`dist/persist.d.mts`](../dist/persist.d.mts): exact exported signatures for the persist module

package/examples/async-commit.ts

@@ -1,38 +1,43 @@
-import { listen, SigmaType } from "preact-sigma";
-
-const SaveIndicator = new SigmaType<
-  {
-    savedCount: number;
-    saving: boolean;
-  },
-  {
-    saved: {
-      count: number;
-    };
+import { listen, SigmaTarget } from "preact-sigma";
+
+type SaveIndicatorState = {
+  savedCount: number;
+  saving: boolean;
+};
+
+type SaveIndicatorEvents = {
+  saved: {
+    count: number;
+  };
+};
+
+class SaveIndicator extends SigmaTarget<SaveIndicatorEvents, SaveIndicatorState> {
+  constructor() {
+    super({
+      savedCount: 0,
+      saving: false,
+    });
   }
->("SaveIndicator")
-  .defaultState({
-    savedCount: 0,
-    saving: false,
-  })
-  .actions({
-    async save() {
-      this.saving = true;
-      this.commit(); // Publish before the async boundary.
-
-      await Promise.resolve();
-
-      this.savedCount += 1;
-      this.saving = false;
-      this.commit(); // Publish before emitting the event boundary.
-
-      this.emit("saved", { count: this.savedCount });
-    },
-  });
+
+  async save() {
+    this.saving = true;
+    this.commit(); // Publish before the async boundary.
+
+    await Promise.resolve();
+
+    this.savedCount += 1;
+    this.saving = false;
+    this.commit(); // Publish before emitting the event boundary.
+
+    this.emit("saved", { count: this.savedCount });
+  }
+}
+
+interface SaveIndicator extends SaveIndicatorState {}
 
 const indicator = new SaveIndicator();
 
-listen(indicator, "saved", ({ count }) => {
+const stop = listen(indicator, "saved", ({ count }) => {
   console.log(`Saved ${count} times`);
 });
 
@@ -40,3 +45,5 @@ await indicator.save();
 
 console.log(indicator.saving); // false
 console.log(indicator.savedCount); // 1
+
+stop();

package/examples/basic-counter.ts

@@ -1,19 +1,24 @@
-import { SigmaType } from "preact-sigma";
-
-const Counter = new SigmaType<{ count: number }>("Counter")
-  .defaultState({
-    count: 0,
-  })
-  .computed({
-    doubled() {
-      return this.count * 2;
-    },
-  })
-  .actions({
-    increment() {
-      this.count += 1;
-    },
-  });
+import { Sigma } from "preact-sigma";
+
+type CounterState = { count: number };
+
+class Counter extends Sigma<CounterState> {
+  constructor() {
+    super({
+      count: 0,
+    });
+  }
+
+  get doubled() {
+    return this.count * 2;
+  }
+
+  increment() {
+    this.count += 1;
+  }
+}
+
+interface Counter extends CounterState {}
 
 const counter = new Counter();
 

package/examples/command-palette.tsx

@@ -1,6 +1,6 @@
 import { useState } from "preact/hooks";
 
-import { listen, query, SigmaType, useListener, useSigma } from "preact-sigma";
+import { listen, query, Sigma, SigmaTarget, useListener, useSigma } from "preact-sigma";
 
 type Command = {
   id: string;
@@ -9,18 +9,18 @@ type Command = {
 };
 
 class UsageLedger {
-  counts = new Map<string, number>();
+  #counts = new Map<string, number>();
 
   get(id: string) {
-    return this.counts.get(id) ?? 0;
+    return this.#counts.get(id) ?? 0;
   }
 
   increment(id: string) {
-    this.counts.set(id, this.get(id) + 1);
+    this.#counts.set(id, this.get(id) + 1);
   }
 }
 
-const matchesText = query((command: Command, draft: string) => {
+function matchesText(command: Command, draft: string) {
   const needle = draft.trim().toLowerCase();
   if (!needle) {
     return true;
@@ -30,101 +30,115 @@ const matchesText = query((command: Command, draft: string) => {
     command.title.toLowerCase().includes(needle) ||
     command.keywords.some((keyword) => keyword.toLowerCase().includes(needle))
   );
-});
+}
 
-const SearchHistory = new SigmaType<{
+type SearchHistoryState = {
   items: string[];
-}>("SearchHistory")
-  .defaultState({
-    items: [],
-  })
-  .actions({
-    remember(query: string) {
-      const value = query.trim();
-      if (!value) {
-        return;
-      }
-
-      this.items = [value, ...this.items.filter((item) => item !== value)].slice(0, 5);
-    },
-  });
+};
 
-interface SearchHistory extends InstanceType<typeof SearchHistory> {}
-
-const CommandPalette = new SigmaType<
-  {
-    commands: Command[];
-    cursor: number;
-    draft: string;
-    history: SearchHistory;
-    usage: UsageLedger;
-  },
-  {
-    ran: Command;
+class SearchHistory extends Sigma<SearchHistoryState> {
+  constructor() {
+    super({
+      items: [],
+    });
   }
->("CommandPalette")
-  .defaultState({
-    commands: [
-      { id: "inbox", title: "Open inbox", keywords: ["mail", "messages", "triage"] },
-      { id: "capture", title: "Capture note", keywords: ["write", "quick", "idea"] },
-      { id: "focus", title: "Start focus timer", keywords: ["pomodoro", "deep work"] },
-      { id: "theme", title: "Toggle theme", keywords: ["appearance", "dark", "light"] },
-    ],
-    cursor: 0,
-    draft: "",
-    history: () => new SearchHistory(),
-    usage: () => new UsageLedger(),
-  })
-  .computed({
-    visibleCommands() {
-      return this.commands.filter((command) => matchesText(command, this.draft));
-    },
-    activeCommand() {
-      return this.visibleCommands[this.cursor] ?? null;
-    },
-  })
-  .queries({
-    canRun() {
-      return this.activeCommand !== null;
-    },
-    usageCount(id: string) {
-      return this.usage.get(id);
-    },
-  })
-  .actions({
-    setDraft(draft: string) {
-      this.draft = draft;
-      this.cursor = 0;
-    },
-    move(step: number) {
-      if (this.visibleCommands.length === 0) {
-        this.cursor = 0;
-        return;
-      }
-
-      const lastIndex = this.visibleCommands.length - 1;
-      this.cursor = Math.max(0, Math.min(lastIndex, this.cursor + step));
-    },
-    seedDraftFromHistory() {
-      const latest = this.history.items[0];
-      if (latest) {
-        this.setDraft(latest);
-      }
-    },
-    runActive() {
-      const command = this.activeCommand;
-      if (!command || !this.canRun()) {
-        return;
-      }
-
-      this.history.remember(this.draft || command.title);
-      this.usage.increment(command.id);
-      this.emit("ran", command);
-      this.draft = "";
+
+  remember(query: string) {
+    const value = query.trim();
+    if (!value) {
+      return;
+    }
+
+    this.items = [value, ...this.items.filter((item) => item !== value)].slice(0, 5);
+  }
+}
+
+interface SearchHistory extends SearchHistoryState {}
+
+type CommandPaletteState = {
+  commands: Command[];
+  cursor: number;
+  draft: string;
+  history: SearchHistory;
+  usage: UsageLedger;
+};
+
+type CommandPaletteEvents = {
+  ran: Command;
+};
+
+class CommandPalette extends SigmaTarget<CommandPaletteEvents, CommandPaletteState> {
+  constructor() {
+    super({
+      commands: [
+        { id: "inbox", title: "Open inbox", keywords: ["mail", "messages", "triage"] },
+        { id: "capture", title: "Capture note", keywords: ["write", "quick", "idea"] },
+        { id: "focus", title: "Start focus timer", keywords: ["pomodoro", "deep work"] },
+        { id: "theme", title: "Toggle theme", keywords: ["appearance", "dark", "light"] },
+      ],
+      cursor: 0,
+      draft: "",
+      history: new SearchHistory(),
+      usage: new UsageLedger(),
+    });
+  }
+
+  get visibleCommands() {
+    return this.commands.filter((command) => matchesText(command, this.draft));
+  }
+
+  get activeCommand() {
+    return this.visibleCommands[this.cursor] ?? null;
+  }
+
+  get canRun() {
+    return this.activeCommand !== null;
+  }
+
+  @query
+  usageCount(id: string) {
+    return this.usage.get(id);
+  }
+
+  setDraft(draft: string) {
+    this.draft = draft;
+    this.cursor = 0;
+  }
+
+  move(step: number) {
+    if (this.visibleCommands.length === 0) {
       this.cursor = 0;
-    },
-  })
-  .setup(function () {
+      return;
+    }
+
+    const lastIndex = this.visibleCommands.length - 1;
+    this.cursor = Math.max(0, Math.min(lastIndex, this.cursor + step));
+  }
+
+  seedDraftFromHistory() {
+    const latest = this.history.items[0];
+    if (latest) {
+      this.setDraft(latest);
+    }
+  }
+
+  runActive() {
+    const command = this.activeCommand;
+    if (!command) {
+      return;
+    }
+
+    const search = this.draft || command.title;
+    this.usage.increment(command.id);
+    this.draft = "";
+    this.cursor = 0;
+    this.commit();
+
+    this.history.remember(search);
+    this.emit("ran", command);
+  }
+
+  onSetup() {
     return [
       listen(window, "keydown", (event) => {
         if ((event.metaKey || event.ctrlKey) && event.key === "k") {
@@ -144,9 +158,10 @@ const CommandPalette = new SigmaType<
         }
       }),
     ];
-  });
+  }
+}
 
-interface CommandPalette extends InstanceType<typeof CommandPalette> {}
+interface CommandPalette extends CommandPaletteState {}
 
 export function CommandPaletteExample() {
   const palette = useSigma(() => new CommandPalette());
@@ -158,16 +173,11 @@ export function CommandPaletteExample() {
 
   return (
     <section>
-      <p>
-        <strong>Command palette</strong>: setup-owned keyboard shortcuts, computed getters, tracked
-        queries with args, typed events, nested sigma state, and a mutable custom class instance.
-      </p>
-
       <label>
         Search
         <input
           value={palette.draft}
-          onInput={(event) => palette.setDraft((event.currentTarget as HTMLInputElement).value)}
+          onInput={(event) => palette.setDraft(event.currentTarget.value)}
           placeholder="Try: note, timer, inbox"
         />
       </label>
@@ -179,7 +189,7 @@ export function CommandPaletteExample() {
         <button type="button" onClick={() => palette.move(1)}>
           Down
         </button>
-        <button type="button" onClick={() => palette.runActive()} disabled={!palette.canRun()}>
+        <button type="button" onClick={() => palette.runActive()} disabled={!palette.canRun}>
           Run
         </button>
       </div>

package/examples/observe-and-restore.ts

@@ -1,29 +1,35 @@
-import { sigma, SigmaType } from "preact-sigma";
+import { sigma, Sigma } from "preact-sigma";
 
-const TodoList = new SigmaType<{
+type TodoListState = {
   todos: string[];
-}>("TodoList")
-  .defaultState({
-    todos: [],
-  })
-  .actions({
-    add(title: string) {
-      this.todos.push(title);
-    },
-  });
+};
+
+class TodoList extends Sigma<TodoListState> {
+  constructor() {
+    super({
+      todos: [],
+    });
+  }
+
+  add(title: string) {
+    this.todos.push(title);
+  }
+}
+
+interface TodoList extends TodoListState {}
 
 const todoList = new TodoList();
-const stop = sigma.subscribe(todoList, (change) => {
-  console.log(`${change.oldState.todos.length} -> ${change.newState.todos.length}`);
+const stop = sigma.subscribe(todoList, (nextState, baseState) => {
+  console.log(`${baseState.todos.length} -> ${nextState.todos.length}`);
 });
 
 todoList.add("Write docs");
 
-const saved = sigma.getState(todoList);
+const saved = sigma.captureState(todoList);
 
 todoList.add("Ship release");
 sigma.replaceState(todoList, saved);
 
-console.log(sigma.getState(todoList).todos); // ["Write docs"]
+console.log(sigma.captureState(todoList).todos); // ["Write docs"]
 
 stop();

package/examples/persist-search-draft.ts

@@ -1,29 +1,32 @@
-import { SigmaType } from "preact-sigma";
-import {
-  bindPersistenceSync,
-  pickStateCodec,
-  type PersistRecord,
-  type SyncPersistStore,
-} from "preact-sigma/persist";
+import { Sigma } from "preact-sigma";
+import { hydrateSync, type PersistRecord, type SyncPersistStore } from "preact-sigma/persist";
 
-const Search = new SigmaType<{
+type SearchState = {
   draft: string;
   page: number;
-}>("Search")
-  .defaultState({
-    draft: "",
-    page: 1,
-  })
-  .actions({
-    nextPage() {
-      this.page += 1;
-    },
-    setDraft(draft: string) {
-      this.draft = draft;
-    },
-  });
+};
+
+class Search extends Sigma<SearchState> {
+  constructor(initialState: Partial<SearchState> = {}) {
+    super({
+      draft: "",
+      page: 1,
+      ...initialState,
+    });
+  }
+
+  nextPage() {
+    this.page += 1;
+  }
+
+  setDraft(draft: string) {
+    this.draft = draft;
+  }
+}
+
+interface Search extends SearchState {}
 
-const records = new Map<string, PersistRecord<{ draft: string }>>([
+const records = new Map<string, PersistRecord<Pick<SearchState, "draft">>>([
   [
     "search",
     {
@@ -34,22 +37,22 @@ const records = new Map<string, PersistRecord<{ draft: string }>>([
   ],
 ]);
 
-const store: SyncPersistStore<PersistRecord<{ draft: string }>> = {
-  read(key) {
+const store: SyncPersistStore<Pick<SearchState, "draft">> = {
+  get(key) {
     return records.get(key);
   },
-  write(key, record) {
-    records.set(key, record);
+  set(key, record) {
+    return records.set(key, record);
   },
-  remove(key) {
-    records.delete(key);
+  delete(key) {
+    return records.delete(key);
   },
 };
 
 const search = new Search({ page: 3 });
-const persistence = bindPersistenceSync(search, {
-  codec: pickStateCodec(["draft"]),
+const persistence = hydrateSync(search, {
   key: "search",
+  pick: ["draft"],
   store,
 });
 

package/examples/setup-act.ts

@@ -1,14 +1,19 @@
-import { listen, SigmaType } from "preact-sigma";
+import { listen, Sigma } from "preact-sigma";
 
-const ClickTracker = new SigmaType<{
+type ClickTrackerState = {
   clicks: number;
   status: "idle" | "ready";
-}>("ClickTracker")
-  .defaultState({
-    clicks: 0,
-    status: "idle",
-  })
-  .setup(function (target: EventTarget) {
+};
+
+class ClickTracker extends Sigma<ClickTrackerState> {
+  constructor() {
+    super({
+      clicks: 0,
+      status: "idle",
+    });
+  }
+
+  onSetup(target: EventTarget) {
     this.act(function () {
       this.status = "ready";
     });
@@ -20,7 +25,10 @@ const ClickTracker = new SigmaType<{
         });
       }),
     ];
-  });
+  }
+}
+
+interface ClickTracker extends ClickTrackerState {}
 
 const target = new EventTarget();
 const tracker = new ClickTracker();