preact-sigma 6.2.0 → 6.3.0

package/README.md

@@ -49,7 +49,4 @@ console.log(counter.doubled); // 2
 - Persistence-specific guidance lives in [`docs/persist.md`](./docs/persist.md).
 - Migration guidance from v5 lives in [`docs/migrations/v5-to-v6.md`](./docs/migrations/v5-to-v6.md).
 - Runnable usage patterns live in [`examples/`](./examples/).
-  - [`examples/basic-counter.ts`](./examples/basic-counter.ts)
-  - [`examples/command-palette.tsx`](./examples/command-palette.tsx)
-  - [`examples/external-query-sync.tsx`](./examples/external-query-sync.tsx)
 - Exact exported signatures and public API comments live in `dist/index.d.mts` and `dist/persist.d.mts` after `pnpm build`.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as SigmaRef, c as castProtected, d as sigma, f as Draft, h as Cleanup, i as SigmaDefinition, l as query, m as typeSymbol, n as ReadableSigma, o as SigmaState, p as Immutable, r as Sigma, s as SigmaTarget, t as Protected, u as setAutoFreeze } from "./sigma-BfaJUPWw.mjs";
+import { a as SigmaRef, c as castProtected, d as sigma, f as Draft, g as Cleanup, h as AnyResource, i as SigmaDefinition, l as query, m as typeSymbol, n as ReadableSigma, o as SigmaState, p as Immutable, r as Sigma, s as SigmaTarget, t as Protected, u as setAutoFreeze } from "./sigma-CCBzhGdp.mjs";
 
 //#region src/defaults.d.ts
 /**
@@ -54,7 +54,8 @@ type UseSigmaArgs<T extends Sigma<any>> = T extends {
 /**
  * Creates or reuses a sigma instance for a component and returns its protected consumer view.
  *
- * Classes with `onSetup(...)` run setup in an effect and clean it up on unmount.
+ * Classes with `onSetup(...)` run setup in an effect and clean it up on unmount,
+ * so the returned instance does not need a separate `useSetup(...)` call.
  */
 declare function useSigma<T extends Sigma<any>>(...args: UseSigmaArgs<T>): Protected<T>;
 //#endregion
@@ -72,4 +73,17 @@ type PlainObject = Record<string, unknown>;
  */
 declare function useSigmaSync<TInstance extends Sigma<any>, TInput extends PlainObject>(instance: TInstance | Protected<TInstance>, input: TInput, sync: (input: Readonly<TInput>) => void): void;
 //#endregion
-export { type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, ReadableSigma, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma, useSigmaSync };
+//#region src/hooks/useSetup.d.ts
+/** Setup callback that returns resources owned by one effect run. */
+type SetupCallback = () => readonly AnyResource[];
+/**
+ * Runs a component setup effect and disposes returned resources in reverse order.
+ *
+ * The returned resources use the same cleanup protocol as `Sigma.setup(...)`.
+ * Use this for resources owned directly by a component. Components that create
+ * a sigma instance with `useSigma(...)` do not need `useSetup(...)` for that
+ * instance, because `useSigma(...)` runs `onSetup(...)` automatically.
+ */
+declare function useSetup(setup: SetupCallback, deps?: readonly any[]): void;
+//#endregion
+export { type AnyResource, type Cleanup, type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, ReadableSigma, SetupCallback, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSetup, useSigma, useSigmaSync };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as setAutoFreeze, c as listenersSymbol, i as query, n as SigmaTarget, o as sigma, r as castProtected, s as isPlainObject, t as Sigma } from "./sigma-DEKK3bHd.mjs";
+import { a as setAutoFreeze, c as isPlainObject, i as query, l as listenersSymbol, n as SigmaTarget, o as sigma, r as castProtected, s as disposeResources, t as Sigma } from "./sigma-BH9WolKc.mjs";
 import { useEffect, useRef } from "preact/hooks";
 //#region src/defaults.ts
 /**
@@ -115,4 +115,20 @@ function useSigmaSync(instance, input, sync) {
 	});
 }
 //#endregion
-export { Sigma, SigmaTarget, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma, useSigmaSync };
+//#region src/hooks/useSetup.ts
+/**
+* Runs a component setup effect and disposes returned resources in reverse order.
+*
+* The returned resources use the same cleanup protocol as `Sigma.setup(...)`.
+* Use this for resources owned directly by a component. Components that create
+* a sigma instance with `useSigma(...)` do not need `useSetup(...)` for that
+* instance, because `useSigma(...)` runs `onSetup(...)` automatically.
+*/
+function useSetup(setup, deps) {
+	useEffect(() => {
+		const resources = setup();
+		return () => disposeResources(resources);
+	}, deps);
+}
+//#endregion
+export { Sigma, SigmaTarget, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSetup, useSigma, useSigmaSync };

package/dist/persist.d.mts

@@ -1,4 +1,4 @@
-import { n as ReadableSigma, p as Immutable, r as Sigma } from "./sigma-BfaJUPWw.mjs";
+import { n as ReadableSigma, p as Immutable, r as Sigma } from "./sigma-CCBzhGdp.mjs";
 
 //#region src/persist.d.ts
 type MaybePromise<T> = T | Promise<T>;

