preact-sigma 6.0.2 → 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-BhmvUxp9.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-tZ0xhlG3.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-BhmvUxp9.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-tZ0xhlG3.mjs";
+import { o as sigma, s as isPlainObject } from "./sigma-0X8yJrUR.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {

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

@@ -391,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);
 	}

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

@@ -128,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. */

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. 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.
@@ -68,7 +69,7 @@
 - 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.
@@ -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.2",
+  "version": "6.1.0",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",