preact-sigma 5.0.0 → 6.0.1

package/dist/persist.mjs

@@ -1,4 +1,4 @@
-import { c as sigma } from "./runtime-nX4Aygb8.mjs";
+import { o as sigma, s as isPlainObject } from "./sigma-DTMODzf8.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {
@@ -11,12 +11,31 @@ function createIdentityCodec() {
 		}
 	};
 }
+function createPickCodec(keys) {
+	return {
+		version: 1,
+		encode(state) {
+			const stored = {};
+			for (const key of keys) stored[key] = state[key];
+			return stored;
+		},
+		decode(stored, context) {
+			if (!isPlainObject(stored)) throw new Error("[preact-sigma/persist] pick requires a plain object payload");
+			const partialStored = stored;
+			const restored = { ...context.baseState };
+			for (const key of keys) if (key in partialStored) restored[key] = partialStored[key];
+			return restored;
+		}
+	};
+}
 function getCodec(options) {
-	return options.codec ?? createIdentityCodec();
+	if (options.codec) return options.codec;
+	if (options.pick) return createPickCodec(options.pick);
+	return createIdentityCodec();
 }
 function applyRecord(instance, key, record, codec) {
 	if (!record) return { status: "missing" };
-	const baseState = sigma.getState(instance);
+	const baseState = sigma.captureState(instance);
 	const nextState = codec.decode(record.value, {
 		baseState,
 		key,
@@ -29,46 +48,21 @@ function applyRecord(instance, key, record, codec) {
 		storedVersion: record.version
 	};
 }
-function isPlainObject(value) {
-	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-	const prototype = Object.getPrototypeOf(value);
-	return prototype === Object.prototype || prototype === null;
-}
-/** Restores committed state from a persisted record through an async store. */
-async function restoreState(instance, options) {
+async function restore(instance, options) {
 	const codec = getCodec(options);
-	const record = await options.store.read(options.key);
+	const record = await options.store.get(options.key);
 	return applyRecord(instance, options.key, record, codec);
 }
-/** Restores committed state from a persisted record through a sync store. */
-function restoreStateSync(instance, options) {
+function restoreSync(instance, options) {
 	const codec = getCodec(options);
-	const record = options.store.read(options.key);
+	const record = options.store.get(options.key);
 	return applyRecord(instance, options.key, record, codec);
 }
-/** Creates a codec that persists selected top-level state keys and reconstructs a full snapshot on decode. */
-function pickStateCodec(keys) {
-	return {
-		version: 1,
-		encode(state) {
-			const stored = {};
-			for (const key of keys) stored[key] = state[key];
-			return stored;
-		},
-		decode(stored, context) {
-			if (!isPlainObject(stored)) throw new Error("[preact-sigma/persist] pickStateCodec() requires a plain object payload");
-			const partialStored = stored;
-			const restored = { ...context.baseState };
-			for (const key of keys) if (key in partialStored) restored[key] = partialStored[key];
-			return restored;
-		}
-	};
-}
-/** Persists future committed state changes for one sigma-state instance. */
-function persistState(instance, options) {
+function persist(instance, options) {
 	const codec = getCodec(options);
 	const schedule = options.schedule ?? "microtask";
 	const key = options.key;
+	const store = options.store;
 	let stopped = false;
 	let suspended = false;
 	let hasPendingState = false;
@@ -124,7 +118,7 @@ function persistState(instance, options) {
 		}, schedule.debounceMs);
 	};
 	const queueStateWrite = () => {
-		pendingState = sigma.getState(instance);
+		pendingState = sigma.captureState(instance);
 		hasPendingState = true;
 		scheduleWrite();
 	};
@@ -135,7 +129,7 @@ function persistState(instance, options) {
 			while (hasPendingState && !stopped && !suspended) {
 				const state = pendingState;
 				hasPendingState = false;
-				await options.store.write(key, createRecord(state));
+				await store.set(key, createRecord(state));
 			}
 		})();
 		try {
@@ -163,7 +157,7 @@ function persistState(instance, options) {
 			pendingState = void 0;
 			try {
 				await runningWrite;
-				await options.store.remove(key);
+				await store.delete(key);
 			} finally {
 				suspended = false;
 				if (hasPendingState && !stopped) scheduleWrite();
@@ -184,13 +178,12 @@ function persistState(instance, options) {
 		}
 	};
 }
-/** Restores state, then begins persisting future committed changes. */
-function bindPersistence(instance, options) {
+function hydrate(instance, options) {
 	let stopped = false;
 	let handle;
 	const restored = (async () => {
-		const result = await restoreState(instance, options);
-		if (!stopped) handle = persistState(instance, options);
+		const result = await restore(instance, options);
+		if (!stopped) handle = persist(instance, options);
 		return result;
 	})();
 	return {
@@ -203,14 +196,14 @@ function bindPersistence(instance, options) {
 			try {
 				await restored;
 			} catch {
-				await options.store.remove(options.key);
+				await options.store.delete(options.key);
 				return;
 			}
 			if (handle) {
 				await handle.clear();
 				return;
 			}
-			await options.store.remove(options.key);
+			await options.store.delete(options.key);
 		},
 		async stop() {
 			if (stopped) {
@@ -227,10 +220,9 @@ function bindPersistence(instance, options) {
 		}
 	};
 }
-/** Restores state synchronously, then begins persisting future committed changes. */
-function bindPersistenceSync(instance, options) {
-	const restored = restoreStateSync(instance, options);
-	const handle = persistState(instance, options);
+function hydrateSync(instance, options) {
+	const restored = restoreSync(instance, options);
+	const handle = persist(instance, options);
 	return {
 		restored,
 		clear() {
@@ -245,4 +237,4 @@ function bindPersistenceSync(instance, options) {
 	};
 }
 //#endregion
-export { bindPersistence, bindPersistenceSync, persistState, pickStateCodec, restoreState, restoreStateSync };
+export { hydrate, hydrateSync, persist, restore, restoreSync };

package/dist/sigma-D1V3m1xk.d.mts

@@ -0,0 +1,163 @@
+import { ReadonlySignal } from "@preact/signals";
+import { Patch } from "immer";
+
+//#region src/internal/utils.d.ts
+type AnyFunction = (...args: any[]) => any;
+type Cleanup = () => void;
+type AnyResource = Cleanup | {
+  dispose(): void;
+} | {
+  [Symbol.dispose](): void;
+};
+//#endregion
+//#region src/internal/listener.d.ts
+/** 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;
+}
+/** 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];
+//#endregion
+//#region src/internal/symbols.d.ts
+declare const instanceSymbol: unique symbol;
+declare const listenersSymbol: unique symbol;
+declare const refSymbol: unique symbol;
+declare const snapshotSymbol: unique symbol;
+declare const typeSymbol: unique symbol;
+//#endregion
+//#region src/immer.d.ts
+type PrimitiveType = number | string | boolean;
+/** Object types that should never be mapped */
+type AtomicObject = AbortController | Date | EventTarget | Function | Promise<any> | RegExp | Sigma<any>;
+/**
+ * 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 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 : keyof SigmaRef extends keyof T ? 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 : keyof SigmaRef extends keyof T ? 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/sigma.d.ts
+/**
+ * Configures Immer auto-freezing for values published through sigma state.
+ *
+ * Auto-freezing is enabled by default, so draftable public values are deeply frozen after publish.
+ */
+declare function setAutoFreeze(autoFreeze: boolean): void;
+/** Marks object values that should keep their reference-like type in `Draft` and `Immutable` mappings. */
+type SigmaRef<T extends object = {}> = T & {
+  [refSymbol]?: true;
+};
+/** Definition shape used by helper types that need both state and event maps. */
+type SigmaDefinition = {
+  state: object;
+  events?: object;
+};
+/** Instance type for a sigma definition with state typing preserved for public helpers. */
+type SigmaState<T extends SigmaDefinition> = Sigma<T["state"]> & {
+  [typeSymbol]: T;
+};
+/**
+ * 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.
+ * 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> {
+  [typeSymbol]: {
+    state: TState;
+    events: unknown;
+  };
+  [snapshotSymbol]: Record<string, unknown> | undefined;
+  protected get [instanceSymbol](): this;
+  constructor(initialState: TState);
+  /** Optional setup hook that owns side effects and returns cleanup resources. */
+  onSetup?(...args: any[]): readonly AnyResource[];
+  /** Runs `onSetup(...)` and returns a cleanup that disposes returned resources in reverse order. */
+  setup(...args: Parameters<Extract<this["onSetup"], AnyFunction>>): () => void;
+  /**
+   * Publishes the current action draft.
+   *
+   * Use this before unpublished changes cross an async, event, or external-action boundary.
+   * A callback runs after publish in an action context.
+   */
+  commit<T = void>(callback?: (this: typeof this) => T): T | undefined;
+  /** Runs a synchronous setup-owned callback with action semantics from an `onSetup(...)` context. */
+  act(fn: (this: typeof this) => void): void;
+}
+/** Casts a sigma instance to its readonly public consumer view. */
+declare function castProtected<T extends Sigma<any>>(instance: T): Protected<T>;
+/**
+ * Sigma state model that can emit typed events.
+ *
+ * `TEvents` maps event names to payload types, and `TState` types reactive state.
+ */
+declare class SigmaTarget<TEvents extends object = {}, TState extends object = {}> extends Sigma<TState> {
+  [typeSymbol]: {
+    state: TState;
+    events: TEvents;
+  };
+  protected [listenersSymbol]: SigmaListenerMap;
+  constructor(state?: TState);
+  /** Emits a typed event from an action 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. */
+declare const sigma: Readonly<{
+  /** Subscribes to committed state publishes or to one signal-backed top-level state key. */subscribe: {
+    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[], inversePatches: Patch[]) => void, options: {
+      patches: true;
+    }): Cleanup;
+    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[] | undefined, inversePatches: Patch[] | undefined) => void, options: {
+      patches: boolean;
+    }): Cleanup;
+    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>) => void): Cleanup;
+    <TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey, listener: (value: Immutable<TState[TKey]>) => void): Cleanup;
+  }; /** Returns the readonly signal backing one top-level state key. */
+  getSignal<TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey): ReadonlySignal<Immutable<TState[TKey]>>; /** Captures the current committed top-level state snapshot. */
+  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. */
+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";
+type BrandProtected<T> = T & {
+  [protectedSymbol]: true;
+};
+/** Readonly public view returned by `castProtected(...)` and `useSigma(...)`. */
+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>;
+//#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 };