@hvakr/firestate 0.1.3 → 0.1.5

package/dist/index.mjs

@@ -628,11 +628,13 @@ const createCollectionSubscription = (options) => {
 	const getPublicState = () => ({
 		data: getMergedData(),
 		isLoading: state.isLoading,
+		isLoaded: state.isActive && !state.isLoading,
 		isSynced: state.localState === void 0,
 		isActive: state.isActive,
 		error: state.error
 	});
 	let lastPublished = null;
+	let cachedState = null;
 	const publicStateChanged = (prev, next) => prev.isActive !== next.isActive || observableStateChanged(prev, next);
 	const notify = () => {
 		reconcileDisplayOverrides(state.localState, state.displayOverrides);
@@ -640,6 +642,7 @@ const createCollectionSubscription = (options) => {
 		if (lastPublished !== null && !publicStateChanged(lastPublished, publicState)) return;
 		lastPublished = publicState;
 		cachedHandle = null;
+		cachedState = publicState;
 		subscribers.forEach((fn) => fn(publicState));
 		store.reportSyncState(syncKey, publicState.isSynced);
 	};
@@ -856,8 +859,7 @@ const createCollectionSubscription = (options) => {
 		update: updateState,
 		add: addDocument,
 		remove: removeDocument,
-		isLoading: state.isLoading,
-		isSynced: state.localState === void 0,
+		isLoaded: state.isActive && !state.isLoading,
 		isActive: state.isActive,
 		load,
 		sync,
@@ -868,11 +870,15 @@ const createCollectionSubscription = (options) => {
 		if (cachedHandle === null) cachedHandle = buildHandle();
 		return cachedHandle;
 	};
+	const getState = () => {
+		if (cachedState === null) cachedState = getPublicState();
+		return cachedState;
+	};
 	return {
 		load,
 		stop,
 		subscribe,
-		getState: getPublicState,
+		getState,
 		getHandle,
 		sync
 	};
@@ -939,10 +945,12 @@ const createDocumentSubscription = (options) => {
 	const getPublicState = () => ({
 		data: getMergedData(),
 		isLoading: state.isLoading,
+		isLoaded: !state.isLoading,
 		isSynced: state.localState === void 0,
 		error: state.error
 	});
 	let lastPublished = null;
+	let cachedState = null;
 	const publicStateChanged = observableStateChanged;
 	const notify = () => {
 		reconcileDisplayOverrides(state.localState && typeof state.localState === "object" ? state.localState : void 0, state.displayOverrides);
@@ -950,6 +958,7 @@ const createDocumentSubscription = (options) => {
 		if (lastPublished !== null && !publicStateChanged(lastPublished, publicState)) return;
 		lastPublished = publicState;
 		cachedHandle = null;
+		cachedState = publicState;
 		subscribers.forEach((fn) => fn(publicState));
 		store.reportSyncState(syncKey, publicState.isSynced);
 	};
@@ -1168,8 +1177,7 @@ const createDocumentSubscription = (options) => {
 		update: updateState,
 		set: setData,
 		delete: deleteDocument,
-		isLoading: state.isLoading,
-		isSynced: state.localState === void 0,
+		isLoaded: !state.isLoading,
 		sync,
 		error: state.error,
 		ref: docRef
@@ -1178,11 +1186,15 @@ const createDocumentSubscription = (options) => {
 		if (cachedHandle === null) cachedHandle = buildHandle();
 		return cachedHandle;
 	};
+	const getState = () => {
+		if (cachedState === null) cachedState = getPublicState();
+		return cachedState;
+	};
 	return {
 		load,
 		stop,
 		subscribe,
-		getState: getPublicState,
+		getState,
 		getHandle,
 		sync
 	};
@@ -1286,6 +1298,7 @@ const getDocumentShared = ({ store, definition, collectionPath, docId, readOnly
 			}
 			return readOnlyHandle;
 		},
+		getState: () => ent.sub.getState(),
 		load: () => ent.sub.load(),
 		setUndoable: (enabled) => {
 			if (facadeReadOnly) return;
@@ -1368,6 +1381,7 @@ const getCollectionShared = ({ store, definition, collectionPath, readOnly, quer
 			}
 			return readOnlyHandle;
 		},
+		getState: () => ent.sub.getState(),
 		load: () => ent.sub.load(),
 		setUndoable: (enabled) => {
 			if (facadeReadOnly) return;
@@ -1476,8 +1490,7 @@ const DISABLED_DOCUMENT_HANDLE = {
 	update: NOOP,
 	set: NOOP,
 	delete: NOOP,
-	isLoading: false,
-	isSynced: true,
+	isLoaded: false,
 	sync: ASYNC_NOOP,
 	error: void 0,
 	ref: void 0
@@ -1488,21 +1501,36 @@ const DISABLED_COLLECTION_HANDLE = {
 	update: NOOP,
 	add: DISABLED_ADD,
 	remove: NOOP,
-	isLoading: false,
-	isSynced: true,
+	isLoaded: false,
 	isActive: false,
 	load: NOOP,
 	sync: ASYNC_NOOP,
 	error: void 0,
 	ref: void 0
 };
+const DISABLED_DOCUMENT_STATE = {
+	data: void 0,
+	isLoading: false,
+	isLoaded: false,
+	isSynced: true,
+	error: void 0
+};
+const DISABLED_COLLECTION_STATE = {
+	data: EMPTY_RECORD,
+	isLoading: false,
+	isLoaded: false,
+	isSynced: true,
+	isActive: false,
+	error: void 0
+};
 /**
-* Equality over an {@link ObservableSelection} (no-selector path): status fields
-* compared by identity, the `data` slice by `dataEqual` (the default value
-* comparison). This is what lets a change to a value-equal `data` be collapsed
-* while any status change still re-renders the plain handle.
+* Equality over a {@link DefaultSelection} (no-selector path): `isLoaded`,
+* `error`, and a collection's `isActive` compared by identity, the `data` slice
+* by `dataEqual` (the default value comparison). `isSynced` is absent by design,
+* so a sync flip cannot re-render the plain handle; a change to value-equal
+* `data` is still collapsed, while a load transition re-renders.
 */
-const selectionEqual = (a, b, dataEqual) => a.isLoading === b.isLoading && a.isSynced === b.isSynced && a.error === b.error && a.isActive === b.isActive && dataEqual(a.data, b.data);
+const defaultSelectionEqual = (a, b, dataEqual) => a.isLoaded === b.isLoaded && a.error === b.error && a.isActive === b.isActive && dataEqual(a.data, b.data);
 const defaultDataEqual = valuesEqualForNoOp;
 /**
 * Context for providing the Firestate store
@@ -1575,19 +1603,16 @@ function useDocument(options) {
 		}
 		return release;
 	}, [shared]);
-	const getSnapshot = useCallback(() => shared ? shared.getHandle() : DISABLED_DOCUMENT_HANDLE, [shared]);
-	const selection = useSyncExternalStoreWithSelector(subscribe, getSnapshot, getSnapshot, useCallback((handle) => {
-		const state = {
-			data: handle.data,
-			isLoading: handle.isLoading,
-			isSynced: handle.isSynced,
-			error: handle.error
-		};
-		return selector ? selector(state) : state;
-	}, [selector]), useCallback((a, b) => selector ? (isEqual ?? defaultDataEqual)(a, b) : selectionEqual(a, b, defaultDataEqual), [selector, isEqual]));
+	const getStateSnapshot = useCallback(() => shared ? shared.getState() : DISABLED_DOCUMENT_STATE, [shared]);
+	const getHandle = useCallback(() => shared ? shared.getHandle() : DISABLED_DOCUMENT_HANDLE, [shared]);
+	const selection = useSyncExternalStoreWithSelector(subscribe, getStateSnapshot, getStateSnapshot, useCallback((state) => selector ? selector(state) : {
+		data: state.data,
+		isLoaded: state.isLoaded,
+		error: state.error
+	}, [selector]), useCallback((a, b) => selector ? (isEqual ?? defaultDataEqual)(a, b) : defaultSelectionEqual(a, b, defaultDataEqual), [selector, isEqual]));
 	const hasSelector = selector != null;
 	return useMemo(() => {
-		const handle = getSnapshot();
+		const handle = getHandle();
 		if (hasSelector) return {
 			data: selection,
 			update: handle.update,
@@ -1602,15 +1627,14 @@ function useDocument(options) {
 			update: handle.update,
 			set: handle.set,
 			delete: handle.delete,
-			isLoading: s.isLoading,
-			isSynced: s.isSynced,
+			isLoaded: s.isLoaded,
 			sync: handle.sync,
 			error: s.error,
 			ref: handle.ref
 		};
 	}, [
 		selection,
-		getSnapshot,
+		getHandle,
 		hasSelector
 	]);
 }
@@ -1663,20 +1687,17 @@ function useCollection(options) {
 		}
 		return release;
 	}, [shared, isLazy]);
-	const getSnapshot = useCallback(() => shared ? shared.getHandle() : DISABLED_COLLECTION_HANDLE, [shared]);
-	const selection = useSyncExternalStoreWithSelector(subscribe, getSnapshot, getSnapshot, useCallback((handle) => {
-		const state = {
-			data: handle.data,
-			isLoading: handle.isLoading,
-			isSynced: handle.isSynced,
-			isActive: handle.isActive,
-			error: handle.error
-		};
-		return selector ? selector(state) : state;
-	}, [selector]), useCallback((a, b) => selector ? (isEqual ?? defaultDataEqual)(a, b) : selectionEqual(a, b, defaultDataEqual), [selector, isEqual]));
+	const getStateSnapshot = useCallback(() => shared ? shared.getState() : DISABLED_COLLECTION_STATE, [shared]);
+	const getHandle = useCallback(() => shared ? shared.getHandle() : DISABLED_COLLECTION_HANDLE, [shared]);
+	const selection = useSyncExternalStoreWithSelector(subscribe, getStateSnapshot, getStateSnapshot, useCallback((state) => selector ? selector(state) : {
+		data: state.data,
+		isLoaded: state.isLoaded,
+		isActive: state.isActive,
+		error: state.error
+	}, [selector]), useCallback((a, b) => selector ? (isEqual ?? defaultDataEqual)(a, b) : defaultSelectionEqual(a, b, defaultDataEqual), [selector, isEqual]));
 	const hasSelector = selector != null;
 	return useMemo(() => {
-		const handle = getSnapshot();
+		const handle = getHandle();
 		if (hasSelector) return {
 			data: selection,
 			update: handle.update,
@@ -1692,8 +1713,7 @@ function useCollection(options) {
 			update: handle.update,
 			add: handle.add,
 			remove: handle.remove,
-			isLoading: s.isLoading,
-			isSynced: s.isSynced,
+			isLoaded: s.isLoaded,
 			isActive: s.isActive ?? false,
 			load: handle.load,
 			sync: handle.sync,
@@ -1702,10 +1722,96 @@ function useCollection(options) {
 		};
 	}, [
 		selection,
-		getSnapshot,
+		getHandle,
 		hasSelector
 	]);
 }
+const syncStatusSelector = (state) => ({
+	isSynced: state.isSynced,
+	isSaving: !state.isSynced
+});
+const loadingStatusSelector = (state) => ({
+	isLoading: state.isLoading,
+	isLoaded: state.isLoaded
+});
+/**
+* Subscribe to a document's **sync status only** — `{ isSynced, isSaving }`.
+*
+* The opt-in counterpart to the sync-agnostic default handle (see
+* {@link DocumentHandle}): it re-renders when sync state flips but never on data
+* changes, and shares the resource's one `onSnapshot` listener with
+* `useDocument` and any slice hooks, so opting in adds no listener. While
+* disabled it reports `{ isSynced: true, isSaving: false }`.
+*/
+function useDocumentSyncStatus(options) {
+	return useDocument({
+		definition: options.definition,
+		params: options.params,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: syncStatusSelector
+	}).data;
+}
+/**
+* Subscribe to a document's **loading status only** — `{ isLoading, isLoaded }`.
+*
+* A spinner channel that shares the resource's listener and does NOT re-render
+* on data changes — for a progress indicator rendered apart from the data. The
+* data handle keeps `isLoaded` for the common render path; this is an extra
+* channel, not a replacement.
+*/
+function useDocumentLoadingStatus(options) {
+	return useDocument({
+		definition: options.definition,
+		params: options.params,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: loadingStatusSelector
+	}).data;
+}
+/**
+* Collection counterpart of {@link useDocumentSyncStatus} — `{ isSynced,
+* isSaving }` over a collection query, sharing its one listener.
+*
+* **Lazy caveat.** On a `lazy` collection this hook never calls `load()` itself:
+* activating a lazy listener is the data hook's job, and a passive status reader
+* must not silently start the listener (and bill the reads) the laziness exists
+* to defer. As the *lone* subscriber it therefore attaches no listener and stays
+* at the idle `{ isSynced: true, isSaving: false }`. Mount it alongside a
+* {@link useCollection} on the same query whose `load()` has run — the status
+* hook rides that one shared listener and reports real sync state. Non-lazy
+* collections activate on mount, so this hook works standalone there.
+*/
+function useCollectionSyncStatus(options) {
+	return useCollection({
+		definition: options.definition,
+		params: options.params,
+		queryConstraints: options.queryConstraints,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: syncStatusSelector
+	}).data;
+}
+/**
+* Collection counterpart of {@link useDocumentLoadingStatus} — `{ isLoading,
+* isLoaded }` over a collection query, sharing its one listener.
+*
+* Same lazy caveat as {@link useCollectionSyncStatus}: on a `lazy` collection it
+* never calls `load()`, so as the lone subscriber it attaches no listener and
+* stays at the idle `{ isLoading: false, isLoaded: false }` until a co-mounted
+* {@link useCollection} (or any active hook on the same query) activates the
+* shared listener via `load()`. Non-lazy collections activate on mount.
+*/
+function useCollectionLoadingStatus(options) {
+	return useCollection({
+		definition: options.definition,
+		params: options.params,
+		queryConstraints: options.queryConstraints,
+		enabled: options.enabled,
+		readOnly: true,
+		selector: loadingStatusSelector
+	}).data;
+}
 /**
 * Keyboard shortcut hook for undo/redo
 *
@@ -1865,6 +1971,16 @@ function createFirestate(registry) {
 				definition,
 				params
 			});
+			api[`${hookName}SyncStatus`] = (params = {}, options = {}) => useDocumentSyncStatus({
+				definition,
+				params,
+				enabled: options.enabled
+			});
+			api[`${hookName}LoadingStatus`] = (params = {}, options = {}) => useDocumentLoadingStatus({
+				definition,
+				params,
+				enabled: options.enabled
+			});
 		} else if (entry.__kind === "collection") {
 			const definition = colDefFor(entry);
 			api[hookName] = (params = {}, options = {}) => useCollection({
@@ -1872,6 +1988,18 @@ function createFirestate(registry) {
 				definition,
 				params
 			});
+			api[`${hookName}SyncStatus`] = (params = {}, options = {}) => useCollectionSyncStatus({
+				definition,
+				params,
+				enabled: options.enabled,
+				queryConstraints: options.queryConstraints
+			});
+			api[`${hookName}LoadingStatus`] = (params = {}, options = {}) => useCollectionLoadingStatus({
+				definition,
+				params,
+				enabled: options.enabled,
+				queryConstraints: options.queryConstraints
+			});
 		} else if (entry.__kind === "document-selected") {
 			const definition = docDefFor(entry.base);
 			const { selector, isEqual } = entry;
@@ -2032,6 +2160,37 @@ const shallow = (a, b) => {
 
 //#endregion
 //#region src/utils/undo.ts
+const getGroupedActions = (action) => action.actions ?? [action];
+/**
+* Apply a group in the required direction. If a member fails, compensate the
+* members already applied so a failed undo/redo does not leave the group
+* partially applied (provided the compensating actions themselves succeed).
+*/
+const applyGroup = async (actions, operation) => {
+	const ordered = operation === "undo" ? [...actions].reverse() : actions;
+	const applied = [];
+	try {
+		for (const action of ordered) {
+			await action[operation]();
+			applied.push(action);
+		}
+	} catch (error) {
+		const compensate = operation === "undo" ? "redo" : "undo";
+		for (const action of applied.reverse()) await action[compensate]();
+		throw error;
+	}
+};
+const mergeGroupedActions = (older, newer) => {
+	const actions = [...getGroupedActions(older), newer];
+	return {
+		undo: () => applyGroup(actions, "undo"),
+		redo: () => applyGroup(actions, "redo"),
+		groupId: newer.groupId,
+		path: newer.path ?? older.path,
+		description: newer.description ?? older.description,
+		actions
+	};
+};
 /**
 * Create an undo manager instance.
 * This is a standalone, framework-agnostic implementation.
@@ -2051,7 +2210,7 @@ const shallow = (a, b) => {
 * ```
 */
 const createUndoManager = (config = {}) => {
-	const { maxLength = 20, onNavigate } = config;
+	const { maxLength = 20, onNavigate, onUndo, onRedo, onError } = config;
 	let undoStack = [];
 	let redoStack = [];
 	const subscribers = /* @__PURE__ */ new Set();
@@ -2075,19 +2234,7 @@ const createUndoManager = (config = {}) => {
 			const last = undoStack[undoStack.length - 1];
 			if (last?.groupId === action.groupId) {
 				undoStack.pop();
-				undoStack.push({
-					undo: async () => {
-						await action.undo();
-						await last.undo();
-					},
-					redo: async () => {
-						await last.redo();
-						await action.redo();
-					},
-					groupId: action.groupId,
-					path: action.path ?? last.path,
-					description: action.description ?? last.description
-				});
+				undoStack.push(mergeGroupedActions(last, action));
 				redoStack = [];
 				notify();
 				return;
@@ -2101,31 +2248,35 @@ const createUndoManager = (config = {}) => {
 	const undo = async () => {
 		const action = undoStack.pop();
 		if (!action) return;
-		if (action.path && onNavigate) onNavigate(action.path);
 		try {
+			if (action.path && onNavigate) onNavigate(action.path);
 			await action.undo();
-			redoStack.push(action);
 		} catch (error) {
 			undoStack.push(action);
-			console.error("Undo failed:", error);
+			if (onError) onError(error, action, "undo");
+			else console.error("Undo failed:", error);
 			throw error;
 		}
+		redoStack.push(action);
 		notify();
+		onUndo?.(action);
 	};
 	const redo = async () => {
 		const action = redoStack.pop();
 		if (!action) return;
-		if (action.path && onNavigate) onNavigate(action.path);
 		try {
+			if (action.path && onNavigate) onNavigate(action.path);
 			await action.redo();
-			undoStack.push(action);
-			if (undoStack.length > maxLength) undoStack.shift();
 		} catch (error) {
 			redoStack.push(action);
-			console.error("Redo failed:", error);
+			if (onError) onError(error, action, "redo");
+			else console.error("Redo failed:", error);
 			throw error;
 		}
+		undoStack.push(action);
+		if (undoStack.length > maxLength) undoStack.shift();
 		notify();
+		onRedo?.(action);
 	};
 	const clear = () => {
 		undoStack = [];
@@ -2183,9 +2334,22 @@ const createStore = (config) => {
 	const { firestore, autosave = 1e3, minLoadTime = 0, maxUndoLength = 20 } = config;
 	let onError = config.onError;
 	let onNavigate = config.onNavigate;
+	let onUndo = config.onUndo;
+	let onRedo = config.onRedo;
 	const undoManager = createUndoManager({
 		maxLength: maxUndoLength,
-		onNavigate: (path) => onNavigate?.(path)
+		onNavigate: (path) => onNavigate?.(path),
+		onUndo: (action) => onUndo?.(action),
+		onRedo: (action) => onRedo?.(action),
+		onError: (error, action, operation) => {
+			const context = {
+				type: "undo",
+				path: action.path ?? "undo",
+				operation
+			};
+			if (onError) onError(error, context);
+			else console.error(`Firestate error in ${context.type} ${context.path} during ${context.operation}:`, error);
+		}
 	});
 	const syncStates = /* @__PURE__ */ new Map();
 	const syncSubscribers = /* @__PURE__ */ new Set();
@@ -2212,6 +2376,12 @@ const createStore = (config) => {
 		setOnNavigate: (handler) => {
 			onNavigate = handler;
 		},
+		setOnUndo: (handler) => {
+			onUndo = handler;
+		},
+		setOnRedo: (handler) => {
+			onRedo = handler;
+		},
 		subscribeToSyncState: (fn) => {
 			syncSubscribers.add(fn);
 			return () => syncSubscribers.delete(fn);
@@ -2258,14 +2428,16 @@ const createStore = (config) => {
 * }
 * ```
 */
-const FirestateProvider = ({ firestore, autosave = 1e3, minLoadTime = 0, maxUndoLength = 20, onError, onNavigate, children }) => {
+const FirestateProvider = ({ firestore, autosave = 1e3, minLoadTime = 0, maxUndoLength = 20, onError, onNavigate, onUndo, onRedo, children }) => {
 	const store = useMemo(() => createStore({
 		firestore,
 		autosave,
 		minLoadTime,
 		maxUndoLength,
 		onError,
-		onNavigate
+		onNavigate,
+		onUndo,
+		onRedo
 	}), [
 		firestore,
 		autosave,
@@ -2278,6 +2450,12 @@ const FirestateProvider = ({ firestore, autosave = 1e3, minLoadTime = 0, maxUndo
 	useEffect(() => {
 		store.setOnNavigate(onNavigate);
 	}, [store, onNavigate]);
+	useEffect(() => {
+		store.setOnUndo(onUndo);
+	}, [store, onUndo]);
+	useEffect(() => {
+		store.setOnRedo(onRedo);
+	}, [store, onRedo]);
 	return /* @__PURE__ */ jsx(FirestateContext.Provider, {
 		value: store,
 		children
@@ -2338,5 +2516,5 @@ const useUnsavedChangesBlocker = () => {
 };
 
 //#endregion
-export { FirestateContext, FirestateProvider, FirestateStoreProvider, applyDiff, applyDiffMutable, col, computeDiff, computeUndoDiff, createCollectionSubscription, createDiffAtPath, createDocumentSubscription, createFirestate, createStore, createUndoManager, deepClone, defineCollection, defineDocument, diffContainsPath, doc, extractDiffValue, flattenDiff, flattenDiffToFieldPaths, isDeepEqual, isDiffEmpty, mergeDiffs, shallow, unflattenDiff, useCollection, useDocument, useIsSynced, useStore, useUndoKeyboardShortcuts, useUndoManager, useUnsavedChangesBlocker };
+export { FirestateContext, FirestateProvider, FirestateStoreProvider, applyDiff, applyDiffMutable, col, computeDiff, computeUndoDiff, createCollectionSubscription, createDiffAtPath, createDocumentSubscription, createFirestate, createStore, createUndoManager, deepClone, defineCollection, defineDocument, diffContainsPath, doc, extractDiffValue, flattenDiff, flattenDiffToFieldPaths, isDeepEqual, isDiffEmpty, mergeDiffs, shallow, unflattenDiff, useCollection, useCollectionLoadingStatus, useCollectionSyncStatus, useDocument, useDocumentLoadingStatus, useDocumentSyncStatus, useIsSynced, useStore, useUndoKeyboardShortcuts, useUndoManager, useUnsavedChangesBlocker };
 //# sourceMappingURL=index.mjs.map