preact-sigma 3.1.0 → 5.0.0

package/dist/persist.d.mts

@@ -0,0 +1,101 @@
+import { A as Immutable, _ as SigmaDefinition, y as SigmaState } from "./framework-GgPzRfff.mjs";
+
+//#region src/persist.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type Snapshot<T extends SigmaDefinition> = Immutable<T["state"]>;
+type CodecContext<TState extends object> = {
+  key: string;
+  storedVersion: number;
+  baseState: Readonly<TState>;
+};
+/** A stored persistence record with version and save-time metadata. */
+interface PersistRecord<TStored = unknown> {
+  version: number;
+  savedAt: number;
+  value: TStored;
+}
+/** Storage adapter used by persistence helpers. */
+interface PersistStore<TRecord> {
+  read(key: string): MaybePromise<TRecord | undefined>;
+  write(key: string, record: TRecord): MaybePromise<void>;
+  remove(key: string): MaybePromise<void>;
+}
+/** Synchronous storage adapter used by sync restore helpers. */
+interface SyncPersistStore<TRecord> extends PersistStore<TRecord> {
+  read(key: string): TRecord | undefined;
+  write(key: string, record: TRecord): void;
+  remove(key: string): void;
+}
+/** Codec that maps between in-memory sigma state and stored payloads. */
+interface PersistCodec<TState extends object, TStored = TState> {
+  version: number;
+  encode(state: Readonly<TState>): TStored;
+  decode(stored: unknown, context: CodecContext<TState>): TState;
+}
+/** Scheduling policy for persistence writes. */
+type PersistSchedule = "immediate" | "microtask" | {
+  debounceMs: number;
+};
+/** Options shared by restore and persistence helpers. */
+interface PersistOptions<T extends SigmaDefinition, TStored = Snapshot<T>> {
+  /** Storage key used for reads, writes, and removals. */
+  key: string;
+  /** Store adapter that owns persistence I/O. */
+  store: PersistStore<PersistRecord<TStored>>;
+  /** Codec that maps committed snapshots to stored payloads. Defaults to an identity codec with version 1. */
+  codec?: PersistCodec<Snapshot<T>, TStored>;
+  /** Scheduling policy for future writes. Defaults to `"microtask"`. */
+  schedule?: PersistSchedule;
+  /** Writes the current committed snapshot once after persistence becomes active. */
+  writeInitial?: boolean;
+  /** Receives background write failures without stopping persistence automatically. */
+  onWriteError?: (error: unknown, context: {
+    instance: SigmaState<T>;
+    key: string;
+  }) => void;
+}
+/** Options that require a synchronous store. */
+interface SyncPersistOptions<T extends SigmaDefinition, TStored = Snapshot<T>> extends PersistOptions<T, TStored> {
+  store: SyncPersistStore<PersistRecord<TStored>>;
+}
+/** Result returned by restore helpers. */
+type RestoreResult = {
+  status: "missing";
+} | {
+  status: "restored";
+  savedAt: number;
+  storedVersion: number;
+};
+/** Handle returned by persistence bindings. */
+interface PersistenceHandle {
+  /** Waits for any scheduled or active write for this binding to finish. */
+  flush(): Promise<void>;
+  /** Removes the stored record and keeps the binding active for later writes. */
+  clear(): Promise<void>;
+  /** Stops future persistence and waits for any active write to settle. */
+  stop(): Promise<void>;
+}
+/** Async restore-plus-persist binding result. */
+interface BoundPersistence extends PersistenceHandle {
+  /** Resolves when restore finishes and reports whether a record was applied. */
+  readonly restored: Promise<RestoreResult>;
+}
+/** Sync restore-plus-persist binding result. */
+interface SyncBoundPersistence extends PersistenceHandle {
+  /** Reports the synchronous restore result that ran before persistence started. */
+  readonly restored: RestoreResult;
+}
+/** Restores committed state from a persisted record through an async store. */
+declare function restoreState<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: PersistOptions<T, TStored>): Promise<RestoreResult>;
+/** Restores committed state from a persisted record through a sync store. */
+declare function restoreStateSync<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: SyncPersistOptions<T, TStored>): RestoreResult;
+/** Creates a codec that persists selected top-level state keys and reconstructs a full snapshot on decode. */
+declare function pickStateCodec<TState extends object, TKey extends keyof TState>(keys: readonly TKey[]): PersistCodec<TState, Pick<TState, TKey>>;
+/** Persists future committed state changes for one sigma-state instance. */
+declare function persistState<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: PersistOptions<T, TStored>): PersistenceHandle;
+/** Restores state, then begins persisting future committed changes. */
+declare function bindPersistence<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: PersistOptions<T, TStored>): BoundPersistence;
+/** Restores state synchronously, then begins persisting future committed changes. */
+declare function bindPersistenceSync<T extends SigmaDefinition, TStored = Snapshot<T>>(instance: SigmaState<T>, options: SyncPersistOptions<T, TStored>): SyncBoundPersistence;
+//#endregion
+export { BoundPersistence, PersistCodec, PersistOptions, PersistRecord, PersistSchedule, PersistStore, PersistenceHandle, RestoreResult, SyncBoundPersistence, SyncPersistOptions, SyncPersistStore, bindPersistence, bindPersistenceSync, persistState, pickStateCodec, restoreState, restoreStateSync };

package/dist/persist.mjs

