Add collection-level pagination metadata support to avoid wasteful peek-ahead pattern

[KyleAMathews]

Problem

Currently, useLiveInfiniteQuery uses a "peek ahead" pattern to determine if there's a next page:

// Request one extra item
const expectedLimit = loadedPageCount * pageSize + 1 // +1 for peek ahead

// Check if we got the extra item
const hasMore = dataArray.length > totalItemsRequested

This works well for:

• Electric collections: Push-based sync, no control over what's available (though we could also modify this to avoid the extra fetch)
• LiveQueryCollection: Reactive local computation, no external API

But it's wasteful for QueryCollection where users control the queryFn and their API already returns pagination metadata:

queryFn: async (ctx) => {
  const response = await fetch(url)
  const json = await response.json()
  
  // API already tells us hasNextPage!
  return json.items  // { items: [...], hasNextPage: true, totalCount: 100 }
}

The extra item fetch wastes:

• Network bandwidth
• Database query costs
• API rate limits

Proposed Solution

Add collection-level pagination metadata storage:

// Collections expose pagination metadata API
interface Collection {
  setPaginationMeta(sessionId: string, meta: PaginationMeta): void
  getPaginationMeta(sessionId: string): PaginationMeta | undefined
}

type PaginationMeta = {
  hasNextPage?: boolean
  hasPrevPage?: boolean
  nextCursor?: string
  prevCursor?: string
  totalCount?: number
}

Session ID from Query Predicates

Session ID should be a deterministic hash of:

• Collection ID
• WHERE clauses
• ORDER BY clauses
• Excluding: limit, offset

This enables:

• Same query = same session = reuse pagination state
• Different query = different session = isolated pagination
• Multiple concurrent infinite queries on same collection don't interfere

Implementation using existing serializePredicates pattern:

const sessionId = hashKey([
  collectionId,
  JSON.stringify({ where: opts.where, orderBy: opts.orderBy })
])

Usage in QueryCollection

queryFn: async (ctx) => {
  const response = await fetch(url)
  const json = await response.json()
  
  // Store pagination metadata
  ctx.collection.setPaginationMeta(ctx.sessionId, {
    hasNextPage: json.hasNextPage,
    totalCount: json.totalCount,
    nextCursor: json.nextCursor  // For future cursor support
  })
  
  return json.items
}

Updated useLiveInfiniteQuery

// Check for pagination metadata first
const meta = queryResult.collection.getPaginationMeta(sessionId)
const hasNextPage = meta?.hasNextPage ?? fallbackToPeekAhead()

// Adjust window: no +1 if metadata exists
const limit = meta ? loadedPageCount * pageSize : loadedPageCount * pageSize + 1

Broader Context: Cursor-Based Pagination

This also lays groundwork for cursor-based pagination (from related discussion):

Cursor Storage Concept

• Store cursor per infinite query session
• QueryFn retrieves stored cursor and passes to API
• If page under-fills, keep fetching until limit met
• Requires consistent ORDER BY matching cursor's order

Metadata Columns Approach

To support multiple concurrent queries with different ORDER BY on same collection:

• Session ID isolates pagination sets
• Each session tracks its own cursor/position
• Prevents "page mixing" when different orderings are used

Primary Key Tie-breaker

• Using PK as final ORDER BY element provides deterministic ordering
• Enables DB-native cursor positioning
• Could be enforced when cursor mode is enabled

Cursor + Offset Hybrid

Potentially support starting with offset then switching to cursor:

// Jump to page 5 via offset
// Then infinite scroll from there via cursor
useLiveInfiniteQuery(query, { 
  pageSize: 20, 
  initialOffset: 100  // Start at item 100
  // Then use cursor from API
})

Benefits

• ✅ QueryCollection: No wasteful +1 fetch when API provides hasNextPage
• ✅ Backward compatible: Collections without metadata fall back to peek ahead
• ✅ Foundation for cursors: Enables future cursor-based pagination
• ✅ Session isolation: Multiple concurrent infinite queries work correctly
• ✅ Extensible: Can store other metadata (totalCount, sync progress, etc.)

Open Questions

1. Storage location: Collection property vs separate registry?
2. API surface: Methods on collection vs separate pagination manager?
3. Cursor implementation: Should we tackle cursors now or separate issue?
4. Order validation: Should we detect/prevent ORDER BY changes within session?
5. Cursor + offset: Should both be supported simultaneously or exclusive modes?

Related Use Cases

Beyond hasNextPage, this could also support:

