preact-sigma 6.0.2 → 6.1.1

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-c48-qjsH.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,7 +1,13 @@
-import { f as Immutable, n as Sigma } from "./sigma-BhmvUxp9.mjs";
+import { f as Immutable, n as Sigma, t as Protected } from "./sigma-c48-qjsH.mjs";
 
 //#region src/persist.d.ts
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * Sigma instance or protected consumer view accepted by persistence helpers.
+ *
+ * Restore and hydrate helpers may replace committed state through this trusted owner boundary.
+ */
+type PersistInstance<TState extends object> = Sigma<TState> | Protected<Sigma<TState>>;
 /** Decode-time context passed to persistence codecs. */
 interface PersistDecodeContext<TState extends object> {
   /** Storage key used to read the record being decoded. */
@@ -108,19 +114,19 @@ interface SyncHydrationHandle extends PersistenceHandle {
   readonly restored: RestoreResult;
 }
 /** Restores committed state from a persisted record through an async store. */
-declare function restore<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): Promise<RestoreResult>;
-declare function restore<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): Promise<RestoreResult>;
+declare function restore<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: PickPersistOptions<TState, TKey>): Promise<RestoreResult>;
+declare function restore<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: PersistOptions<TState, TStored>): Promise<RestoreResult>;
 /** Restores committed state from a persisted record through a sync store. */
-declare function restoreSync<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: SyncPickPersistOptions<TState, TKey>): RestoreResult;
-declare function restoreSync<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: SyncPersistOptions<TState, TStored>): RestoreResult;
+declare function restoreSync<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: SyncPickPersistOptions<TState, TKey>): RestoreResult;
+declare function restoreSync<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: SyncPersistOptions<TState, TStored>): RestoreResult;
 /** Persists future committed state changes for one sigma instance. */
-declare function persist<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): PersistenceHandle;
-declare function persist<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): PersistenceHandle;
+declare function persist<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: PickPersistOptions<TState, TKey>): PersistenceHandle;
+declare function persist<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: PersistOptions<TState, TStored>): PersistenceHandle;
 /** Restores state, then begins persisting future committed changes. */
-declare function hydrate<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): HydrationHandle;
-declare function hydrate<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): HydrationHandle;
+declare function hydrate<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: PickPersistOptions<TState, TKey>): HydrationHandle;
+declare function hydrate<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: PersistOptions<TState, TStored>): HydrationHandle;
 /** Restores state synchronously, then begins persisting future committed changes. */
-declare function hydrateSync<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: SyncPickPersistOptions<TState, TKey>): SyncHydrationHandle;
-declare function hydrateSync<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: SyncPersistOptions<TState, TStored>): SyncHydrationHandle;
+declare function hydrateSync<TState extends object, TKey extends keyof TState>(instance: PersistInstance<TState>, options: SyncPickPersistOptions<TState, TKey>): SyncHydrationHandle;
+declare function hydrateSync<TState extends object, TStored = Immutable<TState>>(instance: PersistInstance<TState>, options: SyncPersistOptions<TState, TStored>): SyncHydrationHandle;
 //#endregion
 export { HydrationHandle, PersistCodec, PersistDecodeContext, PersistErrorContext, PersistOptions, PersistRecord, PersistSchedule, PersistStore, PersistenceHandle, PickPersistOptions, RestoreResult, SyncHydrationHandle, SyncPersistOptions, SyncPersistStore, SyncPickPersistOptions, hydrate, hydrateSync, persist, restore, restoreSync };

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-c48-qjsH.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. */
@@ -163,6 +168,6 @@ type Protected<T extends Sigma<any>> = BrandProtected<T extends {
   [typeSymbol]: {
     state: infer TState extends object;
   };
-} ? { [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>;
+} ? { 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 { SigmaState as a, query as c, Draft as d, Immutable as f, SigmaRef as i, setAutoFreeze as l, Cleanup as m, Sigma as n, SigmaTarget as o, typeSymbol as p, SigmaDefinition as r, castProtected as s, Protected as t, sigma as u };

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/docs/persist.md

@@ -29,6 +29,7 @@ Use the persist module when those primitives are the right boundary, but you do
 
 ## Core Pieces
 
+- Instance: a raw `Sigma` instance or a protected consumer view returned by `castProtected(...)` or `useSigma(...)`.
 - Store: owns `get`, `set`, and `delete` for persisted records. These names match [Keyv](https://github.com/jaredwray/keyv) and `Map`.
 - Codec: owns payload shape, versioning, and migration logic between stored data and a full committed snapshot.
 - Pick options: persist selected top-level keys without writing a custom codec.
@@ -54,6 +55,7 @@ Use the persist module when those primitives are the right boundary, but you do
 
 ## Constraints
 
+- Persistence helpers are trusted external model owners. Restore and hydrate helpers may replace committed state even when they receive a protected consumer view.
 - `sigma.replaceState(...)` requires a plain object replacement snapshot. In supported TypeScript usage, pass the class's full `TState` shape.
 - Custom partial persistence codecs should reconstruct a full replacement snapshot before restore finishes.
 - Nested sigma-state values are stored only if the chosen codec and payload format support them explicitly.

package/package.json

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