preact-sigma 6.0.0 → 6.0.2

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as SigmaState, c as query, d as Draft, f as Immutable, i as SigmaRef, l as setAutoFreeze, m as Cleanup, n as Sigma, o as SigmaTarget, p as typeSymbol, r as SigmaDefinition, s as castProtected, t as Protected, u as sigma } from "./sigma-DD7HfTvw.mjs";
+import { a as SigmaState, c as query, d as Draft, f as Immutable, i as SigmaRef, l as setAutoFreeze, m as Cleanup, n as Sigma, o as SigmaTarget, p as typeSymbol, r as SigmaDefinition, s as castProtected, t as Protected, u as sigma } from "./sigma-BhmvUxp9.mjs";
 
 //#region src/defaults.d.ts
 /**

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, t as Sigma } from "./sigma-CJibGQ6g.mjs";
+import { a as setAutoFreeze, c as listenersSymbol, i as query, n as SigmaTarget, o as sigma, r as castProtected, t as Sigma } from "./sigma-tZ0xhlG3.mjs";
 import { useEffect, useRef } from "preact/hooks";
 //#region src/defaults.ts
 /**

package/dist/persist.d.mts

@@ -1,4 +1,4 @@
-import { f as Immutable, n as Sigma } from "./sigma-DD7HfTvw.mjs";
+import { f as Immutable, n as Sigma } from "./sigma-BhmvUxp9.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-CJibGQ6g.mjs";
+import { o as sigma, s as isPlainObject } from "./sigma-tZ0xhlG3.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {

package/dist/{sigma-DD7HfTvw.d.mts → sigma-BhmvUxp9.d.mts}

@@ -88,6 +88,8 @@ type SigmaState<T extends SigmaDefinition> = Sigma<T["state"]> & {
  * Base class for signal-backed state models.
  *
  * `TState` is the source of typing for top-level state keys, subscriptions, signals, and replacement snapshots.
+ * Private class fields stay ordinary instance storage and are not signal-backed, captured,
+ * persisted, or used for reactive invalidation by themselves.
  * Merge a same-named interface with the class when direct property reads should be typed on the instance.
  */
 declare abstract class Sigma<TState extends object> {
@@ -145,7 +147,11 @@ declare const sigma: Readonly<{
   captureState<TState extends object>(instance: Sigma<TState>): Immutable<TState>; /** Publishes a plain-object snapshot as the current committed state. */
   replaceState<TState extends object>(target: Sigma<TState>, nextState: TState): void;
 }>;
-/** Marks a class method as a committed-state reactive read with arguments instead of an action. */
+/**
+ * Marks a class method as a committed-state reactive read with arguments instead of an action.
+ *
+ * Each call creates a reactive read at the call site. Query calls do not memoize results across invocations.
+ */
 declare function query<TThis extends object, TArgs extends any[], TReturn>(method: (this: TThis, ...args: TArgs) => TReturn): (this: TThis, ...args: TArgs) => TReturn;
 declare const protectedSymbol: unique symbol;
 type ProtectedKey = typeof listenersSymbol | typeof snapshotSymbol | "act" | "commit" | "emit" | "onSetup";

package/dist/{sigma-CJibGQ6g.mjs → sigma-tZ0xhlG3.mjs}

@@ -59,21 +59,54 @@ const patchListeners = /* @__PURE__ */ new WeakSet();
 const initializedPrototypes = /* @__PURE__ */ new WeakSet();
 const queries = /* @__PURE__ */ new WeakSet();
 const emptySentinel = {};
-let activeInstance = null;
+let activeActionInstance = null;
+let activeDraftInstance = null;
 let activeDraft;
 let activeDerivedReadDepth = 0;
-function ensureActiveInstance(instance) {
-	if (!activeInstance) {
-		activeInstance = instance;
+let activeSetupInstance = null;
+const pendingAsyncActions = /* @__PURE__ */ new WeakMap();
+function hasPendingAsyncAction(instance) {
+	return pendingAsyncActions.has(instance);
+}
+function addPendingAsyncAction(instance) {
+	pendingAsyncActions.set(instance, (pendingAsyncActions.get(instance) ?? 0) + 1);
+}
+function removePendingAsyncAction(instance) {
+	const count = pendingAsyncActions.get(instance);
+	if (!count) return;
+	if (count === 1) pendingAsyncActions.delete(instance);
+	else pendingAsyncActions.set(instance, count - 1);
+}
+function hasActionContext(instance) {
+	if (activeActionInstance) return activeActionInstance === instance;
+	return hasPendingAsyncAction(instance);
+}
+function createExternalActionError() {
+	const constructorName = (activeDraftInstance ?? activeActionInstance)?.constructor.name;
+	const owner = constructorName ? `Draft for ${constructorName}` : "Draft";
+	return /* @__PURE__ */ new Error(`[preact-sigma] ${owner} was not committed before an external action was invoked.`);
+}
+function beginActionContext(instance) {
+	if (!activeActionInstance) {
+		if (activeDraftInstance && activeDraftInstance !== instance) throw createExternalActionError();
+		activeActionInstance = instance;
 		return false;
 	}
-	if (instance !== activeInstance) throw new Error("Draft was not committed before an external action was invoked.");
+	if (instance !== activeActionInstance) throw createExternalActionError();
 	return true;
 }
-function clearActiveInstance() {
-	activeInstance = null;
+function endActionContext(instance) {
+	if (activeActionInstance === instance) activeActionInstance = null;
+}
+function clearActiveAction() {
+	activeActionInstance = null;
+	activeDraftInstance = null;
 	activeDraft = null;
 }
+function assertActionContext(instance, message) {
+	if (activeActionInstance && activeActionInstance !== instance) throw createExternalActionError();
+	if (!hasActionContext(instance)) throw new Error(message);
+}
 function isStateKey(instance, key) {
 	return Object.hasOwn(instance, key + signalSuffix);
 }
@@ -83,12 +116,30 @@ function getStateSignal(instance, key) {
 function createSnapshot(instance) {
 	if (instance[snapshotSymbol]) return instance[snapshotSymbol];
 	const state = {};
-	for (const key in instance) if (isStateKey(instance, key)) state[key] = instance[key];
+	for (const key in instance) if (isStateKey(instance, key)) state[key] = getStateSignal(instance, key).value;
 	return state;
 }
 function createDraft(instance) {
 	return createDraft$1(createSnapshot(instance));
 }
+function ensureDraft(instance) {
+	if (activeDraftInstance && activeDraftInstance !== instance) throw createExternalActionError();
+	activeDraftInstance = instance;
+	activeDraft ??= createDraft(instance);
+	return activeDraft;
+}
+function readStateProperty(instance, key) {
+	const signal = getStateSignal(instance, key);
+	if (!activeDerivedReadDepth && hasActionContext(instance)) {
+		if (activeDraftInstance === instance) return activeDraft[key];
+		if (isDraftable(signal.value)) return ensureDraft(instance)[key];
+	}
+	return signal.value;
+}
+function writeStateProperty(instance, key, value) {
+	assertActionContext(instance, `[preact-sigma] Cannot set state property "${key}" outside an action.`);
+	ensureDraft(instance)[key] = value;
+}
 function runDerivedRead(callback) {
 	activeDerivedReadDepth += 1;
 	try {
@@ -127,44 +178,15 @@ function publishState(instance, nextState, baseState, patches, inversePatches) {
 		listener(nextState, baseState, patches, inversePatches);
 	});
 }
-function createActionContext(instance) {
-	return new Proxy(instance, {
-		get(target, key, receiver) {
-			if (typeof key === "string" && isStateKey(target, key)) {
-				if (activeDraft) {
-					ensureActiveInstance(target);
-					return activeDraft[key];
-				}
-				const { value } = getStateSignal(target, key);
-				if (isDraftable(value)) {
-					activeDraft = createDraft(instance);
-					return activeDraft[key];
-				}
-				return value;
-			}
-			if (key === instanceSymbol) return instance;
-			return Reflect.get(target, key, receiver);
-		},
-		set(target, key, value) {
-			if (typeof key === "string" && isStateKey(target, key)) {
-				ensureActiveInstance(instance);
-				activeDraft ??= createDraft(instance);
-				activeDraft[key] = value;
-				return true;
-			}
-			return Reflect.set(target, key, value);
-		}
-	});
-}
 function getActionInstance(context) {
 	return context[instanceSymbol];
 }
-function ensureDraftCommitted(instance) {
-	if (activeInstance && instance !== activeInstance) throw new Error("Draft was not committed before an external action was invoked.");
-	activeInstance = null;
+function commitDraft(instance) {
+	if (activeDraftInstance && instance !== activeDraftInstance) throw createExternalActionError();
 	if (!activeDraft) return false;
 	const draft = activeDraft;
 	activeDraft = null;
+	activeDraftInstance = null;
 	let patches;
 	let inversePatches;
 	let patchListener;
@@ -178,6 +200,32 @@ function ensureDraftCommitted(instance) {
 	if (changed) publishState(instance, nextState, baseState, patches, inversePatches);
 	return changed;
 }
+function hasStateChanges(baseState, nextState) {
+	const baseKeys = Object.keys(baseState);
+	const nextKeys = Object.keys(nextState);
+	if (baseKeys.length !== nextKeys.length) return true;
+	for (const key of nextKeys) if (!Object.hasOwn(baseState, key) || !Object.is(baseState[key], nextState[key])) return true;
+	return false;
+}
+function createReplacementPatches(baseState, nextState) {
+	let patches;
+	let inversePatches;
+	const draft = createDraft$1(baseState);
+	const missingKeys = new Set(Object.keys(baseState));
+	for (const key in nextState) {
+		draft[key] = nextState[key];
+		missingKeys.delete(key);
+	}
+	for (const key of missingKeys) delete draft[key];
+	finishDraft(draft, (nextPatches, nextInversePatches) => {
+		patches = nextPatches;
+		inversePatches = nextInversePatches;
+	});
+	return {
+		inversePatches,
+		patches
+	};
+}
 function initializePrototype(prototype) {
 	const descriptors = Object.getOwnPropertyDescriptors(prototype);
 	for (const key in descriptors) {
@@ -192,31 +240,54 @@ function initializePrototype(prototype) {
 			descriptors[key].value = function(...args) {
 				if (activeDerivedReadDepth) throw new Error("[preact-sigma] Computeds and queries cannot call actions.");
 				const instance = getActionInstance(this);
-				if (ensureActiveInstance(instance)) {
-					const result = value.apply(this, args);
+				if (beginActionContext(instance)) {
+					const result = value.apply(instance, args);
 					assertActionResult(key, result);
 					return result;
 				}
 				let result;
 				try {
-					const actionContext = createActionContext(instance);
-					result = actionFn.apply(actionContext, args);
+					result = actionFn.apply(instance, args);
 					assertActionResult(key, result);
 				} catch (error) {
-					clearActiveInstance();
+					clearActiveAction();
+					throw error;
+				}
+				let changed;
+				try {
+					changed = commitDraft(instance);
+				} catch (error) {
+					clearActiveAction();
 					throw error;
 				}
-				const changed = ensureDraftCommitted(instance);
 				if (isPromiseLike(result)) {
-					if (changed) throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before returning a promise.`);
+					if (changed) {
+						endActionContext(instance);
+						throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before returning a promise.`);
+					}
+					addPendingAsyncAction(instance);
+					endActionContext(instance);
 					const onResolveAsyncAction = (promiseResult) => {
-						if (activeDraft && instance === activeInstance) {
-							if (ensureDraftCommitted(instance)) throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before its promise resolved.`);
+						try {
+							if (activeDraft && instance === activeDraftInstance) {
+								if (commitDraft(instance)) throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before its promise resolved.`);
+							}
+							return promiseResult;
+						} finally {
+							removePendingAsyncAction(instance);
+						}
+					};
+					const onRejectAsyncAction = (error) => {
+						if (activeDraftInstance === instance) {
+							activeDraft = null;
+							activeDraftInstance = null;
 						}
-						return promiseResult;
+						removePendingAsyncAction(instance);
+						throw error;
 					};
-					return result.then(onResolveAsyncAction);
+					return result.then(onResolveAsyncAction, onRejectAsyncAction);
 				}
+				endActionContext(instance);
 				return result;
 			};
 		}
@@ -235,24 +306,14 @@ function disposeCleanupResource(resource) {
 	else if ("dispose" in resource) resource.dispose();
 	else resource[Symbol.dispose]();
 }
-function act(fn) {
-	const instance = getActionInstance(this);
-	if (instance !== this) throw new Error("Cannot act() from inside an action.");
-	ensureActiveInstance(instance);
-	try {
-		const context = createActionContext(instance);
-		if (isPromiseLike(action(fn).call(context))) throw new Error("[preact-sigma] act() callbacks must be synchronous");
-	} catch (error) {
-		clearActiveInstance();
-		throw error;
-	}
-	ensureDraftCommitted(instance);
-}
 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, {
 		get() {
-			return this[key + signalSuffix].value;
+			return readStateProperty(this, key);
+		},
+		set(value) {
+			writeStateProperty(this, key, value);
 		},
 		enumerable: true
 	});
@@ -261,6 +322,8 @@ function defineSignalProperty(instance, key, value) {
 * Base class for signal-backed state models.
 *
 * `TState` is the source of typing for top-level state keys, subscriptions, signals, and replacement snapshots.
+* Private class fields stay ordinary instance storage and are not signal-backed, captured,
+* persisted, or used for reactive invalidation by themselves.
 * Merge a same-named interface with the class when direct property reads should be typed on the instance.
 */
 var Sigma = class {
@@ -278,12 +341,15 @@ var Sigma = class {
 	}
 	/** Runs `onSetup(...)` and returns a cleanup that disposes returned resources in reverse order. */
 	setup(...args) {
-		const setupContext = new Proxy(this, { get(target, key, receiver) {
-			if (key === instanceSymbol) return target;
-			if (key === "act") return act.bind(target);
-			return Reflect.get(target, key, receiver);
-		} });
-		const resources = this.onSetup.apply(setupContext, args);
+		const instance = getActionInstance(this);
+		const previousSetupInstance = activeSetupInstance;
+		activeSetupInstance = instance;
+		let resources;
+		try {
+			resources = this.onSetup.apply(instance, args);
+		} finally {
+			activeSetupInstance = previousSetupInstance;
+		}
 		return () => {
 			for (let i = resources.length - 1; i >= 0; i--) disposeCleanupResource(resources[i]);
 		};
@@ -296,19 +362,24 @@ var Sigma = class {
 	*/
 	commit(callback) {
 		const instance = getActionInstance(this);
-		if (instance === this) throw new Error("Cannot commit() from outside an action.");
-		ensureDraftCommitted(instance);
-		if (callback) {
-			const context = new Proxy(instance, { get(target, key, receiver) {
-				if (key === instanceSymbol) return instance;
-				return Reflect.get(target, key, receiver);
-			} });
-			return callback.call(context);
-		}
+		assertActionContext(instance, "Cannot commit() from outside an action.");
+		commitDraft(instance);
+		if (callback) return callback.call(instance);
 	}
 	/** Runs a synchronous setup-owned callback with action semantics from an `onSetup(...)` context. */
 	act(fn) {
-		throw new Error("Cannot act() from outside an onSetup() context.");
+		const instance = getActionInstance(this);
+		if (activeSetupInstance !== instance) throw new Error("Cannot act() from outside an onSetup() context.");
+		if (activeActionInstance === instance) throw new Error("Cannot act() from inside an action.");
+		beginActionContext(instance);
+		try {
+			if (isPromiseLike(action(fn).call(instance))) throw new Error("[preact-sigma] act() callbacks must be synchronous");
+			commitDraft(instance);
+		} catch (error) {
+			clearActiveAction();
+			throw error;
+		}
+		endActionContext(instance);
 	}
 };
 /** Casts a sigma instance to its readonly public consumer view. */
@@ -328,8 +399,8 @@ var SigmaTarget = class extends Sigma {
 	/** Emits a typed event from an action after unpublished draft changes are committed. */
 	emit(name, ...[detail]) {
 		const instance = getActionInstance(this);
-		if (instance === this) throw new Error("Cannot emit() from outside an action.");
-		if (instance === activeInstance && activeDraft) throw new Error("Cannot emit() until you commit() your draft.");
+		assertActionContext(instance, "Cannot emit() from outside an action.");
+		if (instance === activeDraftInstance && activeDraft) throw new Error("Cannot emit() until you commit() your draft.");
 		this[listenersSymbol].emit(name, detail);
 	}
 };
@@ -365,11 +436,19 @@ const sigma = /* @__PURE__ */ Object.freeze({
 		if (activeDraft) throw new Error(`[preact-sigma] replaceState() cannot run while an action has unpublished changes.`);
 		const instance = getActionInstance(target);
 		const baseState = createSnapshot(instance);
-		const patches = hasPatchListeners(instance) ? [] : void 0;
-		publishState(instance, nextState, baseState, patches, patches ? [] : void 0);
+		if (!hasStateChanges(baseState, nextState)) return;
+		const { inversePatches, patches } = hasPatchListeners(instance) ? createReplacementPatches(baseState, nextState) : {
+			inversePatches: void 0,
+			patches: void 0
+		};
+		publishState(instance, nextState, baseState, patches, inversePatches);
 	}
 });
-/** Marks a class method as a committed-state reactive read with arguments instead of an action. */
+/**
+* Marks a class method as a committed-state reactive read with arguments instead of an action.
+*
+* Each call creates a reactive read at the call site. Query calls do not memoize results across invocations.
+*/
 function query(method) {
 	queries.add(method);
 	function queryMethod(...args) {

package/docs/context.md

@@ -22,6 +22,7 @@
 - Sigma class: a class that extends `Sigma<TState>` and passes its initial top-level state to `super(...)`. The `TState` argument drives helper typing for subscriptions, signals, and replacement snapshots; a same-named merged interface gives direct property reads their instance types.
 - Sigma target: a class that extends `SigmaTarget<TEvents, TState>` when it also emits typed events. Use `SigmaTarget<TEvents>` for event-only targets.
 - State property: a top-level key from `TState`. Each key becomes a reactive public property and has its own signal.
+- Private field: an ECMAScript `#field` on the model class. Private fields are ordinary instance storage. They can be read from model members, but they do not create signals or invalidate reactive reads by themselves.
 - Computed: an argument-free derived getter on the class prototype that reads committed state.
 - Query: a reactive read method that accepts arguments, is marked with the `query` decorator, and reads committed state.
 - Action: a prototype method that is not marked as a query. Actions read and write state properties through sigma's draft and commit semantics.
@@ -62,6 +63,7 @@
 
 - Put the state shape in a named `State` type, pass it to `Sigma<TState>` or `SigmaTarget<TEvents, TState>`, then merge a same-named interface with the class for direct property typing.
 - Keep frequently read values as separate top-level state properties. Each top-level key gets its own signal.
+- Use private fields for ephemeral caches, handles, or bookkeeping when private-only changes should not be captured, restored, persisted, used as subscription keys, or published reactively.
 - Use getters for argument-free derived reads.
 - Use `@query` for tracked reads with arguments.
 - Derive directly from state properties inside an action when the calculation needs unpublished draft values.
@@ -94,6 +96,7 @@
 # Invariants and Constraints
 
 - Sigma tracks top-level state properties. Each top-level key gets its own signal.
+- Private fields are not top-level state properties. They do not create signals, appear in committed snapshots, participate in persistence helpers, or drive subscriptions by themselves. Computeds and queries that read private fields update when their signal-backed state dependencies change; private-only changes do not invalidate those reads.
 - Protected consumer views expose immutable state and callable actions.
 - Published draftable public state is deep-frozen by default. `setAutoFreeze(false)` disables that behavior globally.
 - Computeds and queries read committed state, including when called inside actions.

package/package.json

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