Infinite Query

Infinite queries handle paginated data fetching with automatic cursor management.

Import

import { InfiniteQuery } from '@soulcache/core';

Constructor

new InfiniteQuery<TData, TPageParam>(options: InfiniteQueryOptions<TData, TPageParam>)

Types

`InfiniteQueryOptions<TData, TPageParam>`

interface InfiniteQueryOptions<TData, TPageParam> {
  readonly queryKey: QueryKey;
  readonly queryFn: (context: { pageParam: TPageParam; signal?: AbortSignal }) => Promise<TData>;
  readonly initialPageParam?: TPageParam;       // default: 0
  readonly getNextPageParam: (
    lastPage: TData, allPages: TData[],
    lastPageParam: unknown, allPageParams: unknown[],
  ) => TPageParam | undefined;
  readonly getPreviousPageParam?: (
    firstPage: TData, allPages: TData[],
    firstPageParam: unknown, allPageParams: unknown[],
  ) => TPageParam | undefined;
  readonly enabled?: boolean;
  readonly staleTime?: number;
  readonly gcTime?: number;
  readonly maxPages?: number;                   // default: 50 (set Infinity to keep all pages)
}

`InfiniteQueryState<TData>`

interface InfiniteQueryState<TData> {
  readonly pages: InfiniteQueryPage<TData>[];
  readonly pageParams: unknown[];
  readonly hasNextPage: boolean;
  readonly hasPreviousPage: boolean;
  readonly isFetchingNextPage: boolean;
  readonly isFetchingPreviousPage: boolean;
  readonly isFetching: boolean;
  readonly error: Error | null;
}

`InfiniteQueryPage<TData>`

interface InfiniteQueryPage<TData> {
  readonly data: TData;
  readonly pageParam: unknown;
  readonly pageIndex: number;
}

Properties

Property	Type	Description
`id`	`string`	Unique query ID
`queryKey`	`readonly unknown[]`	Query cache key
`data`	`TData[]`	Flat array of all page data
`state`	`InfiniteQueryState<TData>`	Snapshot of the current query state
`isLoading`	`boolean`	Whether the initial fetch is in progress (no data yet)
`isFetching`	`boolean`	Whether any fetch (initial, next, or previous) is in progress
`hasNextPage`	`boolean`	Whether next page is available
`hasPreviousPage`	`boolean`	Whether previous page is available
`isFetchingNextPage`	`boolean`	Whether next page is fetching
`isFetchingPreviousPage`	`boolean`	Whether previous page is fetching
`pageCount`	`number`	Number of loaded pages
`isDestroyed`	`boolean`	Whether query is destroyed

Methods

`fetch()`

Fetch all pages.

fetch(): Promise<void>

`fetchNextPage()`

Fetch the next page. Returns true if a new page was fetched.

fetchNextPage(): Promise<boolean>

`fetchPreviousPage()`

Fetch the previous page. Returns true if a new page was fetched.

fetchPreviousPage(): Promise<boolean>

`subscribe(listener)`

Subscribe to state changes.

subscribe(listener: () => void): () => void

`cancel()`

Cancel any in-flight fetch.

cancel(): void

`reset()`

Reset to initial state.

reset(): void

`destroy()`

Destroy the query and cleanup resources.

destroy(): void

Usage

import { InfiniteQuery } from '@soulcache/core';
 
const query = new InfiniteQuery({
  queryKey: ['posts'],
  queryFn: async ({ pageParam }) => {
    const response = await fetch(`/api/posts?page=${pageParam}`);
    return response.json();
  },
  getNextPageParam: (lastPage) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage) => firstPage.prevCursor,
});
 
// Fetch first page
await query.fetch();
 
// Fetch next page
const hasNext = await query.fetchNextPage();
 
// Subscribe to updates
const unsubscribe = query.subscribe(() => {
  console.log(query.data);
  console.log(query.hasNextPage);
});

Features

Automatic Cursor Management

Cursor tracking is handled automatically between pages

Bidirectional Pagination

Support for both forward and backward pagination

Bounded Page Window

Up to 50 pages retained by default to control memory

Max Pages Limit

Control memory usage by limiting number of kept pages

Best Practices

Infinite Query Guidelines

Use stable cursors — Ensure consistent pagination across refetches
Handle loading states — Show feedback during page fetches
Implement error boundaries — Handle fetch failures gracefully
Understand the page cap — Up to 50 pages are retained by default; oldest pages are evicted beyond the cap. Set maxPages: Infinity to keep every page, or a smaller value to bound memory harder.