preact-sigma 5.0.0 → 6.0.1

package/docs/migrations/v5-to-v6.md

@@ -0,0 +1,273 @@
+# Migrating from v5 to v6
+
+v6 replaces the `SigmaType` builder with class-based models. The runtime contract is still centered on top-level reactive state, derived reads, explicit actions, setup-owned side effects, typed events, and committed snapshots.
+
+## Model Definitions
+
+Define a class that extends `Sigma<TState>` instead of building a configured `SigmaType`.
+
+Before:
+
+```ts
+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;
+    },
+  });
+```
+
+After:
+
+```ts
+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 {}
+```
+
+`TState` drives helper typing for subscriptions, signals, and replacement snapshots. The same-named merged interface gives direct state property reads their instance types.
+
+## Constructor Defaults
+
+Constructor input is ordinary TypeScript now. Use `mergeDefaults(...)` when an instance accepts partial initial state.
+
+```ts
+import { mergeDefaults, Sigma } from "preact-sigma";
+
+type SearchState = {
+  draft: string;
+  page: number;
+};
+
+class Search extends Sigma<SearchState> {
+  static defaultState: SearchState = {
+    draft: "",
+    page: 1,
+  };
+
+  constructor(initialState?: Partial<SearchState>) {
+    super(mergeDefaults(initialState, Search.defaultState));
+  }
+}
+
+interface Search extends SearchState {}
+```
+
+## Computeds, Queries, and Actions
+
+Use class getters for argument-free computed reads. Use ordinary prototype methods for actions. Computeds and queries read committed state, including when called inside actions.
+
+Argument-based reactive reads are class methods marked with `@query`.
+
+```ts
+import { query, Sigma } from "preact-sigma";
+
+type TodoListState = {
+  draft: string;
+};
+
+class TodoList extends Sigma<TodoListState> {
+  constructor() {
+    super({ draft: "" });
+  }
+
+  @query
+  canAdd(minLength: number) {
+    return this.draft.trim().length >= minLength;
+  }
+
+  setDraft(draft: string) {
+    this.draft = draft;
+  }
+}
+
+interface TodoList extends TodoListState {}
+```
+
+## Events
+
+`SigmaTarget` now takes event types first. Use `SigmaTarget<TEvents>` for event-only targets and `SigmaTarget<TEvents, TState>` for targets that also own state.
+
+```ts
+import { listen, SigmaTarget } from "preact-sigma";
+
+type NotificationEvents = {
+  saved: {
+    id: string;
+  };
+};
+
+class Notifications extends SigmaTarget<NotificationEvents> {
+  saved(id: string) {
+    this.emit("saved", { id });
+  }
+}
+
+const notifications = new Notifications();
+
+const stop = listen(notifications, "saved", ({ id }) => {
+  console.log(id);
+});
+```
+
+`emit(...)` runs inside actions. If an action mutates state before emitting, publish first with `this.commit()`.
+
+## Commit Boundaries
+
+Synchronous actions publish automatically when they return. Call `this.commit()` only when unpublished changes cross a boundary:
+
+- before `await`
+- before an async action promise resolves
+- before `emit(...)`
+- before invoking another instance's action
+
+```ts
+type SaveIndicatorState = {
+  savedCount: number;
+  saving: boolean;
+};
+
+type SaveIndicatorEvents = {
+  saved: {
+    count: number;
+  };
+};
+
+class SaveIndicator extends SigmaTarget<SaveIndicatorEvents, SaveIndicatorState> {
+  constructor() {
+    super({
+      savedCount: 0,
+      saving: false,
+    });
+  }
+
+  async save() {
+    this.saving = true;
+    this.commit();
+
+    await Promise.resolve();
+
+    this.savedCount += 1;
+    this.saving = false;
+    this.commit();
+
+    this.emit("saved", { count: this.savedCount });
+  }
+}
+
+interface SaveIndicator extends SaveIndicatorState {}
+```
+
+## Setup
+
+Replace builder setup with an `onSetup(...)` method. Call `setup(...)` manually outside Preact, or use `useSigma(...)` for component-owned instances.
+
+```ts
+import { listen, Sigma } from "preact-sigma";
+
+type ClickTrackerState = {
+  clicks: number;
+};
+
+class ClickTracker extends Sigma<ClickTrackerState> {
+  constructor() {
+    super({ clicks: 0 });
+  }
+
+  onSetup(target: EventTarget) {
+    return [
+      listen(target, "click", () => {
+        this.act(function () {
+          this.clicks += 1;
+        });
+      }),
+    ];
+  }
+}
+
+interface ClickTracker extends ClickTrackerState {}
+```
+
+## Protected Views
+
+The instance method `protect()` is gone. Use `castProtected(instance)` outside components, and use `useSigma(...)` inside components.
+
+```ts
+import { castProtected } from "preact-sigma";
+
+const publicCounter = castProtected(new Counter());
+```
+
+Protected sigma targets keep their event metadata, so `useListener(...)` works directly with the value returned by `useSigma(...)`.
+
+```tsx
+const palette = useSigma(() => new CommandPalette());
+
+useListener(palette, "ran", (command) => {
+  console.log(command.title);
+});
+```
+
+## Committed State Helpers
+
+Replace `sigma.getState(...)` with `sigma.captureState(...)`.
+
+```ts
+const saved = sigma.captureState(todoList);
+
+todoList.add("Ship release");
+sigma.replaceState(todoList, saved);
+```
+
+Use `sigma.subscribe(instance, listener)` for committed state publishes and `sigma.subscribe(instance, key, listener)` for one top-level state key.
+
+## Persistence
+
+The `preact-sigma/persist` helpers are named around restore, persist, and hydrate flows:
+
+- `restore(instance, options)`
+- `restoreSync(instance, options)`
+- `persist(instance, options)`
+- `hydrate(instance, options)`
+- `hydrateSync(instance, options)`
+
+Use `pick: ["key"]` options for selected top-level state keys instead of a separate pick codec helper.
+
+See [`../persist.md`](../persist.md) for persistence-specific guidance.
+
+## More References
+
+- [`../context.md`](../context.md): concepts, lifecycle, invariants, and API selection
+- [`../../examples/basic-counter.ts`](../../examples/basic-counter.ts): minimal class model
+- [`../../examples/command-palette.tsx`](../../examples/command-palette.tsx): component usage, setup, events, nested state, and custom helper objects
+- `dist/index.d.mts` and `dist/persist.d.mts` after `pnpm build`: exact exported signatures

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();