ts-client-lib 0.0.7

package/utils/TSPagination.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Pagination – shared source of truth for cursor-based pagination.
+ * Use on server (Node) and client (React, Angular, etc.) for consistent types and helpers.
+ * No framework or DB dependencies; pure TypeScript.
+ *
+ * Cursor pagination is O(1) per request (no offset). Navigation uses first/after (forward)
+ * or last/before (backward). "Last page" is requested with last=N and no before.
+ */
+/** Cursor pagination request state (first/after or last/before). */
+export interface CursorPaginationState {
+    first?: number;
+    after?: string;
+    last?: number;
+    before?: string;
+}
+/** Page info returned by the server after a paginated query. */
+export interface CursorPageInfo {
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+}
+/** Connection response shape: nodes + totalCount + pageInfo. */
+export interface CursorConnection<T> {
+    nodes: T[];
+    totalCount: number;
+    pageInfo: CursorPageInfo;
+}
+export declare const DEFAULT_PAGE_SIZE = 25;
+export declare const MAX_PAGE_SIZE = 100;
+/**
+ * Clamp page size to [1, max]. Use when building API inputs.
+ */
+export declare function clampPageSize(size: number, max?: number): number;
+/**
+ * 1-based current page number from rangeStart and page size.
+ * rangeStart: 1-based index of the first item on the current page.
+ */
+export declare function getCurrentPage(rangeStart: number, pageSize: number): number;
+/**
+ * Total number of pages for a given total count and page size.
+ * Use for "Page X of Y" and to disable "Last" when on last page.
+ */
+export declare function getTotalPages(totalCount: number, pageSize: number): number;
+/**
+ * Range start (1-based) for the last page, given total count and number of nodes on that page.
+ * Call this after loading the last page (request with last=N, no before) and set rangeStart
+ * so "Showing X – Y of Z" is correct.
+ */
+export declare function getLastPageRangeStart(totalCount: number, nodesLength: number): number;
+/**
+ * True when the request was for the last page (last=N, no before).
+ * Use to decide whether to set rangeStart from getLastPageRangeStart after the response.
+ * When false, the request may be "previous" (last + before) and rangeStart is already set by the client.
+ */
+export declare function isLastPageRequest(pagination: CursorPaginationState): boolean;
+/**
+ * Single source of truth: returns the rangeStart to set after a paginated response, or null.
+ * Use in one place after every cursor-paginated load: if (v != null) setRangeStart(v).
+ * Encodes "when" (only for last-page request) and "value" (getLastPageRangeStart).
+ */
+export declare function getRangeStartToApplyAfterLoad(pagination: CursorPaginationState, totalCount: number, nodesLength: number): number | null;
+/**
+ * Effective page size from pagination state (first or last, or default).
+ */
+export declare function getPageSize(pagination: CursorPaginationState, defaultSize?: number): number;
+/**
+ * Range start after "Next": current + pageSize.
+ * Use in pagination lib only; hook passes (prev, pageSize).
+ */
+export declare function getRangeStartAfterNext(currentRangeStart: number, pageSize: number): number;
+/**
+ * Range start after "Previous": go back one page, not below 1.
+ * Use in pagination lib only; hook passes (prev, pageSize).
+ */
+export declare function getRangeStartAfterPrevious(currentRangeStart: number, pageSize: number): number;
+/**
+ * Clamp value for setRangeStart: use value if >= 1, else keep current (avoid 0 or negative).
+ * Use when applying last-page range or external fixes.
+ */
+export declare function clampRangeStartForSet(value: number, currentRangeStart: number): number;
+/**
+ * True when the "Last" button should be disabled (on last page or no data).
+ * Pass hasNextPage from server when available so Last disables even if rangeStart lags.
+ */
+export declare function isLastPageDisabled(totalCount: number, currentPage: number, pageSize: number, hasNextPage?: boolean): boolean;
+/**
+ * Segment for page-number strip: First | Prev | 1 ... 59 [60] 61 ... 100 | Next | Last.
+ * Only first/previous/next/last are O(1) with cursor; page numbers are clickable only when they map to one of those.
+ */
+export type PageStripAction = 'first' | 'previous' | 'next' | 'last';
+export type PageStripSegment = {
+    type: 'number';
+    page: number;
+    action: PageStripAction | null;
+} | {
+    type: 'ellipsis';
+};
+/** Options for getPageNumberStrip: how many page numbers at start, around current (middle), and end. */
+export interface PageStripOptions {
+    /** Pages at start (default 1). E.g. 1 => show page 1. */
+    start?: number;
+    /**
+     * Middle: when start=0 and end=0, this is the **total** count (e.g. 3 => show only current-1, current, current+1).
+     * Otherwise it's the radius (pages on each side). E.g. 1 => show current-1, current, current+1.
+     */
+    middle?: number;
+    /** Pages at end (default 1). E.g. 1 => show last page. */
+    end?: number;
+}
+/**
+ * Build page strip segments for cursor-safe UI: 1 ... current-1 [current] current+1 ... totalPages.
+ * Only segments with action first/previous/next/last are clickable (one O(1) request each).
+ * No duplicate page numbers (e.g. when on page 2 you get 1 2 3 ... not 1 1 2 3).
+ */
+export declare function getPageNumberStrip(currentPage: number, totalPages: number, options?: PageStripOptions): PageStripSegment[];
+/**
+ * Format range as wordless numeric string for i18n: "X – Y / Z" or "0 / Z".
+ * Append optional itemLabel so the only translatable part is the label.
+ * Example: "1 – 25 / 100" or "1 – 25 / 100 users".
+ */
+export declare function formatShowingRange(rangeStart: number, nodesLength: number, totalCount: number, itemLabel?: string): string;
+/** Which parts of the pagination bar to show. Omitted or true = show, false = hide. strip can be options (e.g. start:0 middle:3 end:0). */
+export interface BarLayout {
+    first?: boolean;
+    previous?: boolean;
+    /** true = default strip, or PageStripOptions (e.g. { start: 0, middle: 3, end: 0 }), false = hide */
+    strip?: boolean | PageStripOptions;
+    next?: boolean;
+    last?: boolean;
+}
+/** Presets for common bar layouts. Single source of truth for app and any other consumer. */
+export declare const BAR_PRESETS: Record<string, BarLayout>;
+export type BarPresetName = keyof typeof BAR_PRESETS;
+/** Resolve layout from preset name or custom layout. Defaults to full. */
+export declare function resolveBarLayout(preset?: BarPresetName, layout?: BarLayout): BarLayout;
+/** Strip options to pass to getDisplay/getPageNumberStrip from a bar layout and optional prop override. */
+export declare function getBarLayoutStripOptions(barLayout: BarLayout, propStripOptions?: PageStripOptions): PageStripOptions | undefined;
+/** Which parts of the bar are visible. Only explicitly true (or strip as object) = show. */
+export interface BarVisibility {
+    showFirst: boolean;
+    showPrevious: boolean;
+    showStrip: boolean;
+    showNext: boolean;
+    showLast: boolean;
+}
+export declare function getBarVisibility(barLayout: BarLayout): BarVisibility;
+/** Strip segment with computed disabled/isCurrent so bar doesn't duplicate logic. */
+export type BarStripSegment = {
+    type: 'ellipsis';
+} | {
+    type: 'number';
+    page: number;
+    action: PageStripAction | null;
+    disabled: boolean;
+    isCurrent: boolean;
+};
+/** Input to compute bar control state (display already has currentPage, totalPages, pageStrip). */
+export interface BarStateInput {
+    display: PaginationDisplay;
+    pageInfo: CursorPageInfo;
+    loading: boolean;
+    isLastDisabled: boolean;
+}
+/** First/Previous/Next/Last button state. */
+export interface BarButtonState {
+    disabled: boolean;
+}
+/** Full bar state: visibility + disabled for each control + strip segments with disabled/isCurrent. */
+export interface BarState {
+    visibility: BarVisibility;
+    first: BarButtonState;
+    previous: BarButtonState;
+    next: BarButtonState;
+    last: BarButtonState;
+    strip: {
+        visible: boolean;
+        segments: BarStripSegment[];
+    };
+}
+export declare function getBarState(barLayout: BarLayout, input: BarStateInput): BarState;
+/** Input for getDisplay: everything needed to compute UI state. */
+export interface PaginationDisplayInput {
+    rangeStart: number;
+    nodesLength: number;
+    totalCount: number;
+    pageSize: number;
+    /** From server; when false, Last is disabled even if rangeStart lags. */
+    hasNextPage?: boolean;
+    /** Optional label for showing text (e.g. "users"). Wordless if omitted. */
+    itemLabel?: string;
+    /** Optional strip layout: start / middle / end chunk sizes. */
+    stripOptions?: PageStripOptions;
+    /** When provided, used to only treat as last page when the request was last+N (no before). Avoids wrong page after clicking previous. */
+    pagination?: CursorPaginationState;
+}
+/** Everything the pagination UI needs in one object. */
+export interface PaginationDisplay {
+    currentPage: number;
+    totalPages: number;
+    showingText: string;
+    isLastDisabled: boolean;
+    /** Segments for page strip: First | Prev | 1 ... 59 [60] 61 ... 100 | Next | Last (cursor-safe). */
+    pageStrip: PageStripSegment[];
+}
+/** When getDisplay is called with barLayout option, it returns display + barState in one go. */
+export type PaginationDisplayWithBarState = PaginationDisplay & {
+    barState: BarState;
+};
+/** Optional second arg: pass preset/layout (getDisplay resolves) or barLayout; when set, getDisplay also returns barState (plug-and-play). */
+export interface GetDisplayBarOptions {
+    /** Resolved layout; if omitted, resolved from preset/layout below. */
+    barLayout?: BarLayout;
+    preset?: BarPresetName;
+    layout?: BarLayout;
+    loading?: boolean;
+    hasPreviousPage?: boolean;
+}
+/** Build display from input (used by both Orchestra and Function mode). */
+export declare function getDisplayFromInput(input: PaginationDisplayInput): PaginationDisplay;
+/** Add barState to display when options (preset/layout/barLayout) are provided. Use in Orchestra and Function mode. */
+export declare function addBarStateIfRequested(display: PaginationDisplay, options: GetDisplayBarOptions | undefined, hasNextPage?: boolean): PaginationDisplay | PaginationDisplayWithBarState;
+/**
+ * Minimal facade: call a few methods for common flows.
+ * For one-off calculations use the top-level functions (getCurrentPage, formatShowingRange, etc.).
+ *
+ * @example
+ * import { TSPagination } from 'ts-client-lib/utils/TSPagaination';
+ *
+ * // 1) UI: one call for all display values
+ * const display = TSPagination.getDisplay({
+ *   rangeStart, nodesLength: nodes.length, totalCount, pageSize,
+ *   hasNextPage: pageInfo.hasNextPage, itemLabel: 'users'
+ * });
+ * // use display.currentPage, display.showingText, display.isLastDisabled
+ *
+ * // 2) After response: should we update rangeStart?
+ * const rangeStartToApply = TSPagination.getRangeStartAfterResponse(pagination, totalCount, nodes.length);
+ * if (rangeStartToApply != null) setRangeStart(rangeStartToApply);
+ *
+ * // 3) Next/Previous: new rangeStart for a direction
+ * const nextRangeStart = TSPagination.getRangeStartAfterMove('next', rangeStart, pageSize);
+ */
+export declare class TSPagination {
+    /**
+     * One call for display (+ optional barState via addBarStateIfRequested). Uses getDisplayFromInput + addBarStateIfRequested.
+     */
+    static getDisplay(input: PaginationDisplayInput, options?: GetDisplayBarOptions): PaginationDisplay | PaginationDisplayWithBarState;
+    /**
+     * After a paginated response: returns rangeStart to set when the request was "last page", else null.
+     */
+    static getRangeStartAfterResponse(pagination: CursorPaginationState, totalCount: number, nodesLength: number): number | null;
+    /**
+       * New rangeStart after moving one page in a direction (for next or previous).
+       */
+    static getRangeStartAfterMove(direction: 'next' | 'previous', currentRangeStart: number, pageSize: number): number;
+    /** Effective page size from pagination state. Use this so you never need to call getPageSize from the lib. */
+    static getPageSize(pagination: CursorPaginationState, defaultSize?: number): number;
+    /** Clamp value for setRangeStart (use value if >= 1, else keep current). */
+    static clampRangeStartForSet(value: number, currentRangeStart: number): number;
+    /** 1-based current page from rangeStart and page size. */
+    static getCurrentPage(rangeStart: number, pageSize: number): number;
+    /** Total pages for "Page X of Y". */
+    static getTotalPages(totalCount: number, pageSize: number): number;
+    /** Whether the Last button should be disabled. */
+    static isLastDisabled(totalCount: number, currentPage: number, pageSize: number, hasNextPage?: boolean): boolean;
+    /**
+     * Execute a navigation (first | previous | next | last). Use this in Orchestra mode so the
+     * orchestrator owns all behavior; the hook only holds state and calls this.
+     * When going 'previous' from the last page, pass totalCount so we don't use stale rangeStart.
+     */
+    static executeGo(direction: 'first' | 'previous' | 'next' | 'last', state: {
+        pagination: CursorPaginationState;
+        pageInfo: CursorPageInfo;
+        rangeStart: number;
+        /** When on last page and going 'previous', use this to compute correct rangeStart (avoids jump to page-2). */
+        totalCount?: number;
+    }, setters: {
+        setPagination: (p: CursorPaginationState) => void;
+        setRangeStartState: (value: number) => void;
+    }, defaultPageSize: number): void;
+}