preact-sigma 4.0.0 → 6.0.0

package/dist/persist.d.mts

@@ -0,0 +1,126 @@
+import { f as Immutable, n as Sigma } from "./sigma-DD7HfTvw.mjs";
+
+//#region src/persist.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/** Decode-time context passed to persistence codecs. */
+interface PersistDecodeContext<TState extends object> {
+  /** Storage key used to read the record being decoded. */
+  key: string;
+  /** Version number stored with the record being decoded. */
+  storedVersion: number;
+  /** Current committed snapshot before the decoded value is applied. */
+  baseState: Immutable<TState>;
+}
+/** Context passed to background write error handlers. */
+interface PersistErrorContext<TState extends object> {
+  /** Sigma instance whose state was being persisted. */
+  instance: Sigma<TState>;
+  /** Storage key used for the failed write. */
+  key: string;
+}
+/** A stored persistence record with version and save-time metadata. */
+interface PersistRecord<TStored = unknown> {
+  version: number;
+  savedAt: number;
+  value: TStored;
+}
+/** Key-value storage adapter used by persistence helpers. The method names match Keyv and `Map`. */
+interface PersistStore<TStored = unknown> {
+  get(key: string): MaybePromise<PersistRecord<TStored> | undefined>;
+  set(key: string, record: PersistRecord<TStored>): MaybePromise<unknown>;
+  delete(key: string): MaybePromise<unknown>;
+}
+/** Synchronous storage adapter used by sync restore helpers. */
+interface SyncPersistStore<TStored = unknown> extends PersistStore<TStored> {
+  get(key: string): PersistRecord<TStored> | undefined;
+  set(key: string, record: PersistRecord<TStored>): unknown;
+  delete(key: string): unknown;
+}
+/** Codec that maps between committed sigma snapshots and stored payloads. */
+interface PersistCodec<TState extends object, TStored = Immutable<TState>> {
+  version: number;
+  encode(state: Immutable<TState>): TStored;
+  decode(stored: unknown, context: PersistDecodeContext<TState>): TState;
+}
+/** Scheduling policy for persistence writes. */
+type PersistSchedule = "immediate" | "microtask" | {
+  debounceMs: number;
+};
+interface PersistLifecycleOptions<TState extends object> {
+  /** Storage key used for gets, sets, and deletes. */
+  key: string;
+  /** 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: PersistErrorContext<TState>) => void;
+}
+/** Options shared by restore and persistence helpers. */
+interface PersistOptions<TState extends object, TStored = Immutable<TState>> extends PersistLifecycleOptions<TState> {
+  /** Store adapter that owns persistence I/O for stored records. */
+  store: PersistStore<TStored>;
+  /** Codec that maps committed snapshots to stored payloads. Defaults to an identity codec with version 1. */
+  codec?: PersistCodec<TState, TStored>;
+  pick?: never;
+}
+/** Options that persist selected top-level state keys without a custom codec. */
+interface PickPersistOptions<TState extends object, TKey extends keyof TState = keyof TState> extends PersistLifecycleOptions<TState> {
+  /** Store adapter that owns persistence I/O for the selected top-level keys. */
+  store: PersistStore<Pick<TState, TKey>>;
+  /** Top-level state keys to persist and restore from the current base snapshot. */
+  pick: readonly TKey[];
+  codec?: never;
+}
+/** Options that require a synchronous store. */
+interface SyncPersistOptions<TState extends object, TStored = Immutable<TState>> extends PersistOptions<TState, TStored> {
+  store: SyncPersistStore<TStored>;
+}
+/** Pick-based options that require a synchronous store. */
+interface SyncPickPersistOptions<TState extends object, TKey extends keyof TState = keyof TState> extends PickPersistOptions<TState, TKey> {
+  store: SyncPersistStore<Pick<TState, TKey>>;
+}
+/** 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 handle. */
+interface HydrationHandle extends PersistenceHandle {
+  /** Resolves when restore finishes and reports whether a record was applied. */
+  readonly restored: Promise<RestoreResult>;
+}
+/** Sync restore-plus-persist handle. */
+interface SyncHydrationHandle 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 restore<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): Promise<RestoreResult>;
+declare function restore<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): Promise<RestoreResult>;
+/** Restores committed state from a persisted record through a sync store. */
+declare function restoreSync<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: SyncPickPersistOptions<TState, TKey>): RestoreResult;
+declare function restoreSync<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: SyncPersistOptions<TState, TStored>): RestoreResult;
+/** Persists future committed state changes for one sigma instance. */
+declare function persist<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): PersistenceHandle;
+declare function persist<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): PersistenceHandle;
+/** Restores state, then begins persisting future committed changes. */
+declare function hydrate<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: PickPersistOptions<TState, TKey>): HydrationHandle;
+declare function hydrate<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: PersistOptions<TState, TStored>): HydrationHandle;
+/** Restores state synchronously, then begins persisting future committed changes. */
+declare function hydrateSync<TState extends object, TKey extends keyof TState>(instance: Sigma<TState>, options: SyncPickPersistOptions<TState, TKey>): SyncHydrationHandle;
+declare function hydrateSync<TState extends object, TStored = Immutable<TState>>(instance: Sigma<TState>, options: SyncPersistOptions<TState, TStored>): SyncHydrationHandle;
+//#endregion
+export { HydrationHandle, PersistCodec, PersistDecodeContext, PersistErrorContext, PersistOptions, PersistRecord, PersistSchedule, PersistStore, PersistenceHandle, PickPersistOptions, RestoreResult, SyncHydrationHandle, SyncPersistOptions, SyncPersistStore, SyncPickPersistOptions, hydrate, hydrateSync, persist, restore, restoreSync };

