preact-sigma 2.1.3 → 2.2.1

package/README.md

@@ -12,10 +12,33 @@ To add `preact-sigma` to your project:
 npm install preact-sigma
 ```
 
-If you use AI coding agents, this repo also includes agent-oriented guidance:
+## Smallest Useful Example
 
-- [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 { 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;
+    },
+  });
+
+const counter = new Counter();
+
+counter.increment();
+
+console.log(counter.count); // 1
+console.log(counter.doubled); // 2
+```
 
 ## What It Is
 
@@ -157,13 +180,17 @@ cleanup();
 
 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.
 
-## Best Practices
+Cleanup resources can be returned as functions, `AbortController`, objects with `dispose()`, or objects with `Symbol.dispose`.
 
-- 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 `SigmaRef<T>` when a value should stay by reference in sigma's `Draft` and `Immutable` types. A normal assignment to a `SigmaRef<T>`-typed value only changes typing and does not change Immer's runtime drafting or freezing behavior.
-- 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.
+Inside setup, `this` exposes the public instance plus `emit(...)` and `act(fn)`. Use `this.act(function () { ... })` when setup needs one synchronous anonymous action with normal draft, `commit()`, and `emit(...)` semantics, whether that work happens immediately in the setup body or later from a setup-owned callback, but should not become a public action method.
+
+## Constructor and Defaults
+
+- `defaultState` values may be plain values or zero-argument initializer functions. Use initializer functions when each instance needs a fresh object, array, or class instance.
+- Constructor input shallowly overrides `defaultState`, so `new TodoList({ draft: "ready" })` replaces only the top-level keys you pass.
+
+## More Docs
+
+- [llms.txt](./llms.txt) provides the exhaustive machine-oriented API guide and terminology.
+- Companion skills are available via `npx skills add alloc/preact-sigma`.
+- The `preact-sigma` skill packages the procedural guidance and agent-oriented workflow for this library.

package/dist/index.d.mts

@@ -47,6 +47,9 @@ type DefaultStateValue<TValue> = TValue | DefaultStateInitializer<TValue>;
 type Disposable = {
   [Symbol.dispose](): void;
 };
+type DisposableLike = {
+  dispose(): void;
+};
 interface SigmaRefBrand {
   [sigmaRefBrand]?: true;
 }
@@ -58,8 +61,8 @@ type AnyEvents = Record<string, object | void>;
 type AnyState = Record<string, unknown>;
 /** The object accepted by `.defaultState(...)`. */
 type AnyDefaultState<TState extends AnyState> = { [K in keyof TState]?: DefaultStateValue<TState[K]> };
-/** A cleanup resource supported by `.setup(...)`. */
-type AnyResource = Cleanup | Disposable | AbortController;
+/** A cleanup resource supported by `.setup(...)`, including function, `dispose()`, and `Symbol.dispose` cleanup. */
+type AnyResource = Cleanup | Disposable | DisposableLike | AbortController;
 type ComputedValues<TComputeds extends object | undefined> = [undefined] extends [TComputeds] ? never : { readonly [K in keyof TComputeds]: TComputeds[K] extends AnyFunction ? Immutable<ReturnType<TComputeds[K]>> : never };
 type ComputedContext<TState extends AnyState, TComputeds extends object> = Immutable<TState> & ComputedValues<TComputeds>;
 type QueryMethods<TQueries extends object | undefined> = [undefined] extends [TQueries] ? never : { [K in keyof TQueries]: TQueries[K] extends AnyFunction ? (...args: Parameters<TQueries[K]>) => ReturnType<TQueries[K]> : never };
@@ -77,6 +80,10 @@ type ActionContext<TState extends AnyState, TEvents extends AnyEvents, TComputed
   /** Publishes the current action draft immediately so later boundaries use committed state. */commit(): void;
   emit: Emit<TEvents>;
 };
