preact-sigma 5.0.0 → 6.0.0

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-CJibGQ6g.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-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 };