package/dist/persist.mjs

@@ -0,0 +1,240 @@
+import { o as sigma, s as isPlainObject } from "./sigma-CJibGQ6g.mjs";
+//#region src/persist.ts
+function createIdentityCodec() {
+	return {
+		version: 1,
+		encode(state) {
+			return state;
+		},
+		decode(stored) {
+			return stored;
+		}
+	};
+}
+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) {
+	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.captureState(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
+	};
+}
+async function restore(instance, options) {
+	const codec = getCodec(options);
+	const record = await options.store.get(options.key);
+	return applyRecord(instance, options.key, record, codec);
+}
+function restoreSync(instance, options) {
+	const codec = getCodec(options);
+	const record = options.store.get(options.key);
+	return applyRecord(instance, options.key, record, codec);
+}
+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;
+	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.captureState(instance);
+		hasPendingState = true;
+		scheduleWrite();
+	};
+	async function drainPendingWrites() {
+		if (runningWrite) return runningWrite;
+		cancelScheduledWrite();
+		runningWrite = (async () => {
+			while (hasPendingState && !stopped && !suspended) {
+				const state = pendingState;
+				hasPendingState = false;
+				await store.set(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 store.delete(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;
+		}
+	};
+}
+function hydrate(instance, options) {
+	let stopped = false;
+	let handle;
+	const restored = (async () => {
+		const result = await restore(instance, options);
+		if (!stopped) handle = persist(instance, options);
+		return result;
+	})();
+	return {
+		restored,
+		async flush() {
+			await restored;
+			await handle?.flush();
+		},
+		async clear() {
+			try {
+				await restored;
+			} catch {
+				await options.store.delete(options.key);
+				return;
+			}
+			if (handle) {
+				await handle.clear();
+				return;
+			}
+			await options.store.delete(options.key);
+		},
+		async stop() {
+			if (stopped) {
+				await handle?.stop();
+				return;
+			}
+			stopped = true;
+			try {
+				await restored;
+			} catch {
+				return;
+			}
+			await handle?.stop();
+		}
+	};
+}
+function hydrateSync(instance, options) {
+	const restored = restoreSync(instance, options);
+	const handle = persist(instance, options);
+	return {
+		restored,
+		clear() {
+			return handle.clear();
+		},
+		flush() {
+			return handle.flush();
+		},
+		stop() {
+			return handle.stop();
+		}
+	};
+}
+//#endregion
+export { hydrate, hydrateSync, persist, restore, restoreSync };