preact-sigma 2.1.2 → 2.2.0

package/README.md

@@ -157,13 +157,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.
 
+Cleanup resources can be returned as functions, `AbortController`, objects with `dispose()`, or objects with `Symbol.dispose`.
+
+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.
+
 ## Best Practices
 
 - 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.
+- 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. Setup can use `this.act(function () { ... })` to run one synchronous anonymous action for initialization work or setup-owned callbacks without adding a public action method.
 - Use `snapshot(instance)` and `replaceState(instance, snapshot)` for committed-state replay. They work on top-level state keys and stay outside action semantics.
-- Use `ref(value)` when a value should stay by reference in sigma's `Draft` and `Immutable` types. It only changes typing and does not change Immer's runtime drafting or freezing behavior.
+- 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.

package/dist/index.d.mts

@@ -47,10 +47,13 @@ type DefaultStateValue<TValue> = TValue | DefaultStateInitializer<TValue>;
 type Disposable = {
   [Symbol.dispose](): void;
 };
+type DisposableLike = {
+  dispose(): void;
+};
 interface SigmaRefBrand {
   [sigmaRefBrand]?: true;
 }
-/** A type brand added by `ref(...)`. */
+/** A type brand that keeps a value by reference in sigma's `Draft` and `Immutable` helpers. */
 type SigmaRef<T = unknown> = T & SigmaRefBrand;
 /** The event map shape used by sigma types. */
 type AnyEvents = Record<string, object | void>;
@@ -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;
@@ -150,11 +158,6 @@ declare function replaceState<T extends AnySigmaState>(publicInstance: T, nextSt
 //#region src/framework.d.ts
 /** Checks whether a value is a sigma-state instance. */
 declare function isSigmaState(value: unknown): value is AnySigmaState;
-/**
- * Returns `value` unchanged and marks its type so sigma's Draft and Immutable
- * helpers keep it by reference instead of recursively immerizing it.
- */
-declare function ref<T extends object>(value: T): SigmaRef<T>;
 /** Creates a standalone tracked query function with the same signature as `fn`. */
 declare function query<TArgs extends any[], TResult>(fn: (this: void, ...args: TArgs) => TResult): typeof fn;
 /**
@@ -238,4 +241,4 @@ declare function useSigma<T extends AnySigmaState>(create: () => T, setupArgs?:
 /** Attaches an event listener in a component and cleans it up when dependencies change. */
 declare function useListener<TTarget extends EventTarget | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
 //#endregion
-export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, ref, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

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) {
@@ -520,13 +541,6 @@ Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
 function isSigmaState(value) {
 	return Boolean(value && typeof value === "object" && value[sigmaStateBrand]);
 }
-/**
-* Returns `value` unchanged and marks its type so sigma's Draft and Immutable
-* helpers keep it by reference instead of recursively immerizing it.
-*/
-function ref(value) {
-	return value;
-}
 /** Creates a standalone tracked query function with the same signature as `fn`. */
 function query(fn) {
 	return ((...args) => computed$1(() => fn(...args)).value);
@@ -633,4 +647,4 @@ function useListener(target, name, listener) {
 	}, [target, name]);
 }
 //#endregion
-export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, ref, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/llms.txt

@@ -7,18 +7,18 @@
 - `state property`: A top-level property from `TState`, such as `draft` in `{ draft: string }`.
 - `computed`: A tracked getter declared with `.computed({ ... })`.
 - `query`: A tracked method declared with `.queries({ ... })` or created with `query(fn)`.
-- `ref`: A helper that keeps a value by reference in sigma's `Draft` and `Immutable` types without changing runtime behavior.
 - `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
 
 - For state shape, inference, and instance shape, read `Start Here`, `Inference`, `SigmaType`, and `Public Instance Shape`.
 - For mutation semantics, read `Critical Rules`, `actions`, `immerable`, and `setAutoFreeze`.
-- For type-level by-reference values, read `ref`.
+- For type-level by-reference values, see `SigmaRef<T>`.
 - For side effects and events, read `setup`, `Events`, `listen`, `useListener`, and `useSigma`.
 - For committed-state utilities, read `observe`, `snapshot`, and `replaceState`.
 
@@ -62,7 +62,7 @@ import {
   isSigmaState,
   listen,
   query,
-  ref,
+  type SigmaRef,
   replaceState,
   setAutoFreeze,
   snapshot,
@@ -76,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.
@@ -170,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
 
@@ -290,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`
 
@@ -328,13 +333,13 @@ Behavior:
 - custom class instances without a true `[immerable]` property stay outside that freeze path
 - plain objects, arrays, `Map`, and `Set` already participate in normal Immer drafting without extra markers
 
-## `ref(value)`
+## `SigmaRef<T>`
 
-`ref(value)` returns `value` unchanged and marks its type so sigma's `Draft` and `Immutable` helpers keep that value by reference.
+`SigmaRef<T>` marks a value's type so sigma's `Draft` and `Immutable` helpers keep that value by reference.
 
 Behavior:
 
-- it has no runtime effect
+- assigning to a `SigmaRef<T>`-typed value has no runtime effect
 - it only changes sigma's local `Draft` and `Immutable` typing
 - it prevents type-level recursive immerization for that value
 - it does not change whether Immer drafts or freezes the value at runtime

package/package.json

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