apps/web/public/assets/posts/live-mode-infinite-query/infinite-query.png

reviewed

This is a binary file and will not be displayed.

apps/web/public/assets/posts/live-mode-infinite-query/offset-caveat.png

reviewed

This is a binary file and will not be displayed.

apps/web/public/assets/posts/live-mode-infinite-query/tanstack.png

reviewed

This is a binary file and will not be displayed.

+170

apps/web/src/content/posts/live-mode-infinite-query.mdx

reviewed

··· 1 1 + --- 2 2 + title: Live Mode 3 3 + description: How we leverage TanStack Infinite Query for implementing live mode 4 4 + author: 5 5 + name: Maximilian Kaske 6 6 + url: https://x.com/mxkaske 7 7 + avatar: /assets/authors/max.png 8 8 + publishedAt: 2025-03-15 9 9 + image: /assets/posts/live-mode-infinite-query/tanstack.png 10 10 + tag: engineering 11 11 + --- 12 12 + 13 13 + While TanStack provides excellent [documentation on Infinite Queries](https://tanstack.com/query/latest/docs/framework/react/guides/infinite-queries), this article offers an additional practical example focusing on implementing live data updates. 14 14 + 15 15 + ## Basic Concept 16 16 + 17 17 + Infinite queries work with "pages" of data. Each time you load new data, a new "page" is either appended or prepended to the `data.pages` array. To get a flat list of all data in the correct order, you simply use `flatMap`: 18 18 + 19 19 + ```ts 20 20 + const { data, fetchNextPage, fetchPreviousPage } = 21 21 + useInfiniteQuery(dataOptions); 22 22 + 23 23 + const flatData = React.useMemo( 24 24 + () => data?.pages?.flatMap((page) => page.data ?? []) ?? [], 25 25 + [data?.pages], 26 26 + ); 27 27 + ``` 28 28 + 29 29 +  30 30 + 31 31 + Once we understand the _load more_ (append data) functionality, we can mirror this approach to implement _live mode_ (prepend data). 32 32 + 33 33 + Each query requires two key parameters: 34 34 + 35 35 + 1. A `cursor` - a pointer indicating a position in the dataset 36 36 + 2. A `direction` - specifying whether to fetch data before or after the cursor ("prev" or "next") 37 37 + 38 38 + In our implementation, the `cursor` is a timestamp representing the last checked date: 39 39 + 40 40 + ```ts 41 41 + const dataOptions = { 42 42 + queryKey: "data-table", 43 43 + queryFn: async ({ pageParam }) => { 44 44 + const { cursor, direction } = pageParam; 45 45 + const res = await fetch( 46 46 + `/api/get/data?cursor=${cursor}&direction=${direction}`, 47 47 + ); 48 48 + const json = await res.json(); 49 49 + // For direction "next": { data: [...], nextCursor: 1741526294, prevCursor: null } 50 50 + // For direction "prev": { data: [...], nextCursor: null, prevCursor: 1741526295 } 51 51 + return json as ReturnType; 52 52 + }, 53 53 + // Initialize with current timestamp for "load more" functionality 54 54 + initialPageParam: { cursor: new Date().getTime(), direction: "next" }, 55 55 + getPreviousPageParam: (firstPage, allPages) => { 56 56 + if (!firstPage.prevCursor) return null; 57 57 + return { cursor: firstPage.prevCursor, direction: "prev" }; 58 58 + }, 59 59 + getNextPageParam: (lastPage, allPages) => { 60 60 + if (!lastPage.nextCursor) return null; 61 61 + return { cursor: lastPage.nextCursor, direction: "next" }; 62 62 + }, 63 63 + }; 64 64 + ``` 65 65 + 66 66 + The `getPreviousPageParam` and `getNextPageParam` functions receive the first and last pages respectively as their first parameter. This allows us to access the `prevCursor` and `nextCursor` values to track our position when loading more items or checking for updates in live mode. 67 67 + 68 68 + TanStack provides helpful states like `isFetchingNextPage` and `isFetchingPreviousPage` for loading indicators, as well as `hasNextPage` and `hasPreviousPage` to check for available pages - especially useful for as we can hit the end of the load more values. 69 69 + 70 70 + Your API endpoint should return at minimum: 71 71 + 72 72 + ```ts 73 73 + type ReturnType<T> = { 74 74 + data: T[]; 75 75 + nextCursor?: number | null; 76 76 + prevCursor?: number | null; 77 77 + }; 78 78 + ``` 79 79 + 80 80 + When fetching older pages ("next" direction), we set a `LIMIT` (e.g., 40 items). However, when fetching newer data ("prev" direction), we return all data between the `prevCursor` and `Date.now()`. 81 81 + 82 82 + Example API implementation: 83 83 + 84 84 + ```ts 85 85 + export async function GET(req: NextRequest) { 86 86 + const searchParams = request.nextUrl.searchParams; 87 87 + const cursor = searchParams.get("cursor"); 88 88 + const direction = searchParams.get("direction"); 89 89 + 90 90 + // Live mode 91 91 + if (direction === "prev") { 92 92 + const prevCursor = Date.now(); 93 93 + const data = await sql` 94 94 + SELECT * FROM table 95 95 + WHERE timestamp > ${cursor} AND timestamp <= ${prevCursor} 96 96 + ORDER BY timestamp DESC 97 97 + `; 98 98 + const res: ReturnType<MyData> = { data, prevCursor, nextCursor: null }; 99 99 + return Response.json(res); 100 100 + // Load more 101 101 + } else { 102 102 + const data = await sql` 103 103 + SELECT * FROM table 104 104 + WHERE timestamp < ${cursor} 105 105 + ORDER BY timestamp DESC 106 106 + LIMIT 40 107 107 + `; 108 108 + const nextCursor = data.length > 0 ? data[data.length - 1].timestamp : null; 109 109 + const res: ReturnType<MyData> = { data, nextCursor, prevCursor: null }; 110 110 + return Response.json(res); 111 111 + } 112 112 + } 113 113 + ``` 114 114 + 115 115 + Key points: 116 116 + 117 117 + - Live mode ("prev" direction): Returns all new data between `Date.now()` and the `cursor` 118 118 + - Load more ("next" direction): Returns 40 items before the `cursor` and updates `nextCursor` 119 119 + 120 120 + > Important: Be careful with timestamp boundaries. If items share the same timestamp, you might miss data because of the `>` comparison. To prevent data loss, include all items sharing the same timestamp as the last item in your query. 121 121 + 122 122 + ### Avoiding OFFSET with Frequent Data Updates 123 123 + 124 124 + While it might be tempting to use `OFFSET` for pagination (without having live mode active), this approach can cause problems when data is frequently prepended: 125 125 + 126 126 + ```ts 127 127 + const data = await sql` 128 128 + SELECT * FROM table 129 129 + ORDER BY timestamp DESC 130 130 + LIMIT ${limit} 131 131 + OFFSET ${offset} 132 132 + `; 133 133 + ``` 134 134 + 135 135 +  136 136 + 137 137 + When new items are prepended, they shift the offset values, potentially causing duplicate items in subsequent queries. 138 138 + 139 139 + ### Implementing Auto-Refresh 140 140 + 141 141 + While TanStack Query provides a `refetchInterval` option, it would refetch all pages, growing increasingly expensive as more pages are loaded. Instead, we implement a custom refresh mechanism for fetching only new data: 142 142 + 143 143 + ```tsx 144 144 + const REFRESH_INTERVAL = 5_000; // 5 seconds 145 145 + 146 146 + React.useEffect(() => { 147 147 + let timeoutId: NodeJS.Timeout; 148 148 + 149 149 + async function fetchData() { 150 150 + // isLive is a simple boolean from React.useState<boolean>() 151 151 + // or nuqs useQueryState("live", parseAsBoolean) 152 152 + if (isLive) { 153 153 + await fetchPreviousPage?.(); 154 154 + timeoutId = setTimeout(fetchData, REFRESH_INTERVAL); 155 155 + } else { 156 156 + clearTimeout(timeoutId); 157 157 + } 158 158 + } 159 159 + 160 160 + fetchData(); 161 161 + 162 162 + return () => { 163 163 + clearTimeout(timeoutId); 164 164 + }; 165 165 + }, [isLive, fetchPreviousPage]); 166 166 + ``` 167 167 + 168 168 + We use `setTimeout` with recursion rather than `setInterval` to ensure each refresh only starts after the previous one completes. This prevents multiple simultaneous fetches when network latency exceeds the refresh interval and is a better UX. 169 169 + 170 170 + For more details about our data table implementation, check out [The React data-table I always wanted](https://www.openstatus.dev/blog/data-table-redesign).