• Total count for "X of Y" UI
• Sync progress tracking
• Stream positions/snapshots
• Transaction IDs for Electric collections
• Custom pagination metadata from APIs

[samwillis]

I think this is a good plan - couple of thoughts:

• sessionId can be just the existing subscription to the collection (it's essentially a session), that will make a good key. It also holds the "session" data already (where, orderby ect), and can be extended. I think it's best to stick to that rather than introduce a new session concept.
• This: "The extra item fetch wastes: / Network bandwidth / Database query costs / API rate limits", is true for the current system where we have to do a request for all items of the max value, but with the other plan of having the PK as a tie break there will be no editional fetched, the data on the wire and number of requests would be the same as with this proposal. Supporting api returned cursors is worth doing, we need to add it, but I wouldn't push this as the core argument for cursor vs PK tie-break.
• We should build this in a generic way that can be used by all collection implementations that want it. But I would like to avoid this abstraction leaking into the query engine itself - I think thats doable.

[kevin-dp]

I like the idea of adding a context store to the collection. However, i would like even more for this context to be completely generic and the collection being unaware of its contents:

type CollectionContext = Record<string, unknown> | undefined // same type as a query function's context

This means that the collection implementer can add whatever data into the context (e.g. pagination meta data). But for pagination purposes the useLiveInfiniteQuery hook will need to rely on a user provided callback that can use the context to tell the hook what to load. Something along these line:

// Check for pagination metadata first
const ctx = queryResult.collection.getCtx(sessionId)
const paginationMeta = queryResult.collection.getPaginationInfo
// Use paginationMeta function if provided by the user
const { hasNextPage } = paginationMeta?.(ctx) ?? { hasNextPage: fallbackToPeekAhead() }
const hasNextPage = meta?.hasNextPage ?? fallbackToPeekAhead()

// Adjust window: no +1 if metadata exists
const limit = paginationMeta ? loadedPageCount * pageSize : loadedPageCount * pageSize + 1

So the idea here is that the context is generic and we can use it for pagination by storing whatever pagination meta data we need inside the context + modifying useLiveInfiniteQuery such that it takes a function (ctx: CollectionContext) => PaginationMeta that the hook can use to determine what to load and how. As such, the core collection implementation is unaware of pagination details it's only aware of a generic context and the pagination is a contract only between the collection implementer (e.g. query collection) and the user of useLiveInfiniteQuery.

EDIT: Perhaps it's a bit odd that you have to pass this function to the useInfiniteLiveQuery hook. Instead the collection could have a generic context and a separate function that you pass it to tell it how to go from context to pagination meta. The useLiveInfiniteQuery hook can then rely on both being present in the collection (i.e. it can access both the context and the function from the collection rather than receiving it as an argument)/

[enyelsequeira]

Hello, Just giving my 2 cents here as I was playing with this today and found it a bit confusing I think what you have here could work. However I still think it is a confusing API, personally if possible I think it would be nice to have the logic of pagination directly in the queryCollectionOptions something similar to what query does

queryFn: async (ctx) => {
  const response = await fetch(url)
  const json = await response.json()
  
  // Store pagination metadata
  ctx.collection.setPaginationMeta(ctx.sessionId, {
    hasNextPage: json.hasNextPage,
    totalCount: json.totalCount,
    nextCursor: json.nextCursor  // For future cursor support
  })
  
  return json.items
}

Maybe something like this would be make more sense, now the problem would be how do you know whether you would want an useLiveInfiniteQuery or just a regular query perhaps by setting a flag?

return createCollection(
    queryCollectionOptions({
      queryKey: ['staff', { session, page, sort, search, size, type }],
      queryFn: async () => fetchStaffList({ session, page, sort, search, size, type }),
      queryClient,
      getKey: (item) => item.firstName,
  initialPageParam: 0,
    getNextPageParam: (lastPage) =>
      lastPage.page?.number < lastPage.page?.totalPages ? lastPage.page?.number + 1 : undefined,
    })
  );
  

by doing this you would also simplify this part as well

 return useLiveInfiniteQuery(
    (q) => q.from({ posts: demoCollection({ session, sort, search, size, type: 'MANAGER' }) }),
// This part below wouldnt be needed anymore 
    ///{
     /// pageSize: size,
      ///getNextPageParam: (lastPage) =>
       // lastPage.page?.number < lastPage.page?.totalPages ? lastPage.page?.number + 1 : undefined,
   // },
    [] // Re-run when category changes
  );

I do think what i have is just wishful thinking and not sure if its possible, but i think in terms of DX would be a bit better and easier to understand