preact-sigma 6.0.1 → 6.1.0

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-D1V3m1xk.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-CadB76LN.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-DTMODzf8.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-0X8yJrUR.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-D1V3m1xk.mjs";
+import { f as Immutable, n as Sigma } from "./sigma-CadB76LN.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-DTMODzf8.mjs";
+import { o as sigma, s as isPlainObject } from "./sigma-0X8yJrUR.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {

package/dist/{sigma-DTMODzf8.mjs → sigma-0X8yJrUR.mjs}

@@ -322,7 +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, or persisted.
+* 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 {
@@ -390,15 +391,22 @@ function castProtected(instance) {
 *
 * `TEvents` maps event names to payload types, and `TState` types reactive state.
 */
-var SigmaTarget = class extends Sigma {
+var SigmaTarget = class SigmaTarget extends Sigma {
 	[listenersSymbol] = new SigmaListenerMap();
 	constructor(state) {
 		super(state ?? emptySentinel);
 	}
-	/** Emits a typed event from an action after unpublished draft changes are committed. */
+	/**
+	* Emits a typed event.
+	*
+	* Directly constructed targets can emit from ordinary code. Subclasses emit from action context
+	* after unpublished draft changes are committed.
+	*/
 	emit(name, ...[detail]) {
 		const instance = getActionInstance(this);
-		assertActionContext(instance, "Cannot emit() from outside an action.");
+		if (Object.getPrototypeOf(instance) === SigmaTarget.prototype) {
+			if (activeDraft) throw createExternalActionError();
+		} else 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);
 	}
@@ -443,7 +451,11 @@ const sigma = /* @__PURE__ */ Object.freeze({
 		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/dist/{sigma-D1V3m1xk.d.mts → sigma-CadB76LN.d.mts}

@@ -88,7 +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, or persisted.
+ * 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> {
@@ -127,7 +128,12 @@ declare class SigmaTarget<TEvents extends object = {}, TState extends object = {
   };
   protected [listenersSymbol]: SigmaListenerMap;
   constructor(state?: TState);
-  /** Emits a typed event from an action after unpublished draft changes are committed. */
+  /**
+   * Emits a typed event.
+   *
+   * Directly constructed targets can emit from ordinary code. Subclasses emit from action context
+   * after unpublished draft changes are committed.
+   */
   emit<TEvent extends string & keyof TEvents>(name: TEvent, ...[detail]: EventParameters<TEvents[TEvent]>): void;
 }
 /** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
@@ -146,7 +152,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/docs/context.md

@@ -20,14 +20,14 @@
 # Core Abstractions
 
 - 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.
+- Sigma target: a class that extends `SigmaTarget<TEvents>` for typed event actions or `SigmaTarget<TEvents, TState>` when it also owns state. Use `new SigmaTarget<TEvents>()` for standalone 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, not signal-backed state.
+- 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.
 - Setup handler: an optional `onSetup(...)` method that owns side effects and returns cleanup resources.
-- Event: a typed notification emitted with `this.emit(...)` inside an action and observed through `listen(...)` or `useListener(...)`.
+- Event: a typed notification emitted with `this.emit(...)` inside an action, or with `emit(...)` on a directly constructed `SigmaTarget`, and observed through `listen(...)` or `useListener(...)`.
 - Protected view: the readonly consumer view returned by `castProtected(...)` and `useSigma(...)`.
 
 # Data Flow / Lifecycle
@@ -45,6 +45,7 @@
 
 - Define reusable model state: `class Model extends Sigma<TState>`.
 - Define reusable model state with events: `class Model extends SigmaTarget<TEvents, TState>`.
+- Define a standalone typed event target: `new SigmaTarget<TEvents>()`.
 - Merge partial constructor input with defaults: `mergeDefaults(initial, defaults)`.
 - Derive an argument-free value: a class getter.
 - Derive a reactive read with arguments: an `@query` class method.
@@ -63,12 +64,12 @@
 
 - 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 that should not be captured, restored, persisted, or used as subscription keys.
+- 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.
 - 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 actions that have no unpublished draft changes. After mutating state, publish first with `this.commit(); this.emit(...)`.
+- 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(...)`.
 - 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.
@@ -96,7 +97,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.
+- 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.
@@ -104,14 +105,14 @@
 - Setup handlers return arrays of cleanup resources, and cleanup runs in reverse order.
 - Call Immer's `enablePatches()` before relying on `sigma.subscribe(instance, handler, { patches: true })`.
 - `sigma.replaceState(...)` works on committed top-level state and requires a plain object snapshot.
-- `SigmaTarget.emit(...)` runs from an action and requires no active unpublished draft. It does not need a `commit(...)` callback.
+- `SigmaTarget.emit(...)` runs directly on standalone targets. In subclasses, it runs from an action and requires no active unpublished draft.
 
 # Error Model
 
 - Crossing an action boundary with unpublished changes throws until `this.commit()` publishes them. Async actions also reject when they finish with unpublished changes.
 - Calling `commit(...)` outside an action throws.
 - Calling `act(...)` outside an `onSetup(...)` setup context throws.
-- Calling `emit(...)` outside an action or before committing the active draft throws.
+- Calling `emit(...)` outside an action on a subclass, or before committing the active draft, throws.
 - Calling an action from a computed or query throws.
 - Returning an active draft from an action throws.
 - `sigma.replaceState(...)` throws when the replacement value is not a plain object or when an action still owns unpublished changes.

package/docs/migrations/v5-to-v6.md

@@ -116,7 +116,7 @@ interface TodoList extends TodoListState {}
 
 ## Events
 
-`SigmaTarget` now takes event types first. Use `SigmaTarget<TEvents>` for event-only targets and `SigmaTarget<TEvents, TState>` for targets that also own state.
+`SigmaTarget` now takes event types first. Use `new SigmaTarget<TEvents>()` for standalone event-only targets, `class Model extends SigmaTarget<TEvents>` for event-only action classes, and `SigmaTarget<TEvents, TState>` for class targets that also own state.
 
 ```ts
 import { listen, SigmaTarget } from "preact-sigma";
@@ -140,7 +140,7 @@ const stop = listen(notifications, "saved", ({ id }) => {
 });
 ```
 
-`emit(...)` runs inside actions. If an action mutates state before emitting, publish first with `this.commit()`.
+Directly constructed `SigmaTarget` instances can emit from ordinary code. Subclasses emit inside actions. If an action mutates state before emitting, publish first with `this.commit()`.
 
 ## Commit Boundaries
 

package/package.json

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