@push.rocks/smartrequest/ts/client/types/pagination.ts

A module for modern HTTP/HTTPS requests with support for form data, file uploads, JSON, binary data, streams, and more.

import { type CoreResponse } from '../../core/index.js';
import type { ICoreResponse } from '../../core_base/types.js';

/**
 * Pagination strategy options
 */
export enum PaginationStrategy {
  OFFSET = 'offset', // Uses page & limit parameters
  CURSOR = 'cursor', // Uses a cursor/token for next page
  LINK_HEADER = 'link', // Uses Link headers
  CUSTOM = 'custom', // Uses a custom pagination handler
}

/**
 * Configuration for offset-based pagination
 */
export interface OffsetPaginationConfig {
  strategy: PaginationStrategy.OFFSET;
  pageParam?: string; // Parameter name for page number (default: "page")
  limitParam?: string; // Parameter name for page size (default: "limit")
  startPage?: number; // Starting page number (default: 1)
  pageSize?: number; // Number of items per page (default: 20)
  totalPath?: string; // JSON path to total item count (default: "total")
}

/**
 * Configuration for cursor-based pagination
 */
export interface CursorPaginationConfig {
  strategy: PaginationStrategy.CURSOR;
  cursorParam?: string; // Parameter name for cursor (default: "cursor")
  cursorPath?: string; // JSON path to next cursor (default: "nextCursor")
  hasMorePath?: string; // JSON path to check if more items exist (default: "hasMore")
}

/**
 * Configuration for Link header-based pagination
 */
export interface LinkPaginationConfig {
  strategy: PaginationStrategy.LINK_HEADER;
  // No additional config needed, uses standard Link header format
}

/**
 * Configuration for custom pagination
 */
export interface CustomPaginationConfig {
  strategy: PaginationStrategy.CUSTOM;
  hasNextPage: (response: ICoreResponse<any>) => boolean;
  getNextPageParams: (
    response: ICoreResponse<any>,
    currentParams: Record<string, string>,
  ) => Record<string, string>;
}

/**
 * Union type of all pagination configurations
 */
export type TPaginationConfig =
  | OffsetPaginationConfig
  | CursorPaginationConfig
  | LinkPaginationConfig
  | CustomPaginationConfig;

/**
 * Interface for a paginated response
 */
export interface TPaginatedResponse<T> {
  items: T[]; // Current page items
  hasNextPage: boolean; // Whether there are more pages
  getNextPage: () => Promise<TPaginatedResponse<T>>; // Function to get the next page
  getAllPages: () => Promise<T[]>; // Function to get all remaining pages and combine
  response: ICoreResponse<any>; // Original response
}