@@ -0,0 +1,248 @@
+import { c as sigma } from "./runtime-nX4Aygb8.mjs";
+//#region src/persist.ts
+function createIdentityCodec() {
+	return {
+		version: 1,
+		encode(state) {
+			return state;
+		},
+		decode(stored) {
+			return stored;
+		}
+	};
+}
+function getCodec(options) {
+	return options.codec ?? createIdentityCodec();
+}
+function applyRecord(instance, key, record, codec) {
+	if (!record) return { status: "missing" };
+	const baseState = sigma.getState(instance);
+	const nextState = codec.decode(record.value, {
+		baseState,
+		key,
+		storedVersion: record.version
+	});
+	sigma.replaceState(instance, nextState);
+	return {
+		status: "restored",
+		savedAt: record.savedAt,
+		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) {
+	const codec = getCodec(options);
+	const record = await options.store.read(options.key);
+	return applyRecord(instance, options.key, record, codec);
+}
+/** Restores committed state from a persisted record through a sync store. */
+function restoreStateSync(instance, options) {
+	const codec = getCodec(options);
+	const record = options.store.read(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) {
+	const codec = getCodec(options);
+	const schedule = options.schedule ?? "microtask";
+	const key = options.key;
+	let stopped = false;
+	let suspended = false;
+	let hasPendingState = false;
+	let pendingState;
+	let microtaskScheduled = false;
+	let debounceTimer;
+	let runningWrite;
+	let backgroundWrite;
+	const cancelScheduledWrite = () => {
+		microtaskScheduled = false;
+		if (debounceTimer !== void 0) {
+			clearTimeout(debounceTimer);
+			debounceTimer = void 0;
+		}
+	};
+	const createRecord = (state) => ({
+		version: codec.version,
+		savedAt: Date.now(),
+		value: codec.encode(state)
+	});
+	const startBackgroundWrite = () => {
+		if (backgroundWrite) return;
+		backgroundWrite = drainPendingWrites().catch((error) => {
+			options.onWriteError?.(error, {
+				instance,
+				key
+			});
+		}).finally(() => {
+			backgroundWrite = void 0;
+		});
+	};
+	const scheduleWrite = () => {
+		if (stopped || suspended) return;
+		if (schedule === "immediate") {
+			startBackgroundWrite();
+			return;
+		}
+		if (schedule === "microtask") {
+			if (microtaskScheduled) return;
+			microtaskScheduled = true;
+			queueMicrotask(() => {
+				microtaskScheduled = false;
+				if (stopped || suspended) return;
+				startBackgroundWrite();
+			});
+			return;
+		}
+		if (debounceTimer !== void 0) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			debounceTimer = void 0;
+			if (stopped || suspended) return;
+			startBackgroundWrite();
+		}, schedule.debounceMs);
+	};
+	const queueStateWrite = () => {
+		pendingState = sigma.getState(instance);
+		hasPendingState = true;
+		scheduleWrite();
+	};
+	async function drainPendingWrites() {
+		if (runningWrite) return runningWrite;
+		cancelScheduledWrite();
+		runningWrite = (async () => {
+			while (hasPendingState && !stopped && !suspended) {
+				const state = pendingState;
+				hasPendingState = false;
+				await options.store.write(key, createRecord(state));
+			}
+		})();
+		try {
+			await runningWrite;
+		} finally {
+			runningWrite = void 0;
+			if (hasPendingState && !stopped && !suspended) startBackgroundWrite();
+		}
+	}
+	const stopSubscription = sigma.subscribe(instance, queueStateWrite);
+	if (options.writeInitial) queueStateWrite();
+	return {
+		async flush() {
+			cancelScheduledWrite();
+			if (!hasPendingState) {
+				await runningWrite;
+				return;
+			}
+			await drainPendingWrites();
+		},
+		async clear() {
+			suspended = true;
+			cancelScheduledWrite();
+			hasPendingState = false;
+			pendingState = void 0;
+			try {
+				await runningWrite;
+				await options.store.remove(key);
+			} finally {
+				suspended = false;
+				if (hasPendingState && !stopped) scheduleWrite();
+			}
+		},
+		async stop() {
+			if (stopped) {
+				await runningWrite;
+				return;
+			}
+			stopped = true;
+			suspended = true;
+			stopSubscription();
+			cancelScheduledWrite();
+			hasPendingState = false;
+			pendingState = void 0;
+			await runningWrite;
+		}
+	};
+}
+/** Restores state, then begins persisting future committed changes. */
+function bindPersistence(instance, options) {
+	let stopped = false;
+	let handle;
+	const restored = (async () => {
+		const result = await restoreState(instance, options);
+		if (!stopped) handle = persistState(instance, options);
+		return result;
+	})();
+	return {
+		restored,
+		async flush() {
+			await restored;
+			await handle?.flush();
+		},
+		async clear() {
+			try {
+				await restored;
+			} catch {
+				await options.store.remove(options.key);
+				return;
+			}
+			if (handle) {
+				await handle.clear();
+				return;
+			}
+			await options.store.remove(options.key);
+		},
+		async stop() {
+			if (stopped) {
+				await handle?.stop();
+				return;
+			}
+			stopped = true;
+			try {
+				await restored;
+			} catch {
+				return;
+			}
+			await handle?.stop();
+		}
+	};
+}
+/** Restores state synchronously, then begins persisting future committed changes. */
+function bindPersistenceSync(instance, options) {
+	const restored = restoreStateSync(instance, options);
+	const handle = persistState(instance, options);
+	return {
+		restored,
+		clear() {
+			return handle.clear();
+		},
+		flush() {
+			return handle.flush();
+		},
+		stop() {
+			return handle.stop();
+		}
+	};
+}
+//#endregion
+export { bindPersistence, bindPersistenceSync, persistState, pickStateCodec, restoreState, restoreStateSync };