package/dist/persist.mjs

@@ -1,4 +1,4 @@
-import { o as sigma, s as isPlainObject } from "./sigma-DEKK3bHd.mjs";
+import { c as isPlainObject, o as sigma } from "./sigma-BH9WolKc.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {

package/dist/{sigma-DEKK3bHd.mjs → sigma-BH9WolKc.mjs}

@@ -33,6 +33,14 @@ var SigmaListenerMap = class extends Map {
 };
 //#endregion
 //#region src/internal/utils.ts
+function disposeResource(resource) {
+	if (typeof resource === "function") resource();
+	else if ("dispose" in resource) resource.dispose();
+	else resource[Symbol.dispose]();
+}
+function disposeResources(resources) {
+	for (let i = resources.length - 1; i >= 0; i--) disposeResource(resources[i]);
+}
 function isPlainObject(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const prototype = Object.getPrototypeOf(value);
@@ -303,11 +311,6 @@ function initializeType(type) {
 		initializedPrototypes.add(prototype);
 	}
 }
-function disposeCleanupResource(resource) {
-	if (typeof resource === "function") resource();
-	else if ("dispose" in resource) resource.dispose();
-	else resource[Symbol.dispose]();
-}
 function defineSignalProperty(instance, key, value) {
 	Object.defineProperty(instance, key + signalSuffix, { value: signal(value) });
 	if (!Object.hasOwn(instance.constructor.prototype, key)) Object.defineProperty(instance.constructor.prototype, key, {
@@ -355,7 +358,7 @@ var Sigma = class {
 			activeSetupInstance = previousSetupInstance;
 		}
 		return () => {
-			for (let i = resources.length - 1; i >= 0; i--) disposeCleanupResource(resources[i]);
+			disposeResources(resources);
 		};
 	}
 	/**
@@ -418,22 +421,23 @@ var SigmaTarget = class SigmaTarget extends Sigma {
 /** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
 const sigma = /* @__PURE__ */ Object.freeze({
 	subscribe: ((instance, keyOrListener, listenerOrOptions) => {
+		const source = instance;
 		if (typeof keyOrListener === "string") {
-			const signal = getStateSignal(instance, keyOrListener);
+			const signal = getStateSignal(source, keyOrListener);
 			if (!signal) throw new Error(`[preact-sigma] Property named "${keyOrListener}" is not signal-backed.`);
 			return signal.subscribe(listenerOrOptions);
 		}
 		const listener = keyOrListener;
 		if (listenerOrOptions?.patches) patchListeners.add(listener);
-		let subscriptions = changeListenersMap.get(instance);
+		let subscriptions = changeListenersMap.get(source);
 		if (!subscriptions) {
 			subscriptions = /* @__PURE__ */ new Set();
-			changeListenersMap.set(instance, subscriptions);
+			changeListenersMap.set(source, subscriptions);
 		}
 		subscriptions.add(listener);
 		return () => {
 			subscriptions.delete(listener);
-			if (!subscriptions.size) changeListenersMap.delete(instance);
+			if (!subscriptions.size) changeListenersMap.delete(source);
 		};
 	}),
 	getSignal(instance, key) {
@@ -471,4 +475,4 @@ function query(method) {
 	return queryMethod;
 }
 //#endregion
-export { setAutoFreeze as a, listenersSymbol as c, query as i, SigmaTarget as n, sigma as o, castProtected as r, isPlainObject as s, Sigma as t };
+export { setAutoFreeze as a, isPlainObject as c, query as i, listenersSymbol as l, SigmaTarget as n, sigma as o, castProtected as r, disposeResources as s, Sigma as t };

package/dist/{sigma-BfaJUPWw.d.mts → sigma-CCBzhGdp.d.mts}

@@ -3,7 +3,9 @@ import { Patch } from "immer";
 
 //#region src/internal/utils.d.ts
 type AnyFunction = (...args: any[]) => any;
+/** Function cleanup returned from setup-owned resources. */
 type Cleanup = () => void;
+/** Cleanup resource returned from setup hooks and disposed during teardown. */
 type AnyResource = Cleanup | {
   dispose(): void;
 } | {
@@ -141,14 +143,14 @@ declare class SigmaTarget<TEvents extends object = {}, TState extends object = {
 /** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
 declare const sigma: Readonly<{
   /** Subscribes to committed state publishes or to one signal-backed top-level state key. */subscribe: {
-    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[], inversePatches: Patch[]) => void, options: {
+    <TState extends object>(instance: ReadableSigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[], inversePatches: Patch[]) => void, options: {
       patches: true;
     }): Cleanup;
-    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[] | undefined, inversePatches: Patch[] | undefined) => void, options: {
+    <TState extends object>(instance: ReadableSigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[] | undefined, inversePatches: Patch[] | undefined) => void, options: {
       patches: boolean;
     }): Cleanup;
-    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>) => void): Cleanup;
-    <TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey, listener: (value: Immutable<TState[TKey]>) => void): Cleanup;
+    <TState extends object>(instance: ReadableSigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>) => void): Cleanup;
+    <TState extends object, TKey extends Extract<keyof TState, string>>(instance: ReadableSigma<TState>, key: TKey, listener: (value: Immutable<TState[TKey]>) => void): Cleanup;
   }; /** Returns the readonly signal backing one top-level state key. */
   getSignal<TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey): ReadonlySignal<Immutable<TState[TKey]>>; /** Captures the current committed top-level state snapshot. */
   captureState<TState extends object>(instance: ReadableSigma<TState>): Immutable<TState>; /** Publishes a plain-object snapshot, including readonly captured snapshots, as committed state. */
