preact-sigma 2.2.3 → 2.3.0

package/README.md

@@ -43,5 +43,5 @@ console.log(counter.doubled); // 2
 - Concepts, lifecycle, invariants, and API selection live in [`docs/context.md`](./docs/context.md).
 - Quick-start usage lives in [`examples/basic-counter.ts`](./examples/basic-counter.ts).
 - An advanced end-to-end example lives in [`examples/command-palette.tsx`](./examples/command-palette.tsx).
-- Focused examples for non-obvious APIs live in [`examples/async-commit.ts`](./examples/async-commit.ts), [`examples/observe-and-restore.ts`](./examples/observe-and-restore.ts), [`examples/signal-access.ts`](./examples/signal-access.ts), and [`examples/setup-act.ts`](./examples/setup-act.ts).
+- Focused examples for non-obvious APIs live in [`examples/async-commit.ts`](./examples/async-commit.ts), [`examples/observe-and-restore.ts`](./examples/observe-and-restore.ts), [`examples/setup-act.ts`](./examples/setup-act.ts), [`examples/sigma-target.ts`](./examples/sigma-target.ts), and [`examples/signal-access.ts`](./examples/signal-access.ts).
 - Exact exported signatures live in `dist/index.d.mts` after `pnpm build`.

package/dist/index.d.mts

