Infinite Loading Types

Purpose

Infinite Loading Types define the TypeScript interfaces and type aliases that enable strong typing and configuration of the infinite loading feature built upon the core SWR hook. This subtopic addresses the need to precisely type the parameters, fetchers, responses, and mutation options specific to paginated and infinite data fetching scenarios. By establishing these types, it ensures type safety, IntelliSense support, and clear API contracts for developers using or extending the infinite loading functionality.

Functionality

This subtopic specifies types for several key aspects:

• Key Loaders (SWRInfiniteKeyLoader): Functions that generate the cache key for each page based on the page index and the previous page’s data. This allows dynamic and conditional pagination.

• Fetchers (SWRInfiniteFetcher): Functions that receive the key generated by the key loader and return the data for that page, either synchronously or as a Promise.

• Configuration (SWRInfiniteConfiguration): Extends the core SWR configuration with additional options unique to infinite loading, such as:

  • initialSize: Number of pages to fetch initially.

  • revalidateAll: Whether to revalidate all pages during a revalidation cycle.

  • persistSize: Whether to persist page size across re-renders.

  • parallel: Enable parallel fetching of pages.

  • Custom compare functions for deep equality checks of page data arrays.

• Response (SWRInfiniteResponse): Extends the core SWR response with infinite-loading-specific fields and methods:

  • size: Current number of pages loaded.

  • setSize: Function to update the number of pages, triggering fetch or removal accordingly.

  • Overridden mutate method to handle mutation of the paginated array of data.

• Mutator Options (SWRInfiniteMutatorOptions): Options for mutation operations, including a specialized revalidate flag or function to control revalidation per page or for the entire dataset.

• Hook Signature (SWRInfiniteHook): Overloaded type definitions for the infinite loading hook, supporting various combinations of parameters (key loader, fetcher, configuration) with appropriate typing.

• Cache Value (SWRInfiniteCacheValue): Internal cache state extension to store infinite-loading-specific metadata such as page size, key arguments, and revalidation flags to coordinate between pages and hooks sharing the same key.

These types collectively enable precise typings for the infinite loading sub-feature, ensuring consistent behavior and extensibility.

Integration

This subtopic tightly integrates with the parent topic "Infinite Loading Support" by providing the foundational type contracts that the infinite loading middleware and hooks implement. While the parent topic focuses on the runtime behavior, caching, and data concatenation for paginated requests, this subtopic defines the shape of the configuration, fetchers, and responses that drive those implementations.

It complements other subtopics by:

• Building on the core SWR types (SWRConfiguration, SWRResponse, etc.) imported from internal modules, ensuring consistency across all SWR hooks.

• Supporting the middleware architecture by typing configuration options that middleware can extend or override.

• Enabling mutation handling for paginated data sets through specialized mutator options and methods.

By providing these types, it allows the "Infinite Hook Implementation" and associated modules to enforce type safety and clarity, improving developer experience and reducing runtime errors.

Code Snippets Illustrating Key Types

Key Loader Type

Defines the function signature used to generate keys per page:

export type SWRInfiniteKeyLoader<Data = any, Args extends Arguments = Arguments> = (
  index: number,
  previousPageData: Data | null
) => Args

Infinite Response Interface

Extends SWR response with pagination controls:

export interface SWRInfiniteResponse<Data = any, Error = any> extends Omit<SWRResponse<Data[], Error>, 'mutate'> {
  size: number
  setSize: (size: number | ((_size: number) => number)) => Promise<Data[] | undefined>
  mutate: SWRInfiniteKeyedMutator<Data[]>
}

Hook Overloads

Typing the infinite loading hook with flexibility:

export interface SWRInfiniteHook {
  <Data = any, Error = any, KeyLoader extends SWRInfiniteKeyLoader = ...>(
    getKey: KeyLoader,
    fetcher?: SWRInfiniteFetcher<Data, KeyLoader> | null,
    config?: SWRInfiniteConfiguration<Data, Error, SWRInfiniteFetcher<Data, KeyLoader>>
  ): SWRInfiniteResponse<Data, Error>
}

Diagram: Infinite Loading Type Relationships

classDiagram
  class SWRInfiniteHook {
    +getKey: SWRInfiniteKeyLoader
    +fetcher?: SWRInfiniteFetcher
    +config?: SWRInfiniteConfiguration
    +returns SWRInfiniteResponse
  }

  class SWRInfiniteKeyLoader {
    +index: number
    +previousPageData: Data | null
    +returns Args
  }

  class SWRInfiniteFetcher {
    +args: Args
    +returns Data | Promise<Data>
  }

  class SWRInfiniteConfiguration {
    +initialSize: number
    +revalidateAll: boolean
    +persistSize: boolean
    +parallel: boolean
    +fetcher: SWRInfiniteFetcher
    +compare: SWRInfiniteCompareFn
  }

  class SWRInfiniteResponse {
    +size: number
    +setSize(size)
    +mutate(data, opts)
  }

  SWRInfiniteHook --> SWRInfiniteKeyLoader : uses
  SWRInfiniteHook --> SWRInfiniteFetcher : optionally uses
  SWRInfiniteHook --> SWRInfiniteConfiguration : optionally uses
  SWRInfiniteHook --> SWRInfiniteResponse : returns
  SWRInfiniteResponse --> SWRInfiniteKeyedMutator : mutate type
  SWRInfiniteConfiguration --> SWRInfiniteFetcher : fetcher type

This diagram visualizes the core types and their interactions that define the infinite loading feature's type system, highlighting how the hook uses key loaders, fetchers, and configuration to return a response with pagination controls.

By clearly defining these types, the infinite loading feature ensures type-safe, predictable, and extensible usage patterns that enhance both developer experience and runtime correctness.