preact-sigma 4.0.0 → 6.0.0

package/dist/sigma-CJibGQ6g.mjs

@@ -0,0 +1,383 @@
+import { action, batch, computed, signal } from "@preact/signals";
+import { createDraft as createDraft$1, finishDraft, freeze, isDraft, isDraftable, original, setAutoFreeze as setAutoFreeze$1 } from "immer";
+//#region src/internal/symbols.ts
+const instanceSymbol = Symbol.for("sigma:instance");
+const listenersSymbol = Symbol.for("sigma:listeners");
+const snapshotSymbol = Symbol.for("sigma:snapshot");
+//#endregion
+//#region src/internal/listener.ts
+/** Listener registry used by sigma targets and sigma states for typed event delivery. */
+var SigmaListenerMap = class extends Map {
+	/** Delivers one event payload to the current listeners for `name`. */
+	emit(name, detail) {
+		const listeners = this.get(name);
+		if (!listeners?.size) return;
+		for (const listener of [...listeners]) listener(detail);
+	}
+	/** Adds one listener for `name`, creating the listener set on first use. */
+	addListener(name, listener) {
+		let listeners = this.get(name);
+		if (!listeners) {
+			listeners = /* @__PURE__ */ new Set();
+			this.set(name, listeners);
+		}
+		listeners.add(listener);
+	}
+	/** Removes one listener for `name` and prunes the empty listener set. */
+	removeListener(name, listener) {
+		const listeners = this.get(name);
+		if (!listeners) return;
+		listeners.delete(listener);
+		if (!listeners.size) this.delete(name);
+	}
+};
+//#endregion
+//#region src/internal/utils.ts
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function isPromiseLike(value) {
+	return value != null && typeof value.then === "function";
+}
+//#endregion
+//#region src/sigma.ts
+let autoFreezeEnabled = true;
+/**
+* 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.
+*/
+function setAutoFreeze(autoFreeze) {
+	setAutoFreeze$1(autoFreeze);
+	autoFreezeEnabled = autoFreeze;
+}
+const signalSuffix = "$";
+const changeListenersMap = /* @__PURE__ */ new WeakMap();
+const patchListeners = /* @__PURE__ */ new WeakSet();
+const initializedPrototypes = /* @__PURE__ */ new WeakSet();
+const queries = /* @__PURE__ */ new WeakSet();
+const emptySentinel = {};
+let activeInstance = null;
+let activeDraft;
+let activeDerivedReadDepth = 0;
+function ensureActiveInstance(instance) {
+	if (!activeInstance) {
+		activeInstance = instance;
+		return false;
+	}
+	if (instance !== activeInstance) throw new Error("Draft was not committed before an external action was invoked.");
+	return true;
+}
+function clearActiveInstance() {
+	activeInstance = null;
+	activeDraft = null;
+}
+function isStateKey(instance, key) {
+	return Object.hasOwn(instance, key + signalSuffix);
+}
+function getStateSignal(instance, key) {
+	return instance[key + signalSuffix];
+}
+function createSnapshot(instance) {
+	if (instance[snapshotSymbol]) return instance[snapshotSymbol];
+	const state = {};
+	for (const key in instance) if (isStateKey(instance, key)) state[key] = instance[key];
+	return state;
+}
+function createDraft(instance) {
+	return createDraft$1(createSnapshot(instance));
+}
+function runDerivedRead(callback) {
+	activeDerivedReadDepth += 1;
+	try {
+		return callback();
+	} finally {
+		activeDerivedReadDepth -= 1;
+	}
+}
+function assertActionResult(key, result) {
+	if (isDraft(result)) throw new Error(`[preact-sigma] Action named "${key}" returned an active draft.`);
+}
+function hasPatchListeners(instance) {
+	const listeners = changeListenersMap.get(instance);
+	if (!listeners) return false;
+	for (const sub of listeners) if (patchListeners.has(sub)) return true;
+	return false;
+}
+function publishState(instance, nextState, baseState, patches, inversePatches) {
+	instance[snapshotSymbol] = nextState;
+	batch(() => {
+		const missingKeys = new Set(Object.keys(baseState));
+		for (const key in nextState) {
+			const nextValue = nextState[key];
+			if (autoFreezeEnabled) freeze(nextValue, true);
+			const signal = getStateSignal(instance, key);
+			if (signal) signal.value = nextValue;
+			else defineSignalProperty(instance, key, nextValue);
+			missingKeys.delete(key);
+		}
+		for (const key of missingKeys) {
+			const signal = getStateSignal(instance, key);
+			if (signal) signal.value = void 0;
+		}
+	});
+	changeListenersMap.get(instance)?.forEach((listener) => {
+		listener(nextState, baseState, patches, inversePatches);
+	});
+}
+function createActionContext(instance) {
+	return new Proxy(instance, {
+		get(target, key, receiver) {
+			if (typeof key === "string" && isStateKey(target, key)) {
+				if (activeDraft) {
+					ensureActiveInstance(target);
+					return activeDraft[key];
+				}
+				const { value } = getStateSignal(target, key);
+				if (isDraftable(value)) {
+					activeDraft = createDraft(instance);
+					return activeDraft[key];
+				}
+				return value;
+			}
+			if (key === instanceSymbol) return instance;
+			return Reflect.get(target, key, receiver);
+		},
+		set(target, key, value) {
+			if (typeof key === "string" && isStateKey(target, key)) {
+				ensureActiveInstance(instance);
+				activeDraft ??= createDraft(instance);
+				activeDraft[key] = value;
+				return true;
+			}
+			return Reflect.set(target, key, value);
+		}
+	});
+}
+function getActionInstance(context) {
+	return context[instanceSymbol];
+}
+function ensureDraftCommitted(instance) {
+	if (activeInstance && instance !== activeInstance) throw new Error("Draft was not committed before an external action was invoked.");
+	activeInstance = null;
+	if (!activeDraft) return false;
+	const draft = activeDraft;
+	activeDraft = null;
+	let patches;
+	let inversePatches;
+	let patchListener;
+	if (hasPatchListeners(instance)) patchListener = (nextPatches, nextInversePatches) => {
+		patches = nextPatches;
+		inversePatches = nextInversePatches;
+	};
+	const baseState = original(draft);
+	const nextState = finishDraft(draft, patchListener);
+	const changed = baseState !== nextState;
+	if (changed) publishState(instance, nextState, baseState, patches, inversePatches);
+	return changed;
+}
+function initializePrototype(prototype) {
+	const descriptors = Object.getOwnPropertyDescriptors(prototype);
+	for (const key in descriptors) {
+		if (key === "constructor" || key === "onSetup") continue;
+		const { get, value } = descriptors[key];
+		if (get) descriptors[key].get = function() {
+			const instance = getActionInstance(this);
+			return (instance[key + signalSuffix] ??= computed(() => runDerivedRead(() => get.call(instance)))).value;
+		};
+		else if (typeof value === "function" && !queries.has(value)) {
+			const actionFn = action(value);
+			descriptors[key].value = function(...args) {
+				if (activeDerivedReadDepth) throw new Error("[preact-sigma] Computeds and queries cannot call actions.");
+				const instance = getActionInstance(this);
+				if (ensureActiveInstance(instance)) {
+					const result = value.apply(this, args);
+					assertActionResult(key, result);
+					return result;
+				}
+				let result;
+				try {
+					const actionContext = createActionContext(instance);
+					result = actionFn.apply(actionContext, args);
+					assertActionResult(key, result);
+				} catch (error) {
+					clearActiveInstance();
+					throw error;
+				}
+				const changed = ensureDraftCommitted(instance);
+				if (isPromiseLike(result)) {
+					if (changed) throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before returning a promise.`);
+					const onResolveAsyncAction = (promiseResult) => {
+						if (activeDraft && instance === activeInstance) {
+							if (ensureDraftCommitted(instance)) throw new Error(`[preact-sigma] Action named "${key}" forgot to commit() its draft before its promise resolved.`);
+						}
+						return promiseResult;
+					};
+					return result.then(onResolveAsyncAction);
+				}
+				return result;
+			};
+		}
+	}
+	Object.defineProperties(prototype, descriptors);
+}
+function initializeType(type) {
+	for (let prototype = type.prototype; prototype && prototype !== Sigma.prototype && prototype !== SigmaTarget.prototype; prototype = Object.getPrototypeOf(prototype)) {
+		if (initializedPrototypes.has(prototype)) break;
+		initializePrototype(prototype);
+		initializedPrototypes.add(prototype);
+	}
+}
+function disposeCleanupResource(resource) {
+	if (typeof resource === "function") resource();
+	else if ("dispose" in resource) resource.dispose();
+	else resource[Symbol.dispose]();
+}
+function act(fn) {
+	const instance = getActionInstance(this);
+	if (instance !== this) throw new Error("Cannot act() from inside an action.");
+	ensureActiveInstance(instance);
+	try {
+		const context = createActionContext(instance);
+		if (isPromiseLike(action(fn).call(context))) throw new Error("[preact-sigma] act() callbacks must be synchronous");
+	} catch (error) {
+		clearActiveInstance();
+		throw error;
+	}
+	ensureDraftCommitted(instance);
+}
+function defineSignalProperty(instance, key, value) {
+	Object.defineProperty(instance, key + signalSuffix, { value: signal(value) });
+	if (!Object.hasOwn(instance.constructor.prototype, key)) Object.defineProperty(instance.constructor.prototype, key, {
+		get() {
+			return this[key + signalSuffix].value;
+		},
+		enumerable: true
+	});
+}
+/**
+* Base class for signal-backed state models.
+*
+* `TState` is the source of typing for top-level state keys, subscriptions, signals, and replacement snapshots.
+* Merge a same-named interface with the class when direct property reads should be typed on the instance.
+*/
+var Sigma = class {
+	get [instanceSymbol]() {
+		return this;
+	}
+	constructor(initialState) {
+		initializeType(this.constructor);
+		if (initialState === emptySentinel) return;
+		for (const key in initialState) {
+			const initialValue = initialState[key];
+			if (autoFreezeEnabled) freeze(initialValue, true);
+			defineSignalProperty(this, key, initialValue);
+		}
+	}
+	/** Runs `onSetup(...)` and returns a cleanup that disposes returned resources in reverse order. */
+	setup(...args) {
+		const setupContext = new Proxy(this, { get(target, key, receiver) {
+			if (key === instanceSymbol) return target;
+			if (key === "act") return act.bind(target);
+			return Reflect.get(target, key, receiver);
+		} });
+		const resources = this.onSetup.apply(setupContext, args);
+		return () => {
+			for (let i = resources.length - 1; i >= 0; i--) disposeCleanupResource(resources[i]);
+		};
+	}
+	/**
+	* 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(callback) {
+		const instance = getActionInstance(this);
+		if (instance === this) throw new Error("Cannot commit() from outside an action.");
+		ensureDraftCommitted(instance);
+		if (callback) {
+			const context = new Proxy(instance, { get(target, key, receiver) {
+				if (key === instanceSymbol) return instance;
+				return Reflect.get(target, key, receiver);
+			} });
+			return callback.call(context);
+		}
+	}
+	/** Runs a synchronous setup-owned callback with action semantics from an `onSetup(...)` context. */
+	act(fn) {
+		throw new Error("Cannot act() from outside an onSetup() context.");
+	}
+};
+/** Casts a sigma instance to its readonly public consumer view. */
+function castProtected(instance) {
+	return instance;
+}
+/**
+* Sigma state model that can emit typed events.
+*
+* `TEvents` maps event names to payload types, and `TState` types reactive state.
+*/
+var SigmaTarget = class extends Sigma {
+	[listenersSymbol] = new SigmaListenerMap();
+	constructor(state) {
+		super(state ?? emptySentinel);
+	}
+	/** Emits a typed event from an action after unpublished draft changes are committed. */
+	emit(name, ...[detail]) {
+		const instance = getActionInstance(this);
+		if (instance === this) throw new Error("Cannot emit() from outside an action.");
+		if (instance === activeInstance && activeDraft) throw new Error("Cannot emit() until you commit() your draft.");
+		this[listenersSymbol].emit(name, detail);
+	}
+};
+/** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
+const sigma = /* @__PURE__ */ Object.freeze({
+	subscribe: ((instance, keyOrListener, listenerOrOptions) => {
+		if (typeof keyOrListener === "string") {
+			const signal = getStateSignal(instance, keyOrListener);
+			if (!signal) throw new Error(`[preact-sigma] Property named "${keyOrListener}" is not signal-backed.`);
+			return signal.subscribe(listenerOrOptions);
+		}
+		const listener = keyOrListener;
+		if (listenerOrOptions?.patches) patchListeners.add(listener);
+		let subscriptions = changeListenersMap.get(instance);
+		if (!subscriptions) {
+			subscriptions = /* @__PURE__ */ new Set();
+			changeListenersMap.set(instance, subscriptions);
+		}
+		subscriptions.add(listener);
+		return () => {
+			subscriptions.delete(listener);
+			if (!subscriptions.size) changeListenersMap.delete(instance);
+		};
+	}),
+	getSignal(instance, key) {
+		return getStateSignal(instance, key);
+	},
+	captureState(instance) {
+		return Object.freeze(createSnapshot(instance));
+	},
+	replaceState(target, nextState) {
+		if (!isPlainObject(nextState)) throw new Error("[preact-sigma] replaceState() requires a plain object snapshot");
+		if (activeDraft) throw new Error(`[preact-sigma] replaceState() cannot run while an action has unpublished changes.`);
+		const instance = getActionInstance(target);
+		const baseState = createSnapshot(instance);
+		const patches = hasPatchListeners(instance) ? [] : void 0;
+		publishState(instance, nextState, baseState, patches, patches ? [] : void 0);
+	}
+});
+/** Marks a class method as a committed-state reactive read with arguments instead of an action. */
+function query(method) {
+	queries.add(method);
+	function queryMethod(...args) {
+		const instance = getActionInstance(this);
+		return computed(() => runDerivedRead(() => method.apply(instance, args))).value;
+	}
+	queries.add(queryMethod);
+	return queryMethod;
+}
+//#endregion
+export { setAutoFreeze as a, listenersSymbol as c, query as i, SigmaTarget as n, sigma as o, castProtected as r, isPlainObject as s, Sigma as t };

package/dist/sigma-DD7HfTvw.d.mts

@@ -0,0 +1,162 @@
+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.
+ * 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 };