preact-sigma 4.0.0 → 5.0.0

package/docs/persist.md

@@ -0,0 +1,66 @@
+# Persist
+
+## Overview
+
+`preact-sigma/persist` persists and restores committed top-level sigma state without moving storage, scheduling, or migration policy into `SigmaType`.
+
+The module builds on the core committed-state helpers:
+
+- `sigma.getState(instance)` reads the current committed snapshot.
+- `sigma.replaceState(instance, nextState)` restores a committed snapshot.
+- `sigma.subscribe(instance, handler)` observes future committed publishes.
+
+Use the persist module when those primitives are the right boundary, but you do not want each application to reimplement store adapters, partial persistence, restore sequencing, or write scheduling. Exact signatures live in [`dist/persist.d.mts`](../dist/persist.d.mts).
+
+## 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.
+- 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.
+- 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.
+- 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.
+
+## 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)`
+
+## 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.
+- `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.
+
+## 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.
+- 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(...)`.
+- 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/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,4 +1,4 @@
-import { SigmaType } from "preact-sigma";
+import { listen, SigmaType } from "preact-sigma";
 
 const SaveIndicator = new SigmaType<
   {
@@ -32,7 +32,7 @@ const SaveIndicator = new SigmaType<
 
 const indicator = new SaveIndicator();
 
-indicator.on("saved", ({ count }) => {
+listen(indicator, "saved", ({ count }) => {
   console.log(`Saved ${count} times`);
 });
 

package/examples/observe-and-restore.ts

@@ -1,4 +1,4 @@
-import { replaceState, SigmaType, snapshot } from "preact-sigma";
+import { sigma, SigmaType } from "preact-sigma";
 
 const TodoList = new SigmaType<{
   todos: string[];
@@ -6,9 +6,6 @@ const TodoList = new SigmaType<{
   .defaultState({
     todos: [],
   })
-  .observe(function (change) {
-    console.log(`${change.oldState.todos.length} -> ${change.newState.todos.length}`);
-  })
   .actions({
     add(title: string) {
       this.todos.push(title);
@@ -16,12 +13,17 @@ const TodoList = new SigmaType<{
   });
 
 const todoList = new TodoList();
+const stop = sigma.subscribe(todoList, (change) => {
+  console.log(`${change.oldState.todos.length} -> ${change.newState.todos.length}`);
+});
 
 todoList.add("Write docs");
 
-const saved = snapshot(todoList);
+const saved = sigma.getState(todoList);
 
 todoList.add("Ship release");
-replaceState(todoList, saved);
+sigma.replaceState(todoList, saved);
+
+console.log(sigma.getState(todoList).todos); // ["Write docs"]
 
-console.log(snapshot(todoList).todos); // ["Write docs"]
+stop();

package/examples/persist-search-draft.ts

@@ -0,0 +1,67 @@
+import { SigmaType } from "preact-sigma";
+import {
+  bindPersistenceSync,
+  pickStateCodec,
+  type PersistRecord,
+  type SyncPersistStore,
+} from "preact-sigma/persist";
+
+const Search = new SigmaType<{
+  draft: string;
+  page: number;
+}>("Search")
+  .defaultState({
+    draft: "",
+    page: 1,
+  })
+  .actions({
+    nextPage() {
+      this.page += 1;
+    },
+    setDraft(draft: string) {
+      this.draft = draft;
+    },
+  });
+
+const records = new Map<string, PersistRecord<{ draft: string }>>([
+  [
+    "search",
+    {
+      savedAt: 100,
+      value: { draft: "restored" },
+      version: 1,
+    },
+  ],
+]);
+
+const store: SyncPersistStore<PersistRecord<{ draft: string }>> = {
+  read(key) {
+    return records.get(key);
+  },
+  write(key, record) {
+    records.set(key, record);
+  },
+  remove(key) {
+    records.delete(key);
+  },
+};
+
+const search = new Search({ page: 3 });
+const persistence = bindPersistenceSync(search, {
+  codec: pickStateCodec(["draft"]),
+  key: "search",
+  store,
+});
+
+console.log(persistence.restored); // { status: "restored", savedAt: 100, storedVersion: 1 }
+console.log(search.draft); // "restored"
+console.log(search.page); // 3
+
+search.setDraft("signals");
+search.nextPage();
+
+await persistence.flush();
+
+console.log(records.get("search")?.value); // { draft: "signals" }
+
+await persistence.stop();

package/examples/sigma-target.ts

@@ -8,7 +8,7 @@ const notifications = new SigmaTarget<{
   reset: void;
 }>();
 
-const stopSaved = notifications.on("saved", ({ id, title }) => {
+const stopSaved = listen(notifications, "saved", ({ id, title }) => {
   console.log(`Saved ${id}: ${title}`);
 });
 

package/examples/signal-access.ts

@@ -1,4 +1,4 @@
-import { effect, SigmaType } from "preact-sigma";
+import { effect, sigma, SigmaType } from "preact-sigma";
 
 const Counter = new SigmaType<{
   count: number;
@@ -20,7 +20,10 @@ const Counter = new SigmaType<{
 const counter = new Counter();
 
 const stop = effect(() => {
-  console.log(counter.get("count").value, counter.get("doubled").value);
+  console.log(
+    sigma.getSignal(counter, "count").value,
+    sigma.getSignal(counter, "doubled").value,
+  );
 });
 
 counter.increment();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",
@@ -18,8 +18,20 @@
     ".": {
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
+    },
+    "./persist": {
+      "types": "./dist/persist.d.mts",
+      "import": "./dist/persist.mjs"
     }
   },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
+    "fmt": "oxfmt",
+    "lint": "oxlint",
+    "prepublishOnly": "pnpm build"
+  },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.5",
     "@types/node": "^25.5.0",
@@ -37,12 +49,5 @@
     "@preact/signals": ">=2",
     "immer": ">=11",
     "preact": ">=10"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
-    "fmt": "oxfmt",
-    "lint": "oxlint"
   }
-}
+}