@@ -172,4 +174,4 @@ type Protected<T extends Sigma<any>> = BrandProtected<T extends {
   };
 } ? { readonly [K in keyof T as K extends ProtectedKey ? never : K]: K extends typeof typeSymbol ? T[K] : K extends keyof TState ? Immutable<T[K]> : T[K] extends AnyFunction ? (...params: Parameters<T[K]>) => Immutable<ReturnType<T[K]>> : Immutable<T[K]> } : never>;
 //#endregion
-export { SigmaRef as a, castProtected as c, sigma as d, Draft as f, Cleanup as h, SigmaDefinition as i, query as l, typeSymbol as m, ReadableSigma as n, SigmaState as o, Immutable as p, Sigma as r, SigmaTarget as s, Protected as t, setAutoFreeze as u };
+export { SigmaRef as a, castProtected as c, sigma as d, Draft as f, Cleanup as g, AnyResource as h, SigmaDefinition as i, query as l, typeSymbol as m, ReadableSigma as n, SigmaState as o, Immutable as p, Sigma as r, SigmaTarget as s, Protected as t, setAutoFreeze as u };

package/docs/context.md

@@ -53,9 +53,10 @@
 - Publish unpublished changes before `await`, `emit(...)`, promise resolution, or another instance's action: `this.commit()`.
 - React to committed state changes: `sigma.subscribe(instance, handler)` or `sigma.subscribe(instance, key, handler)`.
 - Read one top-level state property as a `ReadonlySignal`: `sigma.getSignal(instance, key)`.
-- Own timers, listeners, subscriptions, or nested setup: `onSetup(...)` plus `setup(...)`.
-- Use a sigma instance inside a component: `useSigma(...)`.
+- Own model lifecycle resources: `onSetup(...)` plus `setup(...)`.
+- Use a component-owned sigma instance: `useSigma(...)`, which runs `onSetup(...)` automatically.
 - Synchronize changed component data into a sigma instance after the initial render: `useSigmaSync(instance, input, sync)`.
+- Own component-local setup resources: `useSetup(...)`.
 - Cast an instance to its readonly consumer view outside a component: `castProtected(instance)`.
 - Subscribe to sigma or DOM events in a component: `useListener(...)`.
 - Subscribe outside components: `listen(instance, ...)`.
@@ -72,7 +73,9 @@
 - Use ordinary actions for routine writes. Reserve `sigma.captureState(...)` and `sigma.replaceState(...)` for replay, reset, restore, or undo-like flows on committed top-level state.
 - Emit directly from standalone `SigmaTarget` instances. In subclasses, emit from actions that have no unpublished draft changes. After mutating state, publish first with `this.commit(); this.emit(...)`.
 - Prefer `listen(...)` for external event subscriptions. It works with sigma targets and DOM targets.
-- Put owned side effects in `onSetup(...)`.
+- Put model-owned side effects in `onSetup(...)`.
+- Use `useSetup(...)` when a component owns setup resources directly. The callback returns cleanup resources, and teardown disposes them in reverse order.
+- A sigma instance created with `useSigma(...)` already runs its `onSetup(...)` method. Do not call `instance.setup(...)` for that same instance from `useSetup(...)`, because that starts a second setup lifecycle.
 - Use `useSigmaSync(...)` when a component-owned sigma instance is initialized from external props or hook data and needs to receive later changes through an action. Pass a plain object with stable keys; values are compared with `Object.is(...)`, and a recreated instance treats the current input as its new baseline.
 - Use `sigma.subscribe(this, ...)` inside `onSetup(...)` when a setup-owned side effect should react to future committed publishes. Return that cleanup so the subscription stops with setup.
   ```ts
@@ -91,6 +94,7 @@
 - Reaching for `sigma.getSignal(instance, key)` when direct property reads already cover the use case.
 - Crossing `emit(...)`, `await`, promise resolution, or another instance's action with unpublished changes. Publish them first with `this.commit()`.
 - Starting side effects during construction instead of through explicit `setup(...)`.
+- Calling `setup(...)` manually for an instance created by `useSigma(...)`.
 - Encoding storage, hydration, or migration policy directly into model classes.
 - Relying on computeds or queries to observe unpublished draft changes inside actions.
 - Treating query calls as memoized across invocations.

package/package.json

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