preact-sigma 1.0.1 → 2.0.1

package/README.md

@@ -1,509 +1,168 @@
-# `preact-sigma`
+# preact-sigma
 
-Managed UI state for Preact Signals, with Immer-powered updates and a small public API.
+`preact-sigma` is a typed state-model builder for apps that want Preact's fine-grained reactivity, Immer-backed writes, and explicit lifecycle.
 
-For naming and API design conventions, see [best-practices.md](./best-practices.md).
+You define a reusable state type once, then create instances wherever they make sense: inside components, in shared modules, or in plain TypeScript code. Each instance exposes readonly public state, tracked derived reads, imperative actions, and optional setup and event APIs.
 
-## Install
+## Getting Started
 
-```sh
-pnpm add preact-sigma
-```
+To add `preact-sigma` to your project:
 
-```sh
+```bash
 npm install preact-sigma
 ```
 
-## Big Picture
-
-Define state once, expose a few methods, and return reactive immutable data from the public instance.
-
-```ts
-import { computed, defineManagedState, type StateHandle } from "preact-sigma";
-
-type CounterEvents = {
-  thresholdReached: [{ count: number }];
-};
-
-type CounterState = number;
-
-const Counter = defineManagedState(
-  (counter: StateHandle<CounterState, CounterEvents>, step: number) => {
-    const doubled = computed(() => counter.get() * 2);
-
-    return {
-      count: counter,
-      doubled,
-      increment() {
-        counter.set((value) => value + step);
-
-        if (counter.get() >= 10) {
-          counter.emit("thresholdReached", { count: counter.get() });
-        }
-      },
-      reset() {
-        counter.set(0);
-      },
-    };
-  },
-  0,
-);
-
-const counter = new Counter(2);
-const stopThreshold = counter.on("thresholdReached", (event) => {
-  console.log(event.count);
-});
-
-counter.count;
-counter.doubled;
-counter.increment();
-stopThreshold();
-```
-
-- `count: counter` exposes the base state as a reactive immutable property.
-- `doubled` is a memoized reactive value exposed through `computed()`.
-- `increment()` is action-wrapped automatically, so the state update is batched and untracked.
-- `counter.on(...)` returns `stopThreshold`, which unsubscribes the event listener.
-
-## Define Reusable State
-
-Use `defineManagedState()` when you want a reusable managed-state class.
-
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
-
-type CounterState = number;
-
-const Counter = defineManagedState(
-  (counter: StateHandle<CounterState>) => ({
-    count: counter,
-    increment() {
-      counter.set((value) => value + 1);
-    },
-  }),
-  0,
-);
-```
-
-## Expose Base State
+If you use AI coding agents, this repo also includes agent-oriented guidance:
 
-Return the constructor handle when you want the base state to appear as a reactive immutable property.
+- [llms.txt](./llms.txt) provides a compact overview of the API and recommended patterns.
+- Companion skills are available via `npx skills add alloc/preact-sigma`.
 
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
-
-type CounterState = number;
-
-const Counter = defineManagedState(
-  (count: StateHandle<CounterState>) => ({
-    count,
-  }),
-  0,
-);
-
-new Counter().count;
-```
-
-## Memoize A Reactive Derivation
-
-Use `computed()` when you want a memoized reactive value on the public instance.
-
-```ts
-import { computed, defineManagedState, type StateHandle } from "preact-sigma";
-
-type CounterState = number;
+## What It Is
 
-const Counter = defineManagedState(
-  (counter: StateHandle<CounterState>) => ({
-    doubled: computed(() => counter.get() * 2),
-  }),
-  0,
-);
+At its core, `preact-sigma` lets you describe a stateful model as a constructor:
 
-new Counter().doubled;
-```
-
-## Create A Tracked Query Method
-
-Use `query()` when you want a public method whose reads stay tracked.
-Query functions read from closed-over handles or signals and do not use
-instance `this`.
-
-```ts
-import { defineManagedState, query, type StateHandle } from "preact-sigma";
+- top-level state stays reactive through one signal per state property
+- computed values become tracked getters
+- queries become tracked methods, including queries with arguments
+- actions batch reads and writes through Immer drafts
+- setup handlers own side effects and cleanup
+- typed events let instances notify the outside world without exposing mutable internals
 
-type CounterState = number;
+The result feels like a small stateful object from application code, while still behaving like signal-driven state from rendering code.
 
