newOS for Developers
Back to Overview
useProgressiveLiveQuery
hook20 linesA wrapper around Dexie's useLiveQuery that integrates with the ProgressiveHandler pattern for reactive data fetching with IndexedDB caching.
Source Path
apps/web/hooks/useProgressiveLiveQuery.tsPackage
@newos/web
Signature
useProgressiveLiveQuery<T>(
querier: () => ProgressiveHandlerResponse<T>,
deps?: unknown[]
): [T | undefined, ProgressEntrySignal | undefined]Parameters
| Parameter | Type | Description |
|---|---|---|
| querier | () => ProgressiveHandlerResponse<T> | Function returning a ProgressiveHandler result (typically from a newgraph-signals action) |
| deps | unknown[] | Dependency array for re-running the query (like useEffect deps) |
Return Value
[
data: T | undefined, // The fetched data, reactive to IndexedDB changes
progress: ProgressEntrySignal | undefined // Progress status with loading/error state
]ProgressEntrySignal Properties
value.inProgress — Boolean indicating if fetch is in progressvalue.done — Boolean indicating if all pages are loadedvalue.error — Error object if fetch failedvalue.page — Current page number for paginationvalue.continue() — Function to load next pagevalue.reset() — Function to reset paginationUsage Examples
Basic Usage
const [folder, progress] = useProgressiveLiveQuery(
() => readFolder({ id: folderId }),
[folderId]
);
if (progress?.value.inProgress) {
return <Spinner />;
}
return <FolderView folder={folder} />;With Pagination
const [posts, progress] = useProgressiveLiveQuery(
() => readPosts({ folderId, page: 0 }),
[folderId]
);
// Load more posts when needed
const loadMore = () => {
if (!progress?.value.done && !progress?.value.inProgress) {
progress?.value.continue();
}
};How It Works
1. Calls the
querier function which returns a ProgressiveHandlerResponse2. Extracts the Dexie observable from the response
3. Passes it to
useLiveQuery from dexie-react-hooks4. Returns the reactive data along with progress signal
5. Data automatically updates when IndexedDB cache changes
Edge Cases & Gotchas
Initial undefined — Both return values can be
undefinedon first render before data is fetched.Dependency Array — Changing dependencies will re-run the query. Use stable references to avoid infinite loops.
ProgressiveHandler Required — Only works with actions that return
ProgressiveHandlerResponse from newgraph-signals.Cache-First — Returns cached data immediately, then updates when API response arrives. Handle stale data display accordingly.