@systemfsoftware/xstate-store 0.0.0-stage → 5.0.0-beta.6

package/dist/persist.mjs

@@ -0,0 +1,630 @@
+import { n as assertNoInternalEventTypeCollisions } from "./store-BMZdYhoE.mjs";
+// src/persist.ts
+const PERSIST_INTERNALS = Symbol.for("xstate-store-persist");
+const PERSIST_REVISION = Symbol("xstate-store-persist-revision");
+const PERSIST_REHYDRATE_EVENT_TYPE = "__persist.rehydrate";
+const noopStorage = {
+	getItem: () => null,
+	setItem: () => {},
+	removeItem: () => {}
+};
+function getStorage(options) {
+	return options.storage ?? createJSONStorage(() => localStorage);
+}
+function isEventStrategy(options) {
+	return options.strategy === "event";
+}
+function serializeSnapshotValue(options, value) {
+	return options.serialize ? options.serialize(value) : JSON.stringify(value);
+}
+function deserializeSnapshotValue(options, str) {
+	return options.deserialize ? options.deserialize(str) : JSON.parse(str);
+}
+function serializeEventValue(options, value) {
+	return options.serialize ? options.serialize(value) : JSON.stringify(value);
+}
+function deserializeEventValue(options, str) {
+	return options.deserialize ? options.deserialize(str) : JSON.parse(str);
+}
+function mergeContext(options, persistedContext, currentContext) {
+	return options.merge ? options.merge(persistedContext, currentContext) : {
+		...currentContext,
+		...persistedContext
+	};
+}
+function migrateSnapshotIfNeeded(options, stored) {
+	const currentVersion = options.version ?? 0;
+	if (stored.version !== currentVersion && options.migrate) return options.migrate(stored.context, stored.version);
+	return stored.context;
+}
+function migrateEventsIfNeeded(options, stored) {
+	const currentVersion = options.version ?? 0;
+	if (stored.version !== currentVersion && options.migrate) return options.migrate(stored.events, stored.version);
+	return stored.events;
+}
+function enqueueWrite(internals, write) {
+	const result = internals.pendingWrite ? internals.pendingWrite.then(write, write) : write();
+	if (result instanceof Promise) {
+		const pending = result.finally(() => {
+			if (internals.pendingWrite === pending) internals.pendingWrite = null;
+		});
+		internals.pendingWrite = pending;
+		return pending;
+	}
+}
+function writeSnapshotToStorage(internals, context) {
+	const options = internals.options;
+	const { storage } = internals;
+	const contextToPersist = options.pick ? options.pick(context) : context;
+	const value = {
+		context: contextToPersist,
+		version: options.version ?? 0
+	};
+	return enqueueWrite(internals, () => {
+		try {
+			const serialized = serializeSnapshotValue(options, value);
+			const result = storage.setItem(options.name, serialized);
+			if (result instanceof Promise) return result.then(() => options.onDone?.(contextToPersist)).catch((err) => options.onError?.(err));
+			options.onDone?.(contextToPersist);
+		} catch (err) {
+			options.onError?.(err);
+		}
+	});
+}
+function writeEventsToStorage(internals, events, checkpoint) {
+	const options = internals.options;
+	const { storage } = internals;
+	const value = {
+		events,
+		version: options.version ?? 0
+	};
+	if (checkpoint !== void 0) value.checkpoint = checkpoint;
+	return enqueueWrite(internals, () => {
+		try {
+			const serialized = serializeEventValue(options, value);
+			const result = storage.setItem(options.name, serialized);
+			if (result instanceof Promise) return result.then(() => options.onDone?.(events)).catch((err) => options.onError?.(err));
+			options.onDone?.(events);
+		} catch (err) {
+			options.onError?.(err);
+		}
+	});
+}
+function createInternals(options) {
+	const internals = {
+		options,
+		storage: getStorage(options),
+		pendingContext: null,
+		pendingEvents: null,
+		pendingCheckpoint: null,
+		flushTimeoutId: null,
+		pendingWrite: null,
+		lastScheduledRevision: 0,
+		flush: () => {
+			if (internals.flushTimeoutId !== null) {
+				clearTimeout(internals.flushTimeoutId);
+				internals.flushTimeoutId = null;
+			}
+			if (isEventStrategy(options)) {
+				if (internals.pendingEvents !== null) {
+					const events = internals.pendingEvents;
+					const checkpoint = internals.pendingCheckpoint;
+					internals.pendingEvents = null;
+					internals.pendingCheckpoint = null;
+					return writeEventsToStorage(internals, events, checkpoint);
+				}
+			} else if (internals.pendingContext !== null) {
+				const context = internals.pendingContext;
+				internals.pendingContext = null;
+				return writeSnapshotToStorage(internals, context);
+			}
+			return internals.pendingWrite ?? void 0;
+		}
+	};
+	return internals;
+}
+function persistSnapshotFromLogic(logic, options) {
+	assertNoInternalEventTypeCollisions(logic.eventTypes, [PERSIST_REHYDRATE_EVENT_TYPE], "persist");
+	const internals = createInternals(options);
+	const { storage } = internals;
+	const throttleMs = options.throttle ?? 0;
+	return {
+		...logic,
+		eventTypes: logic.eventTypes,
+		getInitialSnapshot: () => {
+			const baseSnapshot = logic.getInitialSnapshot();
+			if (options.skipHydration) return {
+				...baseSnapshot,
+				_persist: { hydrated: false },
+				[PERSIST_INTERNALS]: internals
+			};
+			try {
+				const storedValue = storage.getItem(options.name);
+				if (storedValue instanceof Promise) {
+					storedValue.catch((error) => options.onError?.(error));
+					return {
+						...baseSnapshot,
+						_persist: { hydrated: false },
+						[PERSIST_INTERNALS]: internals
+					};
+				}
+				if (storedValue === null) return {
+					...baseSnapshot,
+					_persist: { hydrated: true },
+					[PERSIST_INTERNALS]: internals
+				};
+				const mergedContext = mergeContext(options, migrateSnapshotIfNeeded(options, deserializeSnapshotValue(options, storedValue)), baseSnapshot.context);
+				return {
+					...baseSnapshot,
+					context: mergedContext,
+					_persist: { hydrated: true },
+					[PERSIST_INTERNALS]: internals
+				};
+			} catch (err) {
+				options.onError?.(err);
+				return {
+					...baseSnapshot,
+					_persist: { hydrated: true },
+					[PERSIST_INTERNALS]: internals
+				};
+			}
+		},
+		transition: (snapshot, event) => {
+			if (event.type === PERSIST_REHYDRATE_EVENT_TYPE) {
+				const rawState = event.state;
+				if (!rawState) return [{
+					...snapshot,
+					_persist: {
+						...snapshot._persist,
+						hydrated: true
+					}
+				}, []];
+				try {
+					const mergedContext = mergeContext(options, migrateSnapshotIfNeeded(options, deserializeSnapshotValue(options, rawState)), snapshot.context);
+					return [{
+						...snapshot,
+						context: mergedContext,
+						_persist: {
+							...snapshot._persist,
+							hydrated: true
+						}
+					}, []];
+				} catch (err) {
+					options.onError?.(err);
+					return [{
+						...snapshot,
+						_persist: {
+							...snapshot._persist,
+							hydrated: true
+						}
+					}, []];
+				}
+			}
+			const [nextSnapshot, effects] = logic.transition(snapshot, event);
+			const revision = (snapshot[PERSIST_REVISION] ?? 0) + 1;
+			const snapshotWithMeta = {
+				...nextSnapshot,
+				[PERSIST_REVISION]: revision,
+				_persist: snapshot._persist ?? { hydrated: false },
+				[PERSIST_INTERNALS]: internals
+			};
+			if (!snapshotWithMeta._persist?.hydrated) return [snapshotWithMeta, effects];
+			if (options.filter && !options.filter(event)) return [snapshotWithMeta, effects];
+			const persistEffect = () => {
+				if (revision <= internals.lastScheduledRevision) return;
+				internals.lastScheduledRevision = revision;
+				if (throttleMs > 0) {
+					internals.pendingContext = nextSnapshot.context;
+					if (internals.flushTimeoutId === null) internals.flushTimeoutId = setTimeout(() => {
+						internals.flush();
+					}, throttleMs);
+				} else writeSnapshotToStorage(internals, nextSnapshot.context);
+			};
+			return [snapshotWithMeta, [persistEffect, ...effects]];
+		}
+	};
+}
+function persistEventFromLogic(logic, options) {
+	assertNoInternalEventTypeCollisions(logic.eventTypes, [PERSIST_REHYDRATE_EVENT_TYPE], "persist");
+	const internals = createInternals(options);
+	const { storage } = internals;
+	const throttleMs = options.throttle ?? 0;
+	const maxEvents = options.maxEvents ?? Infinity;
+	function replayEvents(baseSnapshot, events) {
+		let current = baseSnapshot;
+		for (const ev of events) {
+			const [next] = logic.transition(current, ev);
+			current = next;
+		}
+		return current;
+	}
+	return {
+		...logic,
+		eventTypes: logic.eventTypes,
+		getInitialSnapshot: () => {
+			const baseSnapshot = logic.getInitialSnapshot();
+			if (options.skipHydration) return {
+				...baseSnapshot,
+				_persistEvents: [],
+				_persistCheckpoint: null,
+				_persist: { hydrated: false },
+				[PERSIST_INTERNALS]: internals
+			};
+			try {
+				const storedValue = storage.getItem(options.name);
+				if (storedValue instanceof Promise) {
+					storedValue.catch((error) => options.onError?.(error));
+					return {
+						...baseSnapshot,
+						_persistEvents: [],
+						_persistCheckpoint: null,
+						_persist: { hydrated: false },
+						[PERSIST_INTERNALS]: internals
+					};
+				}
+				if (storedValue === null) return {
+					...baseSnapshot,
+					_persistEvents: [],
+					_persistCheckpoint: null,
+					_persist: { hydrated: true },
+					[PERSIST_INTERNALS]: internals
+				};
+				const parsed = deserializeEventValue(options, storedValue);
+				const events = migrateEventsIfNeeded(options, parsed);
+				return {
+					...replayEvents(parsed.checkpoint ? {
+						...baseSnapshot,
+						context: parsed.checkpoint
+					} : baseSnapshot, events),
+					_persistEvents: events,
+					_persistCheckpoint: parsed.checkpoint ?? null,
+					_persist: { hydrated: true },
+					[PERSIST_INTERNALS]: internals
+				};
+			} catch (err) {
+				options.onError?.(err);
+				return {
+					...baseSnapshot,
+					_persistEvents: [],
+					_persistCheckpoint: null,
+					_persist: { hydrated: true },
+					[PERSIST_INTERNALS]: internals
+				};
+			}
+		},
+		transition: (snapshot, event) => {
+			if (event.type === PERSIST_REHYDRATE_EVENT_TYPE) {
+				const rawState = event.state;
+				if (!rawState) return [{
+					...snapshot,
+					_persistEvents: snapshot._persistEvents ?? [],
+					_persistCheckpoint: snapshot._persistCheckpoint ?? null,
+					_persist: {
+						...snapshot._persist,
+						hydrated: true
+					}
+				}, []];
+				try {
+					const parsed = deserializeEventValue(options, rawState);
+					const events = migrateEventsIfNeeded(options, parsed);
+					const baseSnapshot = logic.getInitialSnapshot();
+					return [{
+						...replayEvents(parsed.checkpoint ? {
+							...baseSnapshot,
+							context: parsed.checkpoint
+						} : baseSnapshot, events),
+						[PERSIST_REVISION]: snapshot[PERSIST_REVISION],
+						_persistEvents: events,
+						_persistCheckpoint: parsed.checkpoint ?? null,
+						_persist: {
+							...snapshot._persist,
+							hydrated: true
+						},
+						[PERSIST_INTERNALS]: internals
+					}, []];
+				} catch (err) {
+					options.onError?.(err);
+					return [{
+						...snapshot,
+						_persistEvents: snapshot._persistEvents ?? [],
+						_persistCheckpoint: snapshot._persistCheckpoint ?? null,
+						_persist: {
+							...snapshot._persist,
+							hydrated: true
+						}
+					}, []];
+				}
+			}
+			const [nextSnapshot, effects] = logic.transition(snapshot, event);
+			const prevEvents = snapshot._persistEvents ?? [];
+			const prevCheckpoint = snapshot._persistCheckpoint ?? null;
+			const revision = (snapshot[PERSIST_REVISION] ?? 0) + 1;
+			const snapshotWithMeta = {
+				...nextSnapshot,
+				[PERSIST_REVISION]: revision,
+				_persistEvents: prevEvents,
+				_persistCheckpoint: prevCheckpoint,
+				_persist: snapshot._persist ?? { hydrated: false },
+				[PERSIST_INTERNALS]: internals
+			};
+			if (!snapshotWithMeta._persist?.hydrated) return [snapshotWithMeta, effects];
+			let nextEvents = [...prevEvents, event];
+			let nextCheckpoint = prevCheckpoint;
+			if (nextEvents.length > maxEvents) {
+				const droppedEvents = nextEvents.slice(0, -maxEvents);
+				const baseSnapshot = logic.getInitialSnapshot();
+				nextCheckpoint = replayEvents(prevCheckpoint ? {
+					...baseSnapshot,
+					context: prevCheckpoint
+				} : baseSnapshot, droppedEvents).context;
+				nextEvents = nextEvents.slice(-maxEvents);
+			}
+			const snapshotWithEvents = {
+				...snapshotWithMeta,
+				_persistEvents: nextEvents,
+				_persistCheckpoint: nextCheckpoint
+			};
+			const persistEffect = () => {
+				if (revision <= internals.lastScheduledRevision) return;
+				internals.lastScheduledRevision = revision;
+				if (throttleMs > 0) {
+					internals.pendingEvents = nextEvents;
+					internals.pendingCheckpoint = nextCheckpoint;
+					if (internals.flushTimeoutId === null) internals.flushTimeoutId = setTimeout(() => {
+						internals.flush();
+					}, throttleMs);
+				} else writeEventsToStorage(internals, nextEvents, nextCheckpoint);
+			};
+			return [snapshotWithEvents, [persistEffect, ...effects]];
+		}
+	};
+}
+function persistFromLogic(logic, options) {
+	if (isEventStrategy(options)) return persistEventFromLogic(logic, options);
+	return persistSnapshotFromLogic(logic, options);
+}
+/**
+* Creates a store extension that persists context to storage.
+*
+* @example
+*
+* ```ts
+* import { persist } from '@systemfsoftware/xstate-store/persist';
+*
+* const store = createStore({
+*   context: { count: 0 },
+*   on: { inc: (ctx) => ({ count: ctx.count + 1 }) }
+* }).with(persist({ name: 'my-store' }));
+* ```
+*
+* @example
+*
+* ```ts
+* // Throttled writes with callbacks
+* const store = createStore({
+*   context: { count: 0 },
+*   on: { inc: (ctx) => ({ count: ctx.count + 1 }) }
+* }).with(
+*   persist({
+*     name: 'my-store',
+*     throttle: 1000,
+*     onDone: (ctx) => console.log('Persisted:', ctx),
+*     onError: (err) => console.error('Persist failed:', err)
+*   })
+* );
+* ```
+*
+* @example
+*
+* ```ts
+* // Async storage with manual rehydration
+* import {
+*   persist,
+*   rehydrateStore,
+*   createJSONStorage
+* } from '@systemfsoftware/xstate-store/persist';
+*
+* const store = createStore({
+*   context: { count: 0 },
+*   on: { inc: (ctx) => ({ count: ctx.count + 1 }) }
+* }).with(
+*   persist({
+*     name: 'my-store',
+*     storage: createJSONStorage(() => AsyncStorage),
+*     skipHydration: true
+*   })
+* );
+*
+* await rehydrateStore(store);
+* ```
+*/
+function persist(options) {
+	return (logic) => persistFromLogic(logic, options);
+}
+/**
+* Creates a storage adapter with error handling and SSR safety.
+*
+* @example
+*
+* ```ts
+* import { createJSONStorage } from '@systemfsoftware/xstate-store/persist';
+*
+* // Safe for SSR — returns noop storage if localStorage is unavailable
+* const storage = createJSONStorage(() => localStorage);
+*
+* // Async storage (React Native)
+* const asyncStorage = createJSONStorage(() => AsyncStorage);
+* ```
+*/
+function createJSONStorage(getStorage) {
+	let storage;
+	try {
+		storage = getStorage();
+	} catch {
+		return noopStorage;
+	}
+	return {
+		getItem: (name) => {
+			try {
+				const result = storage?.getItem(name);
+				if (result instanceof Promise) return result.catch(() => null);
+				return result ?? null;
+			} catch {
+				return null;
+			}
+		},
+		setItem: (name, value) => {
+			try {
+				const result = storage?.setItem(name, value);
+				if (result instanceof Promise) return result.catch(() => {});
+				return result;
+			} catch {}
+		},
+		removeItem: (name) => {
+			try {
+				const result = storage?.removeItem(name);
+				if (result instanceof Promise) return result.catch(() => {});
+				return result;
+			} catch {}
+		}
+	};
+}
+/**
+* Removes persisted data from storage for a store that uses the `persist`
+* extension.
+*
+* @example
+*
+* ```ts
+* import { clearStorage } from '@systemfsoftware/xstate-store/persist';
+*
+* clearStorage(store);
+* ```
+*/
+function clearStorage(store) {
+	const internals = store.getSnapshot()?.[PERSIST_INTERNALS];
+	if (!internals) throw new Error("clearStorage: store does not have a persist extension");
+	if (internals.flushTimeoutId !== null) {
+		clearTimeout(internals.flushTimeoutId);
+		internals.flushTimeoutId = null;
+	}
+	internals.pendingContext = null;
+	internals.pendingEvents = null;
+	internals.pendingCheckpoint = null;
+	return enqueueWrite(internals, () => internals.storage.removeItem(internals.options.name));
+}
+/**
+* Flushes pending throttled updates and waits for already queued async writes.
+* Synchronous storage writes complete before this function returns.
+*
+* @example
+*
+* ```ts
+* import { flushStorage } from '@systemfsoftware/xstate-store/persist';
+*
+* // Force write before page unload
+* window.addEventListener('beforeunload', () => {
+*   flushStorage(store);
+* });
+* ```
+*/
+function flushStorage(store) {
+	const internals = store.getSnapshot()?.[PERSIST_INTERNALS];
+	if (!internals) throw new Error("flushStorage: store does not have a persist extension");
+	return internals.flush();
+}
+/**
+* Returns whether the store has been hydrated from storage.
+*
+* @example
+*
+* ```ts
+* import { isHydrated } from '@systemfsoftware/xstate-store/persist';
+*
+* if (isHydrated(store)) {
+*   // Safe to read persisted state
+* }
+* ```
+*/
+function isHydrated(store) {
+	return store.getSnapshot()?._persist?.hydrated === true;
+}
+/**
+* Reads persisted state from (potentially async) storage and rehydrates the
+* store. Use this for async storage adapters or when `skipHydration` is
+* `true`.
+*
+* @example
+*
+* ```ts
+* import { rehydrateStore } from '@systemfsoftware/xstate-store/persist';
+*
+* const store = createStore({ ... }).with(persist({
+*   name: 'my-store',
+*   storage: createJSONStorage(() => AsyncStorage),
+*   skipHydration: true
+* }));
+*
+* await rehydrateStore(store);
+* ```
+*/
+async function rehydrateStore(store) {
+	const internals = store.getSnapshot()?.[PERSIST_INTERNALS];
+	if (!internals) throw new Error("rehydrateStore: store does not have a persist extension");
+	const data = await internals.storage.getItem(internals.options.name);
+	store.send({
+		type: PERSIST_REHYDRATE_EVENT_TYPE,
+		state: data
+	});
+}
+function assertBroadcastChannelAvailable() {
+	if (typeof BroadcastChannel === "undefined") throw new Error("createBroadcastStorage: BroadcastChannel is not available in this environment");
+}
+/**
+* Wraps a storage adapter so writes are announced across same-origin tabs.
+*
+* Pair with `subscribeToBroadcastStorage(...)` on persisted stores that should
+* rehydrate when another tab writes to the same storage key.
+*/
+function createBroadcastStorage(baseStorage, options) {
+	assertBroadcastChannelAvailable();
+	const channel = new BroadcastChannel(options?.channel ?? "xstate-store");
+	return {
+		channel,
+		getItem: (name) => baseStorage.getItem(name),
+		setItem: (name, value) => {
+			const result = baseStorage.setItem(name, value);
+			const broadcast = () => {
+				channel.postMessage({
+					type: "xstate-store-update",
+					name
+				});
+			};
+			if (result instanceof Promise) return result.then(broadcast);
+			broadcast();
+			return result;
+		},
+		removeItem: (name) => baseStorage.removeItem(name)
+	};
+}
+/**
+* Subscribes a persisted store to broadcast storage updates.
+*
+* Returns an unsubscribe function that closes the broadcast listener.
+*/
+function subscribeToBroadcastStorage(store) {
+	const internals = store.getSnapshot()?.[PERSIST_INTERNALS];
+	if (!internals) throw new Error("subscribeToBroadcastStorage: store does not have a persist extension");
+	const channel = internals.storage.channel;
+	if (typeof BroadcastChannel === "undefined" || !(channel instanceof BroadcastChannel)) throw new Error("subscribeToBroadcastStorage: store storage must be wrapped with createBroadcastStorage()");
+	const storeName = internals.options.name;
+	const handler = (event) => {
+		const data = event.data;
+		if (data && data.type === "xstate-store-update" && data.name === storeName) rehydrateStore(store);
+	};
+	channel.addEventListener("message", handler);
+	return () => {
+		channel.removeEventListener("message", handler);
+	};
+}
+export { clearStorage, createBroadcastStorage, createJSONStorage, flushStorage, isHydrated, persist, rehydrateStore, subscribeToBroadcastStorage };