-const Counter = defineManagedState(
-  (counter: StateHandle<CounterState>) => ({
-    isPositive: query(() => counter.get() > 0),
-  }),
-  0,
-);
+## What You Can Do With It
 
-new Counter().isPositive();
-```
-
-## Read Base State Without Tracking
+`preact-sigma` is useful when you want state logic to live in one reusable unit instead of being split across loose signals, reducers, and effect cleanup code.
 
-Use `handle.peek()` when you need the current base-state snapshot without creating a reactive dependency.
+With it, you can:
 
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
+- model domain state as reusable constructors instead of one-off store objects
+- read public state directly while keeping writes inside typed action methods
+- derive reactive values with computed getters and parameterized queries
+- publish state changes from synchronous or async actions
+- observe committed state changes and optional Immer patches
+- snapshot committed top-level state and replace committed state for undo-like flows
+- manage timers, listeners, nested state setup, and teardown through explicit cleanup
+- use the same model inside Preact components with `useSigma(...)` and `useListener(...)`
 
-type CounterState = number;
+## Why This Shape Exists
 
-const Counter = defineManagedState(
-  (counter: StateHandle<CounterState>) => ({
-    logNow() {
-      console.log(counter.peek());
-    },
-  }),
-  0,
-);
-```
+This package exists to keep stateful logic cohesive without giving up signal-level reactivity.
 
-## Use Top-Level Lenses
+It is a good fit when plain signals start to sprawl across modules, but heavier store abstractions feel too opaque or too tied to component structure. `preact-sigma` keeps the "model object" ergonomics of a class-like API, while preserving readonly public reads, explicit write boundaries, and explicit ownership of side effects.
 
