preact-sigma 6.2.1 → 6.3.1

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-cb2HeDjg.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-thcYEnFu.mjs";
 
 //#region src/defaults.d.ts
 /**
@@ -44,7 +44,14 @@ declare function useListener<TTarget extends Listenable, TEvent extends InferEve
 //#region src/hooks/useSigma.d.ts
 /** Setup arguments and recreation dependencies for `useSigma(...)`. */
 type UseSigmaOptions<TSetup extends readonly any[] = any[]> = {
-  /** Arguments passed to the sigma instance's `onSetup(...)` method. */setup: TSetup | (() => TSetup); /** Dependencies that recreate the sigma instance when they change. */
+  /**
+   * Arguments passed to the sigma instance's `onSetup(...)` method.
+   *
+   * Array setup arguments also drive setup cleanup and rerun. Function setup is
+   * evaluated for the current setup run, but it does not make captured render
+   * values reactive by itself; pass an array when setup inputs should rerun.
+   */
+  setup: TSetup | (() => TSetup); /** Dependencies that recreate the sigma instance when they change. */
   deps?: readonly any[];
 };
 /** Infers the accepted `useSigma(...)` call shape from a sigma class and its setup parameters. */
@@ -54,7 +61,9 @@ 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. Array
+ * setup arguments rerun setup when they change; `deps` recreates the instance.
  */
 declare function useSigma<T extends Sigma<any>>(...args: UseSigmaArgs<T>): Protected<T>;
 //#endregion
@@ -72,4 +81,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-B7kPkW-M.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-cb2HeDjg.mjs";
+import { n as ReadableSigma, p as Immutable, r as Sigma } from "./sigma-thcYEnFu.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-B7kPkW-M.mjs";
+import { c as isPlainObject, o as sigma } from "./sigma-BH9WolKc.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {

package/dist/{sigma-B7kPkW-M.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);
 		};
 	}
 	/**
@@ -472,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-cb2HeDjg.d.mts → sigma-thcYEnFu.d.mts}

@@ -3,7 +3,14 @@ import { Patch } from "immer";
 
 //#region src/internal/utils.d.ts
 type AnyFunction = (...args: any[]) => any;
+/** Cleanup function returned by setup-owned resources and run during teardown. */
 type Cleanup = () => void;
+/**
+ * Resource shape accepted from `onSetup(...)` and `useSetup(...)`.
+ *
+ * Teardown disposes resources in reverse order and accepts cleanup functions,
+ * objects with `dispose()`, and objects with `[Symbol.dispose]()`.
+ */
 type AnyResource = Cleanup | {
   dispose(): void;
 } | {
@@ -172,4 +179,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.1",
+  "version": "6.3.1",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",
@@ -24,6 +24,14 @@
       "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",
@@ -42,11 +50,5 @@
     "immer": ">=11",
     "preact": ">=10"
   },
-  "scripts": {
-    "build": "tsdown",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
-    "fmt": "oxfmt",
-    "lint": "oxlint"
-  }
-}
+  "packageManager": "pnpm@11.5.1"
+}