preact-sigma 5.0.0 → 6.0.0

package/examples/sigma-target.ts

@@ -1,12 +1,24 @@
 import { listen, SigmaTarget } from "preact-sigma";
 
-const notifications = new SigmaTarget<{
+type NotificationEvents = {
   saved: {
     id: string;
     title: string;
   };
   reset: void;
-}>();
+};
+
+class Notifications extends SigmaTarget<NotificationEvents> {
+  saved(id: string, title: string) {
+    this.emit("saved", { id, title });
+  }
+
+  reset() {
+    this.emit("reset");
+  }
+}
+
+const notifications = new Notifications();
 
 const stopSaved = listen(notifications, "saved", ({ id, title }) => {
   console.log(`Saved ${id}: ${title}`);
@@ -16,11 +28,8 @@ const stopReset = listen(notifications, "reset", () => {
   console.log("Reset");
 });
 
-notifications.emit("saved", {
-  id: "note-1",
-  title: "Draft post",
-});
-notifications.emit("reset");
+notifications.saved("note-1", "Draft post");
+notifications.reset();
 
 stopSaved();
 stopReset();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",
@@ -24,14 +24,6 @@
       "import": "./dist/persist.mjs"
     }
   },
-  "scripts": {
-    "build": "tsdown",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
-    "fmt": "oxfmt",
-    "lint": "oxlint",
-    "prepublishOnly": "pnpm build"
-  },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.5",
     "@types/node": "^25.5.0",
@@ -49,5 +41,12 @@
     "@preact/signals": ">=2",
     "immer": ">=11",
     "preact": ">=10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
+    "fmt": "oxfmt",
+    "lint": "oxlint"
   }
-}
+}

package/dist/framework-GgPzRfff.d.mts