-When the base state is object-shaped, the constructor handle exposes a shallow lens for each top-level property, and you can return that lens directly.
+## Big Picture Example
 
 ```ts
-import { computed, defineManagedState, type StateHandle } from "preact-sigma";
+import { computed, SigmaType } from "preact-sigma";
 
-type SearchState = {
-  query: string;
+type Todo = {
+  id: string;
+  title: string;
+  done: boolean;
 };
 
-const Search = defineManagedState(
-  (search: StateHandle<SearchState>) => ({
-    query: search.query,
-    trimmedQuery: computed(() => search.query.get().trim()),
-    setQuery(query: string) {
-      search.query.set(query);
+const TodoList = new SigmaType<
+  { draft: string; todos: Todo[]; saving: boolean },
+  { saved: { count: number } }
+>("TodoList")
+  .defaultState({
+    draft: "",
+    todos: [],
+    saving: false,
+  })
+  .computed({
+    // Computeds are tracked getters with no arguments.
+    remainingCount() {
+      return this.todos.filter((todo) => !todo.done).length;
     },
-  }),
-  { query: "" },
-);
-
-new Search().query;
-```
-
-## Spread A Handle To Expose Top-Level Properties
-
-When the base state is object-shaped, spread the handle into the returned object to expose its current top-level lenses at once.
-
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
-
-type SearchState = {
-  page: number;
-  query: string;
-};
-
-const Search = defineManagedState(
-  (search: StateHandle<SearchState>) => ({
-    ...search,
-    nextPage() {
-      search.page.set((page) => page + 1);
+  })
+  .queries({
+    // Queries stay reactive at the call site and can accept arguments.
+    visibleTodos(filter: "all" | "open" | "done") {
+      return this.todos.filter((todo) => {
+        if (filter === "open") return !todo.done;
+        if (filter === "done") return todo.done;
+        return true;
+      });
     },
-  }),
-  { page: 1, query: "" },
-);
-
-const search = new Search();
-
-search.query;
-search.page;
-```
-
-## Compose Managed States
-
-Return another managed-state instance when you want to expose it unchanged as a property.
-Composed managed states are available through direct property access and whole-state snapshots.
-
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
-
-type CounterState = number;
-
-const Counter = defineManagedState(
-  (count: StateHandle<CounterState>) => ({
-    count,
-    increment() {
-      count.set((value) => value + 1);
+  })
+  .actions({
+    // Public state is readonly, so writes live in actions.
+    setDraft(draft: string) {
+      this.draft = draft;
     },
-  }),
-  0,
-);
+    addTodo() {
+      if (!this.draft.trim()) return;
 
-type DashboardState = {
-  ready: boolean;
-};
-
-const Dashboard = defineManagedState(
-  (dashboard: StateHandle<DashboardState>) => ({
-    dashboard,
-    counter: new Counter(),
-  }),
-  { ready: false },
-);
-
-new Dashboard().counter.increment();
-```
-
-## Own Resources And Dispose The Instance
-
-Use `handle.own()` to register cleanup functions or disposables, and call `.dispose()` when the managed state should release them.
-
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
-
-type PollerState = {
-  ticks: number;
-};
-
-const Poller = defineManagedState(
-  (poller: StateHandle<PollerState>) => ({
-    ticks: poller.ticks,
-    start() {
-      const interval = window.setInterval(() => {
-        poller.ticks.set((ticks) => ticks + 1);
-      }, 1000);
-
-      poller.own([() => window.clearInterval(interval)]);
-    },
-  }),
-  { ticks: 0 },
-);
-
-const poller = new Poller();
-
-poller.start();
-poller.dispose();
-```
-
-## Update State
-
-Pass an Immer producer to `.set()` when your base state is object-shaped.
-
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
-
-type SearchState = {
-  query: string;
-};
-
-const Search = defineManagedState(
-  (search: StateHandle<SearchState>) => ({
-    setQuery(query: string) {
-      search.set((draft) => {
-        draft.query = query;
+      this.todos.push({
+        id: crypto.randomUUID(),
+        title: this.draft,
+        done: false,
       });
+      this.draft = "";
     },
-  }),
-  { query: "" },
-);
-```
-
-## Emit Events
-
-Use `.emit()` to publish a custom event with zero or one argument.
-
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
-
-type TodoEvents = {
-  saved: [];
-  selected: [{ id: string }];
-};
-
-type TodoState = {};
-
-const Todo = defineManagedState(
-  (todo: StateHandle<TodoState, TodoEvents>) => ({
-    save() {
-      todo.emit("saved");
-    },
-    select(id: string) {
-      todo.emit("selected", { id });
+    toggleTodo(id: string) {
+      const todo = this.todos.find((todo) => todo.id === id);
+      if (todo) todo.done = !todo.done;
     },
-  }),
-  {},
-);
-```
-
-## Listen For Events
-
-Use `.on()` to subscribe to custom events from a managed state instance.
-
-```ts
-const todo = new Todo();
-
-const stopSaved = todo.on("saved", () => {
-  console.log("saved");
-});
-
-const stopSelected = todo.on("selected", (event) => {
-  console.log(event.id);
-});
-
-stopSaved();
-stopSelected();
-```
-
-## Read Signals From A Managed State
-
-Use `.get(key)` for one exposed signal-backed property or `.get()` for the whole public state signal.
-Keyed reads do not target composed managed-state properties.
-
-```ts
-const counter = new Counter();
-
-const countSignal = counter.get("count");
-const counterSignal = counter.get();
-
-countSignal.value;
-counterSignal.value.count;
-```
-
-## Peek At Public State
-
-Use `.peek(key)` for one exposed signal-backed property or `.peek()` for the whole public snapshot.
-Keyed peeks do not target composed managed-state properties.
-
-```ts
-const counter = new Counter();
-
-counter.peek("count");
-counter.peek();
-```
-
-## Subscribe To Public State
-
-Use `.subscribe(key, listener)` for one exposed signal-backed property or `.subscribe(listener)` for the whole public state.
-Listeners receive the current value immediately and then future updates.
-Keyed subscriptions do not target composed managed-state properties.
+    async save() {
+      this.saving = true;
+      this.commit(); // Publish the loading state before awaiting.
 
-```ts
-const counter = new Counter();
-
-const stopCount = counter.subscribe("count", (count) => {
-  console.log(count);
-});
-
-const stopState = counter.subscribe((value) => {
-  console.log(value.count);
-});
-
-stopCount();
-stopState();
-```
-
-## Use It Inside A Component
-
-Use `useManagedState()` when you want the same pattern directly inside a component.
-
-```tsx
-import { useManagedState, type StateHandle } from "preact-sigma";
-
-type SearchState = {
-  query: string;
-};
-
-function SearchBox() {
-  const search = useManagedState(
-    (search: StateHandle<SearchState>) => ({
-      query: search.query,
-      setQuery(query: string) {
-        search.query.set(query);
-      },
-    }),
-    () => ({ query: "" }),
-  );
-
-  return (
-    <input value={search.query} onInput={(event) => search.setQuery(event.currentTarget.value)} />
-  );
-}
-```
-
-## Subscribe In `useEffect`
-
-Use `useSubscribe()` with any subscribable source, including managed state and Preact signals.
-The listener receives the current value immediately and then future updates.
-
-```tsx
-import { useSubscribe } from "preact-sigma";
-
-useSubscribe(counter, (value) => {
-  console.log(value.count);
-});
-```
+      await fetch("/api/todos", {
+        method: "POST",
+        body: JSON.stringify(this.todos),
+      });
 
-## Listen To DOM Or Managed-State Events In `useEffect`
+      this.saving = false;
+      this.commit(); // Publish post-await writes explicitly.
+      this.emit("saved", { count: this.todos.length });
+    },
+  })
+  .setup(function (storageKey: string) {
+    // Setup is explicit and returns cleanup resources.
+    const interval = window.setInterval(() => {
+      localStorage.setItem(storageKey, JSON.stringify(this.todos));
+    }, 1000);
 
-Use `useEventTarget()` for either DOM events or managed-state events.
+    return [() => window.clearInterval(interval)];
+  });
 
-```tsx
-import { useEventTarget } from "preact-sigma";
+const todoList = new TodoList();
 
-useEventTarget(window, "resize", () => {
-  console.log(window.innerWidth);
-});
-```
+// setup(...) returns one cleanup function for everything this instance owns.
+const cleanup = todoList.setup("todos-demo");
 
-```tsx
-useEventTarget(counter, "thresholdReached", (event) => {
-  console.log(event.count);
+// Queries are reactive where they are read.
+const firstOpenTitle = computed(() => {
+  return todoList.visibleTodos("open")[0]?.title ?? "Nothing open";
 });
-```
 
-## Reach For Signals Helpers
-
-`batch` and `untracked` are re-exported from `@preact/signals`.
-
-```ts
-import { batch, untracked } from "preact-sigma";
-
-batch(() => {
-  counter.increment();
-  counter.reset();
+// Events are typed and unsubscribe cleanly.
+const stop = todoList.on("saved", ({ count }) => {
+  console.log(`Saved ${count} todos`);
 });
 
-untracked(() => {
-  console.log(counter.count);
-});
-```
-
-## Small Feature Model
-
-This pattern works well when a component or UI feature needs a small state model with a few public methods and derived values.
-
-```ts
-import { defineManagedState, type StateHandle } from "preact-sigma";
+todoList.setDraft("Write the README");
+todoList.addTodo();
+await todoList.save();
 
-type DialogState = boolean;
+console.log(todoList.remainingCount);
+console.log(firstOpenTitle.value);
 
-const Dialog = defineManagedState(
-  (dialog: StateHandle<DialogState>) => ({
-    open: dialog,
-    show() {
-      dialog.set(true);
-    },
-    hide() {
-      dialog.set(false);
-    },
-  }),
-  false,
-);
+stop();
+cleanup();
 ```
 
-Keep using plain `useState()` when the state is trivial.
-
-```tsx
-const [open, setOpen] = useState(false);
-```
+In Preact, the same constructor can be used with `useSigma(() => new TodoList(), ["todos-demo"])` so the component owns one instance and `setup(...)` cleanup runs automatically. Use `useListener(...)` when you want component-scoped event subscriptions with automatic teardown.
 
-## License
+## Best Practices
 
-MIT. See [LICENSE-MIT](./LICENSE-MIT).
+- Let `new SigmaType<TState, TEvents>()` and the builder inputs drive inference. Avoid forcing extra type arguments onto builder methods.
+- Keep top-level state properties meaningful. Each top-level property gets its own signal, so shape state around the reads you want to track.
+- Use `computed(...)` for argument-free derived state, and use queries for reactive reads that need parameters.
+- Put writes in actions. A draft boundary is any point where sigma cannot keep reusing the current draft. `emit()`, `await`, and any action call other than a same-instance sync nested action call are draft boundaries, so call `this.commit()` before those boundaries when pending writes should become public.
+- Use `snapshot(instance)` and `replaceState(instance, snapshot)` for committed-state replay. They work on top-level state keys and stay outside action semantics.
+- Use `immerable` on custom classes only when they should participate in Immer drafting. `setAutoFreeze(false)` disables sigma's runtime deep-freezing when you need published state to stay unfrozen.
+- Use `setup(...)` for owned side effects, and always return cleanup resources for anything the instance starts.