package/dist/reset.d.ts

@@ -0,0 +1,51 @@
+import { B as StoreContext, U as StoreExtension, _ as EventObject, v as EventPayloadMap } from "./types-0n0RpfhK.js";
+interface ResetOptions<TContext extends StoreContext> {
+  /**
+   * Custom reset function. Receives the initial context and the current
+   * context, returns the context to reset to.
+   *
+   * Defaults to returning the initial context (full reset).
+   */
+  to?: (initialContext: TContext, currentContext: TContext) => TContext;
+}
+/**
+ * Creates a store extension that adds a `reset` trigger to reset the store
+ * context to its initial state.
+ *
+ * @example
+ *
+ * ```ts
+ * import { reset } from '@systemfsoftware/xstate-store/reset';
+ *
+ * const store = createStore({
+ *   context: { count: 0 },
+ *   on: { inc: (ctx) => ({ count: ctx.count + 1 }) }
+ * }).with(reset());
+ *
+ * store.trigger.inc();
+ * store.trigger.reset(); // count = 0
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * // Partial reset: keep some fields
+ * const store = createStore({
+ *   context: { count: 0, user: null as string | null },
+ *   on: {
+ *     inc: (ctx) => ({ ...ctx, count: ctx.count + 1 }),
+ *     login: (ctx, e: { user: string }) => ({ ...ctx, user: e.user })
+ *   }
+ * }).with(
+ *   reset({
+ *     to: (initial, current) => ({ ...initial, user: current.user })
+ *   })
+ * );
+ *
+ * store.trigger.reset(); // resets count, keeps user
+ * ```
+ */
+export declare function reset<TContext extends StoreContext, TEventPayloadMap extends EventPayloadMap, TEmitted extends EventObject>(options?: ResetOptions<TContext>): StoreExtension<TContext, TEventPayloadMap, {
+  reset: null;
+}, TEmitted>;
+export {};