@@ -160,7 +160,7 @@ declare function replaceState<T extends AnySigmaState>(publicInstance: T, nextSt
 //#endregion
 //#region src/framework.d.ts
 /** Checks whether a value is an instance created by a configured sigma type. */
-declare function isSigmaState(value: unknown): value is AnySigmaState;
+declare function isSigmaState(value: object): value is AnySigmaState;
 /**
  * Creates a standalone tracked query helper with the same signature as `fn`.
  *
@@ -272,22 +272,45 @@ interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefault
 }
 //#endregion
 //#region src/listener.d.ts
-type TryGet<T, K extends PropertyKey, TCatch = never> = K extends keyof T ? T[K] : TCatch;
-type TypedEventListener<TEventMap, TEvent extends string, TCurrentTarget extends EventTarget> = ((event: TryGet<TEventMap, string extends TEvent ? keyof TEventMap : TEvent, CustomEvent> & {
-  readonly currentTarget: TCurrentTarget;
-}) => void) & {
-  __eventType?: string extends TEvent ? keyof TEventMap : TEvent;
-};
+type InferEventMap<TTarget extends EventTarget> = TTarget extends {
+  [sigmaEventsBrand]: infer TEvents extends AnyEvents;
+} ? TEvents : TTarget extends Window ? WindowEventMap : TTarget extends Document ? DocumentEventMap : TTarget extends HTMLBodyElement ? HTMLBodyElementEventMap : TTarget extends HTMLMediaElement ? HTMLMediaElementEventMap : TTarget extends HTMLElement ? HTMLElementEventMap : TTarget extends SVGSVGElement ? SVGSVGElementEventMap : TTarget extends SVGElement ? SVGElementEventMap : never;
+type InferListenerArgs<TEvents extends object, TTarget extends EventTarget, TEvent extends string> = [(TEvent extends keyof TEvents ? TEvents[TEvent] : never) extends infer TPayload ? TTarget extends {
+  [sigmaEventsBrand]: TEvents;
+} ? [TPayload] extends [never] ? never : [TPayload] extends [void] ? undefined : TPayload : ([TPayload] extends [never] ? CustomEvent : Extract<TPayload, Event>) & {
+  readonly currentTarget: TTarget;
+} : never];
+/** Infers the listener callback shape for a target and event name. Sigma states receive payloads directly, while DOM targets receive typed events. */
+type InferListener<TTarget extends EventTarget, TEvent extends string = string> = InferEventMap<TTarget> extends infer TEvents extends object ? ((...args: InferListenerArgs<TEvents, TTarget, TEvent>) => void) & {
+  __eventType?: TEvent;
+} : never;
 /** Infers the event names accepted by `listen(...)` or `useListener(...)` for a target. */
 type InferEventType<TTarget extends EventTarget> = (InferListener<TTarget> extends {
   __eventType?: infer TEvent;
 } ? string & TEvent : never) | (string & {});
-/** Infers the listener callback shape for a target and event name. Sigma states receive payloads directly, while DOM targets receive typed events. */
-type InferListener<TTarget extends EventTarget, TEvent extends string = string> = TTarget extends AnySigmaStateWithEvents<infer TEvents> ? TEvent extends keyof TEvents ? (event: TEvents[TEvent]) => void : never : TTarget extends Window ? TypedEventListener<WindowEventMap, TEvent, TTarget> : TTarget extends Document ? TypedEventListener<DocumentEventMap, TEvent, TTarget> : TTarget extends HTMLBodyElement ? TypedEventListener<HTMLBodyElementEventMap, TEvent, TTarget> : TTarget extends HTMLMediaElement ? TypedEventListener<HTMLMediaElementEventMap, TEvent, TTarget> : TTarget extends HTMLElement ? TypedEventListener<HTMLElementEventMap, TEvent, TTarget> : TTarget extends SVGSVGElement ? TypedEventListener<SVGSVGElementEventMap, TEvent, TTarget> : TTarget extends SVGElement ? TypedEventListener<SVGElementEventMap, TEvent, TTarget> : (event: Event & {
-  readonly currentTarget: TTarget;
-}) => void;
+/**
+ * A standalone typed event hub with `emit(...)` and `on(...)` methods and full
+ * `EventTarget`, `listen(...)`, and `useListener(...)` compatibility.
+ */
+declare class SigmaTarget<TEvents extends AnyEvents = {}> extends EventTarget {
+  readonly [sigmaEventsBrand]: TEvents;
+  /**
+   * Emits a typed event from the hub.
+   *
+   * Void events dispatch a plain `Event`. Payload events dispatch a
+   * `CustomEvent` whose `detail` holds the payload.
+   */
+  emit<TEvent extends string & keyof TEvents>(name: TEvent, ...args: [TEvents[TEvent]] extends [void] ? [] : [payload: TEvents[TEvent]]): void;
+  /**
+   * Registers a typed event listener and returns an unsubscribe function.
+   *
+   * Payload events pass their payload directly to the listener. Void events
+   * call the listener with no arguments.
+   */
+  on<TEvent extends string & keyof TEvents>(name: TEvent, listener: (...args: InferListenerArgs<TEvents, this, TEvent>) => void): () => void;
+}
 /** Adds a listener to a sigma state or DOM target and returns a cleanup function that removes it. */
-declare function listen<TTarget extends EventTarget, TEvent extends InferEventType<TTarget>>(target: TTarget, name: TEvent, fn: InferListener<TTarget, TEvent>): () => void;
+declare function listen<TTarget extends EventTarget, TEvent extends InferEventType<TTarget>>(target: TTarget, name: TEvent, listener: InferListener<TTarget, TEvent>): () => void;
 //#endregion
 //#region src/hooks.d.ts
 /**
@@ -306,4 +329,4 @@ declare function useSigma<T extends AnySigmaState>(create: () => T, setupArgs?:
  */
 declare function useListener<TTarget extends EventTarget | AnySigmaState, TEvent extends InferEventType<TTarget>>(target: TTarget | null, name: TEvent, listener: InferListener<TTarget, TEvent>): void;
 //#endregion
-export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { type AnyDefaultState, type AnyEvents, type AnyResource, type AnySigmaState, type AnySigmaStateWithEvents, type AnyState, InferEventType, InferListener, type InferSetupArgs, type SigmaObserveChange, type SigmaObserveOptions, type SigmaRef, type SigmaState, SigmaTarget, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/dist/index.mjs

@@ -541,7 +541,7 @@ Object.defineProperty(Sigma.prototype, sigmaStateBrand, { value: true });
 //#region src/framework.ts
 /** Checks whether a value is an instance created by a configured sigma type. */
 function isSigmaState(value) {
-	return Boolean(value && typeof value === "object" && value[sigmaStateBrand]);
+	return Boolean(value[sigmaStateBrand]);
 }
 /**
 * Creates a standalone tracked query helper with the same signature as `fn`.
@@ -629,12 +629,40 @@ var SigmaType = class extends Function {
 };
 //#endregion
 //#region src/listener.ts
+/**
+* A standalone typed event hub with `emit(...)` and `on(...)` methods and full
+* `EventTarget`, `listen(...)`, and `useListener(...)` compatibility.
+*/
+var SigmaTarget = class extends EventTarget {
+	/**
+	* Emits a typed event from the hub.
+	*
+	* Void events dispatch a plain `Event`. Payload events dispatch a
+	* `CustomEvent` whose `detail` holds the payload.
+	*/
+	emit(name, ...args) {
+		this.dispatchEvent(args.length === 0 ? new Event(name) : new CustomEvent(name, { detail: args[0] }));
+	}
+	/**
+	* Registers a typed event listener and returns an unsubscribe function.
+	*
+	* Payload events pass their payload directly to the listener. Void events
+	* call the listener with no arguments.
+	*/
+	on(name, listener) {
+		const adapter = (event) => listener(event.detail);
+		this.addEventListener(name, adapter);
+		return () => {
+			this.removeEventListener(name, adapter);
+		};
+	}
+};
 /** Adds a listener to a sigma state or DOM target and returns a cleanup function that removes it. */
-function listen(target, name, fn) {
-	const listener = isSigmaState(target) ? (event) => fn(event.detail) : fn;
-	target.addEventListener(name, listener);
+function listen(target, name, listener) {
+	const adapter = isSigmaState(target) || target instanceof SigmaTarget ? (event) => listener(event.detail) : listener;
+	target.addEventListener(name, adapter);
 	return () => {
-		target.removeEventListener(name, listener);
+		target.removeEventListener(name, adapter);
 	};
 }
 //#endregion
@@ -669,4 +697,4 @@ function useListener(target, name, listener) {
 	}, [target, name]);
 }
 //#endregion
-export { SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };
+export { SigmaTarget, SigmaType, action, batch, computed, effect, freeze, immerable, isSigmaState, listen, query, replaceState, setAutoFreeze, snapshot, untracked, useListener, useSigma };

package/docs/context.md

@@ -1,6 +1,6 @@
 # Overview
 
-`preact-sigma` builds reusable state models from one definition. A configured `SigmaType` owns top-level state, derived reads, writes, setup handlers, and typed events. Each top-level state property is exposed as a reactive public property backed by its own Preact signal, while actions use Immer-style mutation semantics to publish committed state.
+`preact-sigma` builds reusable state models from one definition. A configured `SigmaType` owns top-level state, derived reads, writes, setup handlers, and typed events. Each top-level state property is exposed as a reactive public property backed by its own Preact signal, while actions use Immer-style mutation semantics to publish committed state. For event-only flows, `SigmaTarget` provides a standalone typed event hub with no managed state.
 
 # When to Use
 
@@ -21,6 +21,7 @@
 
 - Sigma type: the builder returned by `new SigmaType<TState, TEvents>()`. After configuration, it is also the constructor for instances.
 - Sigma state: an instance created from a configured sigma type.
+- Sigma target: a standalone typed event hub created with `new SigmaTarget<TEvents>()` when you need typed events without managed state.
 - State property: a top-level key from `TState`. Each one becomes a readonly reactive public property and gets its own signal.
 - Computed: an argument-free derived getter declared with `.computed(...)`.
 - Query: a reactive read that accepts arguments, declared with `.queries(...)` or built locally with `query(fn)`.
@@ -51,6 +52,7 @@
 - Own timers, listeners, subscriptions, or nested setup: `.setup(...)`
 - Use a sigma state inside a component: `useSigma(...)`
 - Subscribe to sigma or DOM events in a component: `useListener(...)`
+- Create a standalone typed event hub with no managed state: `new SigmaTarget<TEvents>()`, `hub.emit(...)`, and `hub.on(...)`
 - Subscribe outside components: `.on(...)` or `listen(...)`
 - Read or restore committed top-level state: `snapshot(...)` and `replaceState(...)`
 

package/examples/sigma-target.ts

@@ -0,0 +1,26 @@
+import { listen, SigmaTarget } from "preact-sigma";
+
+const notifications = new SigmaTarget<{
+  saved: {
+    id: string;
+    title: string;
+  };
+  reset: void;
+}>();
+
+const stopSaved = notifications.on("saved", ({ id, title }) => {
+  console.log(`Saved ${id}: ${title}`);
+});
+
+const stopReset = listen(notifications, "reset", () => {
+  console.log("Reset");
+});
+
+notifications.emit("saved", {
+  id: "note-1",
+  title: "Draft post",
+});
+notifications.emit("reset");
+
+stopSaved();
+stopReset();

package/package.json

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