+type DefinitionEvents<T extends SigmaDefinition> = T["events"] extends AnyEvents ? T["events"] : {};
+type DefinitionComputeds<T extends SigmaDefinition> = T["computeds"] extends object ? T["computeds"] : {};
+type DefinitionQueries<T extends SigmaDefinition> = T["queries"] extends object ? T["queries"] : {};
+type DefinitionActions<T extends SigmaDefinition> = T["actions"] extends object ? T["actions"] : {};
 /** The public shape shared by all sigma-state instances. */
 interface AnySigmaState extends EventTarget {
   readonly [sigmaStateBrand]: true;
@@ -114,6 +121,7 @@ type MapSigmaDefinition<T extends SigmaDefinition> = keyof T extends infer K ? K
 /** The public instance shape produced by a configured sigma type. */
 type SigmaState<T extends SigmaDefinition = SigmaDefinition> = AnySigmaState & Simplify<UnionToIntersection<MapSigmaDefinition<T>>>;
 type SetupContext<T extends SigmaDefinition> = SigmaState<T> & {
+  act<TResult>(fn: (this: ActionContext<T["state"], DefinitionEvents<T>, DefinitionComputeds<T>, DefinitionQueries<T>, DefinitionActions<T>>) => TResult): TResult;
   emit: T["events"] extends object ? Emit<T["events"]> : never;
 };
 type MergeObjects<TLeft extends object, TRight> = [TRight] extends [object] ? Extract<Simplify<Omit<TLeft, keyof TRight> & TRight>, TLeft> : TLeft;

package/dist/index.mjs

@@ -4,6 +4,7 @@ import { freeze, immerable } from "immer";
 import { useEffect, useRef, useState } from "preact/hooks";
 //#region src/internal/context.ts
 const disabledContextOptions = {
+	allowAct: false,
 	allowActions: false,
 	allowCommit: false,
 	allowEmit: false,
@@ -30,6 +31,7 @@ const publicContextOptions = {
 	},
 	setup: {
 		...disabledContextOptions,
+		allowAct: true,
 		allowActions: true,
 		allowEmit: true,
 		allowQueries: true
@@ -87,8 +89,12 @@ function registerContextOwner(context, owner) {
 function createContext(instance, options, owner) {
 	const publicPrototype = Object.getPrototypeOf(instance.publicInstance);
 	return new Proxy(publicPrototype, {
-		get(_target, key) {
+		get(_target, key, receiver) {
 			if (typeof key !== "string") return Reflect.get(publicPrototype, key, owner?.actionContext ?? instance.publicInstance);
+			if (key === "act") return options.allowAct ? (actionFn) => {
+				if (typeof actionFn !== "function") throw new Error("[preact-sigma] act() requires a function");
+				return runAdHocAction(receiver, actionFn);
+			} : void 0;
 			if (key === "commit") return options.allowCommit && owner ? () => commitActionOwner(owner) : void 0;
 			if (key === "emit") return options.allowEmit && owner ? (name, detail) => {
 				handleActionBoundary(owner, "emit");
@@ -168,6 +174,7 @@ function getPublicContext(instance, kind) {
 //#region src/internal/symbols.ts
 const sigmaStateBrand = Symbol("sigma.v2.state");
 const reservedKeys = new Set([
+	"act",
 	"get",
 	"emit",
 	"commit",
@@ -237,38 +244,13 @@ function buildQueryMethod(queryFunction) {
 	};
 }
 function buildActionMethod(actionName, actionFn) {
-	const actionIsAsync = isAsyncFunction(actionFn);
 	return function(...args) {
-		const instance = getSigmaInternals(this);
-		if (instance.disposed) throw new Error("[preact-sigma] Cannot run an action on a disposed sigma state");
-		return untracked$1(() => {
-			let owner;
-			const callerOwner = getContextOwner(this);
-			if (callerOwner && callerOwner.instance === instance && !actionIsAsync) owner = callerOwner;
-			else {
-				handleActionBoundary(callerOwner, "action", actionName);
-				owner = createActionOwner(instance, actionName, actionFn, args);
-			}
-			let result;
-			try {
-				result = actionFn.apply(owner.actionContext, [...args]);
-			} catch (error) {
-				clearCurrentDraft(owner);
-				throw error;
-			}
-			if (!actionIsAsync && isPromiseLike(result)) {
-				clearCurrentDraft(owner);
-				Promise.resolve(result).catch(() => {});
-				throw new Error(`[preact-sigma] Action "${actionName}" must use native async-await syntax to return a promise.`);
-			}
-			if (owner === callerOwner) return result;
-			const finalized = finalizeOwnerDraft(owner);
-			if (finalized?.changed) publishState(instance, finalized);
-			if (isPromiseLike(result)) return resolveAsyncActionResult(owner, result);
-			return result;
-		});
+		return runActionInvocation(this, actionName, actionFn, args);
 	};
 }
+function runAdHocAction(context, actionFn) {
+	return runActionInvocation(context, "act()", actionFn, []);
+}
 function readActionStateValue(owner, key, options) {
 	if (owner.currentDraft) return owner.currentDraft[key];
 	const signal = getSignal(owner.instance, key);
@@ -323,6 +305,44 @@ function createActionOwner(instance, actionName, actionFn, args) {
 	registerContextOwner(owner.actionContext, owner);
 	return owner;
 }
+function runActionInvocation(context, actionName, actionFn, args) {
+	const instance = getSigmaInternals(context);
+	if (instance.disposed) throw new Error("[preact-sigma] Cannot run an action on a disposed sigma state");
+	const isAdHocAction = actionName === "act()";
+	const actionIsAsync = isAsyncFunction(actionFn);
+	if (actionIsAsync && isAdHocAction) throw new Error("[preact-sigma] act() callbacks must stay synchronous");
+	return untracked$1(() => {
+		let owner;
+		const callerOwner = getContextOwner(context);
+		if (callerOwner && callerOwner.instance === instance && !actionIsAsync) owner = callerOwner;
+		else {
+			handleActionBoundary(callerOwner, "action", actionName);
+			owner = createActionOwner(instance, actionName, actionFn, args);
+		}
+		let result;
+		try {
+			result = actionFn.apply(owner.actionContext, args);
+		} catch (error) {
+			clearCurrentDraft(owner);
+			throw error;
+		}
+		if (isAdHocAction && isPromiseLike(result)) {
+			clearCurrentDraft(owner);
+			Promise.resolve(result).catch(() => {});
+			throw new Error("[preact-sigma] act() callbacks must stay synchronous");
+		}
+		if (!actionIsAsync && isPromiseLike(result)) {
+			clearCurrentDraft(owner);
+			Promise.resolve(result).catch(() => {});
+			throw new Error(`[preact-sigma] Action "${actionName}" must use native async-await syntax to return a promise.`);
+		}
+		if (owner === callerOwner) return result;
+		const finalized = finalizeOwnerDraft(owner);
+		if (finalized?.changed) publishState(instance, finalized);
+		if (isPromiseLike(result)) return resolveAsyncActionResult(owner, result);
+		return result;
+	});
+}
 function createCommitError(owner) {
 	return /* @__PURE__ */ new Error(`[preact-sigma] Async action "${owner.actionName}" finished with unpublished changes. Call this.commit() before await or return.`);
 }
@@ -339,6 +359,7 @@ function createDraftMetadata(owner) {
 function disposeCleanupResource(resource) {
 	if (typeof resource === "function") resource();
 	else if (resource instanceof AbortController) resource.abort();
+	else if ("dispose" in resource) resource.dispose();
 	else resource[Symbol.dispose]();
 }
 function assertExactStateKeys(instance, nextState) {

package/llms.txt

@@ -8,9 +8,10 @@
 - `computed`: A tracked getter declared with `.computed({ ... })`.
 - `query`: A tracked method declared with `.queries({ ... })` or created with `query(fn)`.
 - `action`: A method declared with `.actions({ ... })` that reads and writes through one Immer draft for one synchronous call.
+- `anonymous action`: A synchronous function passed to `this.act(...)` inside setup to run one anonymous action.
 - `draft boundary`: Any point where sigma cannot keep reusing the current draft.
 - `setup handler`: A function declared with `.setup(fn)` that returns an array of cleanup resources.
-- `cleanup resource`: A cleanup function, an `AbortController`, or an object with `[Symbol.dispose]()`.
+- `cleanup resource`: A cleanup function, an `AbortController`, an object with `dispose()`, or an object with `[Symbol.dispose]()`.
 - `signal access`: Reading the underlying `ReadonlySignal` for a state property or computed through `instance.get(key)`.
 
 ## Navigation
@@ -75,7 +76,7 @@ import {
 
 - `AnyDefaultState`: Describes the object accepted by `.defaultState(...)`.
 - `AnyEvents`: Describes an event map from event names to payload objects or `void`.
-- `AnyResource`: Describes a supported setup cleanup resource.
+- `AnyResource`: Describes a supported setup cleanup resource, including cleanup functions, `AbortController`, objects with `dispose()`, and objects with `Symbol.dispose`.
 - `AnySigmaState`: Describes the public shape shared by all sigma-state instances.
 - `AnySigmaStateWithEvents`: Describes a sigma-state instance with a typed event map.
 - `AnyState`: Describes the top-level state object for a sigma type.
@@ -169,7 +170,7 @@ Behavior:
 - Constructor input shallowly overrides `defaultState`.
 - If every required state property is covered by `defaultState`, constructor input is optional.
 - Duplicate names across state properties, computeds, queries, and actions are rejected at runtime.
-- Reserved public names are `get`, `setup`, `on`, and `emit`.
+- Reserved public names are `act`, `get`, `setup`, `on`, and `emit`.
 
 ## Public Instance Shape
 
@@ -289,13 +290,18 @@ Behavior:
 - calling `.setup(...)` again cleans up the previous setup first
 - one `.setup(...)` call runs every registered setup handler in definition order
 - the public `.setup(...)` method always returns one cleanup function
-- `this` inside a setup handler exposes the public instance plus `emit(...)`
+- `this` inside a setup handler exposes the public instance plus `emit(...)` and `act(fn)`
+- `this.act(fn)` inside setup runs `fn` with normal action semantics without adding a public action method
+- use `this.act(fn)` for setup-time initialization work or setup-owned callbacks that need action semantics
+- pass a normal `function () {}` to `this.act(...)` so callback `this` receives the action context
+- `this.act(fn)` functions must stay synchronous
 - each setup handler returns an array of cleanup resources
 - setup typing only exposes computeds, queries, and actions that were already present when that `.setup(...)` call happened
 
 Supported cleanup resources:
 
 - cleanup functions
+- objects with `dispose()`
 - objects with `[Symbol.dispose]()`
 - `AbortController`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "2.1.3",
+  "version": "2.2.1",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",