@@ -1,331 +0,0 @@
-import { ReadonlySignal, action, effect } from "@preact/signals";
-import { Patch, immerable } from "immer";
-
-//#region src/internal/symbols.d.ts
-declare const signalPrefix = "#";
-declare const sigmaTypeBrand: unique symbol;
-declare const sigmaStateBrand: unique symbol;
-declare const sigmaTargetBrand: unique symbol;
-declare const sigmaEventsBrand: unique symbol;
-declare const sigmaRefBrand: unique symbol;
-declare const reservedKeys: Set<string>;
-//#endregion
-//#region src/immer.d.ts
-type PrimitiveType = number | string | boolean;
-/** Object types that should never be mapped */
-type AtomicObject = Function | Promise<any> | Date | RegExp | EventTarget | AnySigmaState | {
-  [sigmaTargetBrand]: unknown;
-};
-/**
- * If the lib "ES2015.Collection" is not included in tsconfig.json,
- * types like ReadonlyArray, WeakMap etc. fall back to `any` (specified nowhere)
- * or `{}` (from the node types), in both cases entering an infinite recursion in
- * pattern matching type mappings
- * This type can be used to cast these types to `void` in these cases.
- */
-type IfAvailable<T, Fallback = void> = true | false extends (T extends never ? true : false) ? Fallback : keyof T extends never ? Fallback : T;
-/**
- * These should also never be mapped but must be tested after regular Map and
- * Set
- */
-type WeakReferences = IfAvailable<WeakMap<any, any>> | IfAvailable<WeakSet<any>>;
-type HasSigmaRefBrand<T> = [T] extends [object] ? typeof sigmaRefBrand extends keyof T ? true : false : false;
-type WritableDraft<T> = T extends any[] ? number extends T["length"] ? Draft<T[number]>[] : WritableNonArrayDraft<T> : WritableNonArrayDraft<T>;
-type WritableNonArrayDraft<T> = { -readonly [K in keyof T]: T[K] extends infer V ? (V extends object ? Draft<V> : V) : never };
-/**
- * Convert a readonly type into a mutable type, if possible.
- *
- * Use this instead of `immer.Draft`
- */
-type Draft<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : HasSigmaRefBrand<T> extends true ? T : T extends ReadonlyMap<infer K, infer V> ? Map<Draft<K>, Draft<V>> : T extends ReadonlySet<infer V> ? Set<Draft<V>> : T extends WeakReferences ? T : T extends object ? WritableDraft<T> : T;
-/**
- * Convert a mutable type into a readonly type.
- *
- * Use this instead of `immer.Immutable`
- */
-type Immutable<T> = T extends PrimitiveType ? T : T extends AtomicObject ? T : HasSigmaRefBrand<T> extends true ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<Immutable<K>, Immutable<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<Immutable<V>> : T extends WeakReferences ? T : T extends object ? { readonly [K in keyof T]: Immutable<T[K]> } : T;
-//#endregion
-//#region src/listener.d.ts
-/** Structural event-target shape used by `listen(...)` for sigma targets and sigma states. */
-type SigmaTargetLike = {
-  readonly [sigmaTargetBrand]: SigmaListenerMap;
-};
-/** Target types supported by `listen(...)` and `useListener(...)`. */
-type Listenable = SigmaTargetLike | EventTarget;
-/** Untyped listener shape stored internally by `SigmaListenerMap`. */
-type RawSigmaListener = (detail: unknown) => void;
-/** Listener registry used by sigma targets and sigma states for typed event delivery. */
-declare class SigmaListenerMap extends Map<string, Set<RawSigmaListener>> {
-  /** Delivers one event payload to the current listeners for `name`. */
-  emit(name: string, detail: unknown): void;
-  /** Adds one listener for `name`, creating the listener set on first use. */
-  addListener(name: string, listener: RawSigmaListener): void;
-  /** Removes one listener for `name` and prunes the empty listener set. */
-  removeListener(name: string, listener: RawSigmaListener): void;
-}
-type InferEventMap<TTarget extends Listenable> = 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 : TTarget extends EventTarget ? Record<string, Event> : never;
-type InferListenerArgs<TEvents extends object, TTarget extends Listenable, TEvent extends string> = [(TEvent extends keyof TEvents ? TEvents[TEvent] : never) extends infer TPayload ? TTarget extends SigmaTargetLike ? [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 targets receive payloads directly, while DOM targets receive typed events. */
-type InferListener<TTarget extends Listenable, 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 Listenable> = (InferListener<TTarget> extends {
-  __eventType?: infer TEvent;
-} ? string & TEvent : never) | (string & {});
-/** Infers the detail parameter for a typed emit. */
-type EventParameters<T> = [void] extends [T] ? [detail?: T extends void ? undefined : T] : [undefined] extends [T] ? [detail?: T] : [detail: T];
-/**
- * A standalone typed event hub with `emit(...)` and `on(...)` methods.
- *
- * `SigmaTarget` also works with `listen(...)` and `useListener(...)`.
- */
-declare class SigmaTarget<TEvents extends AnyEvents = {}> {
-  readonly [sigmaEventsBrand]: TEvents;
-  readonly [sigmaTargetBrand]: SigmaListenerMap;
-  /**
-   * Emits a typed event from the hub.
-   *
-   * Void events notify listeners with `undefined`. Payload events pass their
-   * payload directly to listeners.
-   */
-  emit<TEvent extends string & keyof TEvents>(name: TEvent, ...[detail]: EventParameters<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 target or DOM target and returns a cleanup function that removes it. */
-declare function listen<TTarget extends Listenable, TEvent extends InferEventType<TTarget>>(target: TTarget, name: TEvent, listener: InferListener<TTarget, TEvent>): Cleanup;
-//#endregion
-//#region src/internal/types.d.ts
-type Def = typeof sigmaTypeBrand;
-type AnyFunction = (...args: any[]) => any;
-type Cleanup = () => void;
-type DefaultStateInitializer<TValue> = (this: void) => TValue;
-type DefaultStateValue<TValue> = TValue | DefaultStateInitializer<TValue>;
-type Disposable = {
-  [Symbol.dispose](): void;
-};
-type DisposableLike = {
-  dispose(): void;
-};
-interface SigmaRefBrand {
-  [sigmaRefBrand]?: true;
-}
-/** A type brand that keeps a value by reference in sigma's `Draft` and `Immutable` helpers. */
-type SigmaRef<T = unknown> = T & SigmaRefBrand;
-/** The event map shape used by sigma types. */
-type AnyEvents = Record<string, object | void>;
-/** The top-level state object shape used by sigma types. */
-type AnyState = Record<string, unknown>;
-/** The object accepted by `.defaultState(...)`, where each property may be a value or a zero-argument initializer. */
-type AnyDefaultState<TState extends object> = { [K in keyof TState]?: DefaultStateValue<TState[K]> };
-/** A cleanup resource supported by setup handlers, including function, `dispose()`, and `Symbol.dispose` cleanup. */
-type AnyResource = Cleanup | Disposable | DisposableLike | AbortController;
-type ComputedValues<TComputeds> = { readonly [K in keyof TComputeds]: TComputeds[K] extends AnyFunction ? Immutable<ReturnType<TComputeds[K]>> : never };
-type QueryMethods<TQueries> = { [K in keyof TQueries]: TQueries[K] extends AnyFunction ? (...args: Parameters<TQueries[K]>) => ReturnType<TQueries[K]> : never };
-type ActionMethods<TActions> = { [K in keyof TActions]: TActions[K] extends AnyFunction ? (...args: Parameters<TActions[K]>) => ReturnType<TActions[K]> : never };
-type MergeObjects<TLeft, TRight, TConstraint extends object = object> = TRight extends TConstraint ? TLeft extends TConstraint ? Simplify<Omit<TLeft, keyof TRight> & TRight> : TRight : TLeft extends TConstraint ? TLeft : {};
-type Simplify<T> = {} & { [K in keyof T]: T[K] };
-type ComputedContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<Immutable<MergeObjects<T[Def]["state"], TOverrides["state"]>> & ComputedValues<MergeObjects<T[Def]["computeds"], TOverrides["computeds"]>>>;
-type ReadonlyContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<Immutable<MergeObjects<T[Def]["state"], TOverrides["state"]>> & ComputedValues<MergeObjects<T[Def]["computeds"], TOverrides["computeds"]>> & QueryMethods<MergeObjects<T[Def]["queries"], TOverrides["queries"]>>>;
-type Emit<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = MergeObjects<T[Def]["events"], TOverrides["events"], AnyEvents> extends infer TEvents ? [TEvents] extends [AnyEvents] ? <TEvent extends string & keyof TEvents>(name: TEvent, ...[detail]: EventParameters<TEvents[TEvent]>) => void : never : never;
-type ActionContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<Draft<MergeObjects<T[Def]["state"], TOverrides["state"]>> & ComputedValues<MergeObjects<T[Def]["computeds"], TOverrides["computeds"]>> & QueryMethods<MergeObjects<T[Def]["queries"], TOverrides["queries"]>> & ActionMethods<MergeObjects<T[Def]["actions"], TOverrides["actions"]>> & {
-  /** Publishes the current action draft immediately so later boundaries use committed state. */commit(): void; /** Emits a typed event from the current action. */
-  emit: Emit<T, TOverrides>;
-}>;
-type SetupContext<T extends AnySigmaType, TOverrides extends Partial<SigmaDefinition> = {}> = Simplify<SigmaState<T[Def] & TOverrides> & {
-  /** Runs a synchronous anonymous action from setup so reads and writes use normal action semantics. */act<TResult>(fn: (this: ActionContext<T>) => TResult): TResult; /** Emits a typed event from setup. */
-  emit: Emit<T, TOverrides>;
-}>;
-type AnySigmaType = SigmaType<any, any, any> & {
-  readonly [sigmaTypeBrand]: {
-    state: object;
-    events?: object;
-    computeds?: object;
-    queries?: object;
-    actions?: object;
-    setupArgs?: any[];
-  };
-};
-/** The public shape shared by all sigma-state instances. */
-interface AnySigmaState {
-  readonly [sigmaStateBrand]: true;
-  readonly [sigmaTargetBrand]: SigmaListenerMap;
-}
-/** A sigma-state instance with a typed event map. */
-type AnySigmaStateWithEvents<TEvents extends AnyEvents> = AnySigmaState & {
-  readonly [sigmaEventsBrand]: TEvents;
-};
-/** Options accepted by `sigma.subscribe(instance, handler, options)`. */
-type SigmaSubscribeOptions = {
-  /** Includes Immer patches and inverse patches on the delivered change object. */patches?: boolean;
-};
-/** The change object delivered to `sigma.subscribe(instance, handler)` listeners. */
-type SigmaChange<TState extends AnyState, TWithPatches extends boolean = false> = {
-  readonly newState: Immutable<TState>;
-  readonly oldState: Immutable<TState>;
-} & (TWithPatches extends true ? {
-  readonly inversePatches: readonly Patch[];
-  readonly patches: readonly Patch[];
-} : {});
-type SigmaDefinition = {
-  state: AnyState;
-  events?: AnyEvents;
-  computeds?: object;
-  queries?: object;
-  actions?: object;
-  setupArgs?: any[];
-};
-type SigmaSignals<T extends SigmaDefinition> = Simplify<Immutable<T["state"]> & ComputedValues<T["computeds"]>>;
-type SigmaChangeListener<T extends SigmaDefinition = SigmaDefinition, TWithPatches extends boolean = false> = (change: SigmaChange<T["state"], TWithPatches>) => void;
-type EventMetadata<TEvents extends AnyEvents | undefined> = [undefined] extends [TEvents] ? {} : {
-  readonly [sigmaEventsBrand]: TEvents;
-};
-type SetupMethods<TSetupArgs extends any[] | undefined> = [TSetupArgs] extends [undefined] ? {} : {
-  /** Runs every registered setup handler and returns one cleanup function for the active setup. */setup(...args: Extract<TSetupArgs, any[]>): Cleanup;
-};
-/** The public instance shape produced by a configured sigma type. */
-type SigmaState<T extends SigmaDefinition = SigmaDefinition> = AnySigmaState & Simplify<SigmaSignals<T> & QueryMethods<T["queries"]> & ActionMethods<T["actions"]> & EventMetadata<T["events"]> & SetupMethods<T["setupArgs"]>>;
-type RequiredKeys<TObject extends object> = { [K in keyof TObject]-?: {} extends Pick<TObject, K> ? never : K }[keyof TObject];
-type MissingInitialKeys<TState extends AnyState, TDefaults extends object> = Exclude<RequiredKeys<TState>, keyof TDefaults>;
-type InitialStateInput<TState extends AnyState, TDefaults extends object> = [MissingInitialKeys<TState, TDefaults>] extends [never] ? [initialState?: Partial<TState>] : [initialState: Pick<TState, MissingInitialKeys<TState, TDefaults>> & Partial<TState>];
-type ExtendSigmaType<T extends SigmaType<any, any, any>, TExtension extends Partial<SigmaDefinition>> = T & {
-  readonly [sigmaTypeBrand]: T[Def] & TExtension;
-};
-type OmitEmpty<T extends object> = Omit<T, { [K in keyof T]: [undefined] extends [T[K]] ? K : [{}] extends [T[K]] ? K : never }[keyof T]>;
-type InferSigmaDefinition<T extends SigmaType<any, any, any>> = Extract<Simplify<OmitEmpty<T[Def]>>, SigmaDefinition>;
-/** Infers the `setup(...)` argument list for a sigma-state instance. */
-type InferSetupArgs<T extends AnySigmaState> = T extends {
-  setup(...args: infer TArgs extends any[]): Cleanup;
-} ? TArgs : never;
-//#endregion
-//#region src/internal/runtime.d.ts
-/** Controls whether sigma deep-freezes published public state. Auto-freezing starts enabled and the setting is shared across instances. */
-declare function setAutoFreeze(autoFreeze: boolean): void;
-/**
- * Utility helpers for sigma-state instances.
- *
- * The helpers expose instance-specific built-ins without reserving names on the
- * public instance object.
- */
-declare const sigma: Readonly<{
-  /** Returns the underlying signal for a top-level state property or computed. */getSignal: <T extends SigmaDefinition, K extends Extract<keyof SigmaSignals<T>, string>>(publicInstance: SigmaState<T>, key: K) => ReadonlySignal<SigmaSignals<T>[K]>; /** Returns a shallow snapshot of an instance's committed public state. */
-  getState: <T extends SigmaDefinition>(publicInstance: SigmaState<T>) => Immutable<T["state"]>; /** Replaces an instance's committed public state from a snapshot object. */
-  replaceState: <T extends SigmaDefinition>(publicInstance: SigmaState<T>, nextState: Immutable<T["state"]>) => void; /** Subscribes to committed state changes or one top-level property signal. */
-  subscribe: {
-    <T extends SigmaDefinition, K extends Extract<keyof SigmaSignals<T>, string>>(publicInstance: SigmaState<T>, key: K, listener: (value: SigmaSignals<T>[K]) => void): Cleanup;
-    <T extends SigmaDefinition, TOptions extends SigmaSubscribeOptions | undefined = undefined>(publicInstance: SigmaState<T>, listener: SigmaChangeListener<T, TOptions extends {
-      patches: true;
-    } ? true : false>, listenerOrOptions?: TOptions): Cleanup;
-  };
-}>;
-//#endregion
-//#region src/framework.d.ts
-/** Checks whether a value is an instance created by a configured sigma type. */
-declare function isSigmaState(value: object): value is AnySigmaState;
-/**
- * Creates a standalone tracked query helper with the same signature as `fn`.
- *
- * Each call is reactive at the call site and does not memoize results across
- * invocations, which makes `query(fn)` a good fit for local tracked helpers
- * that do not need to live on the sigma-state instance.
- */
-declare function query<TArgs extends any[], TResult>(fn: (this: void, ...args: TArgs) => TResult): typeof fn;
-/**
- * Builds sigma-state constructors by accumulating default state, computeds,
- * queries, actions, and setup handlers.
- *
- * State and event inference starts from `new SigmaType<TState, TEvents>()`.
- * Later builder methods infer names and types from the objects you pass to them.
- */
-declare class SigmaType<TState extends AnyState, TEvents extends AnyEvents = {}, TDefaults extends AnyDefaultState<TState> = {}> extends Function {
-  readonly [sigmaTypeBrand]: {
-    state: TState;
-    events: TEvents;
-  };
-  constructor(name?: string);
-  /**
-   * Adds top-level public state and default values to the builder.
-   *
-   * Each property becomes a reactive public state property on instances. Use a
-   * zero-argument function when each instance needs a fresh object or array.
-   */
-  defaultState<TDefaults extends AnyDefaultState<TState>>(defaultState: TDefaults): SigmaType<TState, TEvents, TDefaults>;
-  /**
-   * Adds reactive getter properties for derived values that take no arguments.
-   *
-   * Computed names and return types are inferred from the object you pass.
-   * `this` exposes readonly state plus computeds that are already on the builder.
-   */
-  computed<TComputeds extends object>(computeds: TComputeds & ThisType<ComputedContext<this, {
-    computeds: TComputeds;
-  }>>): ExtendSigmaType<this, {
-    computeds: TComputeds;
-  }>;
-  /**
-   * Adds reactive read methods that accept arguments.
-   *
-   * Query names, parameters, and return types are inferred from the object you
-   * pass. Each call tracks reactively at the call site and does not memoize
-   * results across invocations.
-   */
-  queries<TQueries extends object>(queries: TQueries & ThisType<ReadonlyContext<this, {
-    queries: TQueries;
-  }>>): ExtendSigmaType<this, {
-    queries: TQueries;
-  }>;
-  /**
-   * Adds action methods whose `this` receives draft state, typed events, `commit()`,
-   * and the computeds, queries, and actions already defined on the builder.
-   *
-   * Actions create drafts lazily as they need them. Sync actions on the same
-   * instance reuse the current draft, so they can compose and publish once when
-   * the outer action returns. Declared async actions publish their initial
-   * synchronous work on return, then require `this.commit()` to publish later
-   * writes made after `await`. Non-async actions stay synchronous; if one
-   * returns a promise, sigma throws so async boundaries stay explicit.
-   */
-  actions<TActions extends object>(actions: TActions & ThisType<ActionContext<this, {
-    actions: TActions;
-  }>>): ExtendSigmaType<this, {
-    actions: TActions;
-  }>;
-  /**
-   * Adds an explicit setup handler for side effects and owned resources.
-   *
-   * Every registered handler runs when `instance.setup(...)` is called, and the
-   * setup argument list is inferred from the first handler you add.
-   */
-  setup<TSetupArgs extends any[]>(setup: (this: SetupContext<this, {
-    setupArgs: TSetupArgs;
-  }>, ...args: TSetupArgs) => readonly AnyResource[]): ExtendSigmaType<this, {
-    setupArgs: TSetupArgs;
-  }>;
-}
-interface SigmaType<TState extends AnyState, TEvents extends AnyEvents, TDefaults extends AnyDefaultState<TState>> {
-  /**
-   * Type-only access to the configured instance shape.
-   *
-   * This property does not exist at runtime. Its type is inferred from the
-   * generics on `new SigmaType<TState, TEvents>()` plus the later builder inputs.
-   */
-  get Instance(): SigmaState<InferSigmaDefinition<this>>;
-  /**
-   * Creates a sigma-state instance.
-   *
-   * Constructor input shallowly overrides `defaultState(...)`. Required keys are
-   * inferred from whichever state properties still do not have defaults.
-   */
-  new (...args: InitialStateInput<TState, TDefaults>): this["Instance"];
-}
-//#endregion
-export { Immutable as A, InferListener as C, SigmaTarget as D, SigmaListenerMap as E, sigmaTargetBrand as F, sigmaTypeBrand as I, signalPrefix as L, sigmaEventsBrand as M, sigmaRefBrand as N, SigmaTargetLike as O, sigmaStateBrand as P, InferEventType as S, RawSigmaListener as T, SigmaDefinition as _, isSigmaState as a, SigmaSubscribeOptions as b, sigma as c, AnyResource as d, AnySigmaState as f, SigmaChange as g, InferSetupArgs as h, immerable as i, reservedKeys as j, listen as k, AnyDefaultState as l, AnyState as m, action as n, query as o, AnySigmaStateWithEvents as p, effect as r, setAutoFreeze as s, SigmaType as t, AnyEvents as u, SigmaRef as v, Listenable as w, EventParameters as x, SigmaState as y };