ts-client-lib 0.0.7

package/utils/TSPagination.js

@@ -0,0 +1,425 @@
+"use strict";
+/**
+ * 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.
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSPagination = exports.BAR_PRESETS = exports.MAX_PAGE_SIZE = exports.DEFAULT_PAGE_SIZE = void 0;
+exports.clampPageSize = clampPageSize;
+exports.getCurrentPage = getCurrentPage;
+exports.getTotalPages = getTotalPages;
+exports.getLastPageRangeStart = getLastPageRangeStart;
+exports.isLastPageRequest = isLastPageRequest;
+exports.getRangeStartToApplyAfterLoad = getRangeStartToApplyAfterLoad;
+exports.getPageSize = getPageSize;
+exports.getRangeStartAfterNext = getRangeStartAfterNext;
+exports.getRangeStartAfterPrevious = getRangeStartAfterPrevious;
+exports.clampRangeStartForSet = clampRangeStartForSet;
+exports.isLastPageDisabled = isLastPageDisabled;
+exports.getPageNumberStrip = getPageNumberStrip;
+exports.formatShowingRange = formatShowingRange;
+exports.resolveBarLayout = resolveBarLayout;
+exports.getBarLayoutStripOptions = getBarLayoutStripOptions;
+exports.getBarVisibility = getBarVisibility;
+exports.getBarState = getBarState;
+exports.getDisplayFromInput = getDisplayFromInput;
+exports.addBarStateIfRequested = addBarStateIfRequested;
+// ═══════════════════════════════════════════════════════════════════
+// Constants
+// ═══════════════════════════════════════════════════════════════════
+exports.DEFAULT_PAGE_SIZE = 25;
+exports.MAX_PAGE_SIZE = 100;
+// ═══════════════════════════════════════════════════════════════════
+// Helpers (pure functions – same on server and client)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Clamp page size to [1, max]. Use when building API inputs.
+ */
+function clampPageSize(size, max) {
+    if (max === void 0) { max = exports.MAX_PAGE_SIZE; }
+    return Math.min(Math.max(1, Math.floor(size)), max);
+}
+/**
+ * 1-based current page number from rangeStart and page size.
+ * rangeStart: 1-based index of the first item on the current page.
+ */
+function getCurrentPage(rangeStart, pageSize) {
+    if (rangeStart < 1 || pageSize < 1)
+        return 1;
+    return Math.floor((rangeStart - 1) / pageSize) + 1;
+}
+/**
+ * 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.
+ */
+function getTotalPages(totalCount, pageSize) {
+    if (totalCount <= 0 || pageSize < 1)
+        return 0;
+    return Math.ceil(totalCount / pageSize);
+}
+/**
+ * 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.
+ */
+function getLastPageRangeStart(totalCount, nodesLength) {
+    if (totalCount <= 0 || nodesLength <= 0)
+        return 1;
+    return Math.max(1, totalCount - nodesLength + 1);
+}
+/**
+ * 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.
+ */
+function isLastPageRequest(pagination) {
+    return pagination.last != null && pagination.before == null;
+}
+/**
+ * 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).
+ */
+function getRangeStartToApplyAfterLoad(pagination, totalCount, nodesLength) {
+    if (!isLastPageRequest(pagination) || totalCount <= 0 || nodesLength <= 0)
+        return null;
+    return getLastPageRangeStart(totalCount, nodesLength);
+}
+/**
+ * Effective page size from pagination state (first or last, or default).
+ */
+function getPageSize(pagination, defaultSize) {
+    var _a, _b;
+    if (defaultSize === void 0) { defaultSize = exports.DEFAULT_PAGE_SIZE; }
+    return (_b = (_a = pagination.first) !== null && _a !== void 0 ? _a : pagination.last) !== null && _b !== void 0 ? _b : defaultSize;
+}
+/**
+ * Range start after "Next": current + pageSize.
+ * Use in pagination lib only; hook passes (prev, pageSize).
+ */
+function getRangeStartAfterNext(currentRangeStart, pageSize) {
+    return currentRangeStart + pageSize;
+}
+/**
+ * Range start after "Previous": go back one page, not below 1.
+ * Use in pagination lib only; hook passes (prev, pageSize).
+ */
+function getRangeStartAfterPrevious(currentRangeStart, pageSize) {
+    return Math.max(1, currentRangeStart - pageSize);
+}
+/**
+ * Clamp value for setRangeStart: use value if >= 1, else keep current (avoid 0 or negative).
+ * Use when applying last-page range or external fixes.
+ */
+function clampRangeStartForSet(value, currentRangeStart) {
+    return value >= 1 ? value : currentRangeStart;
+}
+/**
+ * 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.
+ */
+function isLastPageDisabled(totalCount, currentPage, pageSize, hasNextPage) {
+    if (totalCount <= 0)
+        return true;
+    if (hasNextPage === false)
+        return true;
+    var totalPages = getTotalPages(totalCount, pageSize);
+    return totalPages <= 0 || currentPage >= totalPages;
+}
+var DEFAULT_STRIP_OPTIONS = { start: 1, middle: 1, end: 1 };
+function actionForPage(p, cur, totalPages) {
+    if (p === cur)
+        return null;
+    if (p === 1)
+        return cur === 1 ? null : 'first';
+    if (p === totalPages)
+        return cur === totalPages ? null : 'last';
+    if (p === cur - 1)
+        return 'previous';
+    if (p === cur + 1)
+        return 'next';
+    return null;
+}
+/**
+ * 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).
+ */
+function getPageNumberStrip(currentPage, totalPages, options) {
+    if (totalPages <= 0)
+        return [];
+    var cur = Math.max(1, Math.min(currentPage, totalPages));
+    var _a = __assign(__assign({}, DEFAULT_STRIP_OPTIONS), options), start = _a.start, middle = _a.middle, end = _a.end;
+    var startPages = Math.min(start, totalPages);
+    var endStart = Math.max(1, totalPages - end + 1);
+    var midLo;
+    var midHi;
+    if (start === 0 && end === 0) {
+        // Only middle chunk: treat middle as total count so we show only that many (e.g. 3 => prev, current, next). No disabled extras.
+        var total = Math.max(1, Math.min(middle, totalPages));
+        var half = Math.floor((total - 1) / 2);
+        midLo = Math.max(1, cur - half);
+        midHi = Math.min(totalPages, midLo + total - 1);
+        midLo = Math.max(1, midHi - total + 1);
+    }
+    else {
+        midLo = Math.max(1, cur - middle);
+        midHi = Math.min(totalPages, cur + middle);
+    }
+    var pageSet = new Set();
+    for (var p = 1; p <= startPages; p++)
+        pageSet.add(p);
+    for (var p = midLo; p <= midHi; p++)
+        pageSet.add(p);
+    for (var p = endStart; p <= totalPages; p++)
+        pageSet.add(p);
+    var sorted = Array.from(pageSet).sort(function (a, b) { return a - b; });
+    var segments = [];
+    var prev = 0;
+    for (var _i = 0, sorted_1 = sorted; _i < sorted_1.length; _i++) {
+        var p = sorted_1[_i];
+        if (prev > 0 && p > prev + 1)
+            segments.push({ type: 'ellipsis' });
+        segments.push({ type: 'number', page: p, action: actionForPage(p, cur, totalPages) });
+        prev = p;
+    }
+    return segments;
+}
+/**
+ * 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".
+ */
+function formatShowingRange(rangeStart, nodesLength, totalCount, itemLabel) {
+    if (itemLabel === void 0) { itemLabel = ''; }
+    var numeric;
+    if (totalCount <= 0)
+        numeric = '0 / 0';
+    else if (nodesLength <= 0)
+        numeric = "0 / ".concat(totalCount);
+    else
+        numeric = "".concat(rangeStart, " \u2013 ").concat(rangeStart + nodesLength - 1, " / ").concat(totalCount);
+    return itemLabel ? "".concat(numeric, " ").concat(itemLabel) : numeric;
+}
+/** Presets for common bar layouts. Single source of truth for app and any other consumer. */
+exports.BAR_PRESETS = {
+    /** First | Previous | 1 … 59 [60] 61 … 100 | Next | Last */
+    full: { first: true, previous: true, strip: true, next: true, last: true },
+    /** Only the page number strip (no First/Previous/Next/Last buttons) */
+    numbersOnly: { strip: true },
+    /** First | 1 … [60] … 100 | Last (no Previous/Next) */
+    firstLastOnly: { first: true, strip: true, last: true },
+    /** First | Previous | Next | Last (no page numbers) */
+    firstPrevNextLast: { first: true, previous: true, next: true, last: true },
+    /** Only middle chunk: e.g. [10] 11 12 — the 3 numbers act as prev/current/next. */
+    middleOnly: { strip: { start: 0, middle: 3, end: 0 } },
+    /** First | [3 numbers] | Last — no Previous/Next; adjacent numbers do prev/next. */
+    fullMiddle3: { first: true, strip: { start: 0, middle: 3, end: 0 }, last: true }
+};
+/** Resolve layout from preset name or custom layout. Defaults to full. */
+function resolveBarLayout(preset, layout) {
+    if (preset != null && exports.BAR_PRESETS[preset])
+        return exports.BAR_PRESETS[preset];
+    if (layout != null)
+        return layout;
+    return exports.BAR_PRESETS.full;
+}
+/** Strip options to pass to getDisplay/getPageNumberStrip from a bar layout and optional prop override. */
+function getBarLayoutStripOptions(barLayout, propStripOptions) {
+    var strip = barLayout.strip;
+    if (strip === false)
+        return undefined;
+    if (typeof strip === 'object' && strip != null)
+        return strip;
+    return propStripOptions;
+}
+function getBarVisibility(barLayout) {
+    return {
+        showFirst: barLayout.first === true,
+        showPrevious: barLayout.previous === true,
+        showStrip: barLayout.strip === true || (typeof barLayout.strip === 'object' && barLayout.strip != null),
+        showNext: barLayout.next === true,
+        showLast: barLayout.last === true
+    };
+}
+function getBarState(barLayout, input) {
+    var visibility = getBarVisibility(barLayout);
+    var display = input.display, pageInfo = input.pageInfo, loading = input.loading, isLastDisabled = input.isLastDisabled;
+    var currentPage = display.currentPage, totalPages = display.totalPages, pageStrip = display.pageStrip;
+    var prevDisabled = (totalPages <= 0 ? !pageInfo.hasPreviousPage : currentPage <= 1) || loading;
+    var nextDisabled = (totalPages <= 0 ? !pageInfo.hasNextPage : currentPage >= totalPages) || loading;
+    var lastDisabled = loading || (totalPages > 0 && currentPage >= totalPages) || isLastDisabled;
+    var segments = pageStrip.map(function (seg) {
+        if (seg.type === 'ellipsis')
+            return { type: 'ellipsis' };
+        var isCurrent = seg.action === null;
+        var disabled = isCurrent || loading;
+        return { type: 'number', page: seg.page, action: seg.action, disabled: disabled, isCurrent: isCurrent };
+    });
+    return {
+        visibility: visibility,
+        first: { disabled: prevDisabled },
+        previous: { disabled: prevDisabled },
+        next: { disabled: nextDisabled },
+        last: { disabled: lastDisabled },
+        strip: { visible: visibility.showStrip, segments: segments }
+    };
+}
+/** Build display from input (used by both Orchestra and Function mode). */
+function getDisplayFromInput(input) {
+    var rangeStart = input.rangeStart, nodesLength = input.nodesLength, totalCount = input.totalCount, pageSize = input.pageSize, hasNextPage = input.hasNextPage, _a = input.itemLabel, itemLabel = _a === void 0 ? '' : _a, stripOptions = input.stripOptions, pagination = input.pagination;
+    var totalPages = getTotalPages(totalCount, pageSize);
+    var computedPage = getCurrentPage(rangeStart, pageSize);
+    var isLastPageReq = pagination ? isLastPageRequest(pagination) : false;
+    var currentPage = totalPages > 0 && hasNextPage === false && isLastPageReq ? totalPages : computedPage;
+    return {
+        currentPage: currentPage,
+        totalPages: totalPages,
+        showingText: formatShowingRange(rangeStart, nodesLength, totalCount, itemLabel),
+        isLastDisabled: isLastPageDisabled(totalCount, currentPage, pageSize, hasNextPage),
+        pageStrip: getPageNumberStrip(currentPage, totalPages, stripOptions)
+    };
+}
+/** Add barState to display when options (preset/layout/barLayout) are provided. Use in Orchestra and Function mode. */
+function addBarStateIfRequested(display, options, hasNextPage) {
+    var _a, _b, _c;
+    var barLayout = (_a = options === null || options === void 0 ? void 0 : options.barLayout) !== null && _a !== void 0 ? _a : ((options === null || options === void 0 ? void 0 : options.preset) != null || (options === null || options === void 0 ? void 0 : options.layout) != null ? resolveBarLayout(options.preset, options.layout) : undefined);
+    if (barLayout != null && options != null) {
+        var pageInfo = {
+            hasNextPage: hasNextPage !== null && hasNextPage !== void 0 ? hasNextPage : false,
+            hasPreviousPage: (_b = options.hasPreviousPage) !== null && _b !== void 0 ? _b : false,
+            startCursor: undefined,
+            endCursor: undefined
+        };
+        var barState = getBarState(barLayout, {
+            display: display,
+            pageInfo: pageInfo,
+            loading: (_c = options.loading) !== null && _c !== void 0 ? _c : false,
+            isLastDisabled: display.isLastDisabled
+        });
+        return __assign(__assign({}, display), { barState: barState });
+    }
+    return display;
+}
+/**
+ * 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);
+ */
+var TSPagination = /** @class */ (function () {
+    function TSPagination() {
+    }
+    /**
+     * One call for display (+ optional barState via addBarStateIfRequested). Uses getDisplayFromInput + addBarStateIfRequested.
+     */
+    TSPagination.getDisplay = function (input, options) {
+        return addBarStateIfRequested(getDisplayFromInput(input), options, input.hasNextPage);
+    };
+    /**
+     * After a paginated response: returns rangeStart to set when the request was "last page", else null.
+     */
+    TSPagination.getRangeStartAfterResponse = function (pagination, totalCount, nodesLength) {
+        return getRangeStartToApplyAfterLoad(pagination, totalCount, nodesLength);
+    };
+    /**
+       * New rangeStart after moving one page in a direction (for next or previous).
+       */
+    TSPagination.getRangeStartAfterMove = function (direction, currentRangeStart, pageSize) {
+        return direction === 'next'
+            ? getRangeStartAfterNext(currentRangeStart, pageSize)
+            : getRangeStartAfterPrevious(currentRangeStart, pageSize);
+    };
+    /** Effective page size from pagination state. Use this so you never need to call getPageSize from the lib. */
+    TSPagination.getPageSize = function (pagination, defaultSize) {
+        if (defaultSize === void 0) { defaultSize = exports.DEFAULT_PAGE_SIZE; }
+        return getPageSize(pagination, defaultSize);
+    };
+    /** Clamp value for setRangeStart (use value if >= 1, else keep current). */
+    TSPagination.clampRangeStartForSet = function (value, currentRangeStart) {
+        return clampRangeStartForSet(value, currentRangeStart);
+    };
+    /** 1-based current page from rangeStart and page size. */
+    TSPagination.getCurrentPage = function (rangeStart, pageSize) {
+        return getCurrentPage(rangeStart, pageSize);
+    };
+    /** Total pages for "Page X of Y". */
+    TSPagination.getTotalPages = function (totalCount, pageSize) {
+        return getTotalPages(totalCount, pageSize);
+    };
+    /** Whether the Last button should be disabled. */
+    TSPagination.isLastDisabled = function (totalCount, currentPage, pageSize, hasNextPage) {
+        return isLastPageDisabled(totalCount, currentPage, pageSize, hasNextPage);
+    };
+    /**
+     * 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.
+     */
+    TSPagination.executeGo = function (direction, state, setters, defaultPageSize) {
+        var pagination = state.pagination, pageInfo = state.pageInfo, rangeStart = state.rangeStart, totalCount = state.totalCount;
+        var pageSize = getPageSize(pagination, defaultPageSize);
+        switch (direction) {
+            case 'first':
+                setters.setPagination({ first: defaultPageSize });
+                setters.setRangeStartState(1);
+                break;
+            case 'last':
+                setters.setPagination({ last: pageSize });
+                break;
+            case 'next':
+                if (pageInfo.hasNextPage && pageInfo.endCursor) {
+                    setters.setPagination({ first: pageSize, after: pageInfo.endCursor });
+                    setters.setRangeStartState(getRangeStartAfterNext(rangeStart, pageSize));
+                }
+                break;
+            case 'previous':
+                if (pageInfo.hasPreviousPage && pageInfo.startCursor) {
+                    setters.setPagination({ last: pageSize, before: pageInfo.startCursor });
+                    var newRangeStart = void 0;
+                    if (pageInfo.hasNextPage === false && totalCount != null && totalCount > 0) {
+                        // On last page; rangeStart may be stale. Use totalCount so we land on (totalPages - 1).
+                        var totalPages = getTotalPages(totalCount, pageSize);
+                        newRangeStart = Math.max(1, (totalPages - 2) * pageSize + 1);
+                    }
+                    else {
+                        newRangeStart = getRangeStartAfterPrevious(rangeStart, pageSize);
+                    }
+                    setters.setRangeStartState(newRangeStart);
+                }
+                break;
+        }
+    };
+    return TSPagination;
+}());
+exports.TSPagination = TSPagination;

package/utils/TSPaginationMulti.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Multi-feed cursor pagination — client-side emulation of legacy paginateMulti.
+ *
+ * Each feed keeps its own PGN-1 cursor; this module k-way merges by a shared sort field.
+ * Use for "All orders" / recent-activity views. Per-product tabs should use TSPagination alone.
+ *
+ * @see TSPagination.ts — single-feed cursor UI helpers
+ */
+import { TSPagination, type CursorConnection, type CursorPageInfo, type CursorPaginationState } from './TSPagination.js';
+/** Which product feed a merged row came from (e.g. sports_order). */
+export interface MultiFeedNodeMeta {
+    feedKey: string;
+}
+export type MergedFeedNode<T> = T & MultiFeedNodeMeta;
+export interface MergeConnectionsOptions<T extends Record<string, unknown>> {
+    sortField: keyof T & string;
+    sortDir?: 'asc' | 'desc';
+    limit: number;
+}
+export interface MultiFeedSource<T extends Record<string, unknown>> {
+    key: string;
+    fetch: (pagination: CursorPaginationState) => Promise<CursorConnection<T>>;
+    /** Optional normalizer before merge (e.g. map API node → ClientOrderListRow). */
+    mapNode?: (node: T) => T;
+}
+export interface MultiFeedPageResult<T extends Record<string, unknown>> {
+    nodes: Array<MergedFeedNode<T>>;
+    /** Sum when every feed returned a numeric totalCount; otherwise undefined. */
+    totalCount?: number;
+    /** True when more items may exist across any feed buffer or cursor. */
+    hasMore: boolean;
+    feeds: Record<string, {
+        pageInfo: CursorPageInfo;
+        buffered: number;
+    }>;
+}
+/**
+ * Stateless merge — legacy paginateMulti page-1 equivalent.
+ * Parallel responses are merged, sorted, and sliced to `limit`.
+ */
+export declare function mergeConnectionsFirstPage<T extends Record<string, unknown>>(responses: Array<{
+    key: string;
+    connection: CursorConnection<T>;
+}>, opts: MergeConnectionsOptions<T>): MultiFeedPageResult<T>;
+/** Adapt merge result to ConnectionList / GraphQL connection shape. */
+export declare function toMergedCursorConnection<T extends Record<string, unknown>>(result: MultiFeedPageResult<T>): CursorConnection<MergedFeedNode<T>>;
+/**
+ * Maintains per-feed buffers and cursors; fetches the next globally sorted page.
+ */
+export declare class MultiFeedMergePaginator<T extends Record<string, unknown>> {
+    private readonly sources;
+    private readonly pageSize;
+    private readonly sortField;
+    private readonly sortDir;
+    private buffers;
+    private pageIndex;
+    constructor(sources: MultiFeedSource<T>[], pageSize: number, sortField: keyof T & string, sortDir?: 'asc' | 'desc');
+    reset(): void;
+    /** Fetch the next merged page (call reset() before the first page). */
+    fetchNextPage(): Promise<MultiFeedPageResult<T>>;
+    get currentPageIndex(): number;
+    private peekBestHead;
+    private refillBuffersWhereNeeded;
+    private resolveFetchPagination;
+    private fetchMore;
+}
+export declare class TSPaginationMulti {
+    static initialPageInfo(): CursorPageInfo;
+    /** One CursorPaginationState per feed key (tab mode). */
+    static createFeedStates(keys: string[], defaultPageSize?: number): Record<string, CursorPaginationState>;
+    static mergeFirstPage: typeof mergeConnectionsFirstPage;
+    static toCursorConnection: typeof toMergedCursorConnection;
+    static createPaginator<T extends Record<string, unknown>>(sources: MultiFeedSource<T>[], pageSize: number, sortField: keyof T & string, sortDir?: 'asc' | 'desc'): MultiFeedMergePaginator<T>;
+    /** Re-export for merged views that share the same pagination bar helpers. */
+    static getDisplay: typeof TSPagination.getDisplay;
+    static getRangeStartAfterMove: typeof TSPagination.getRangeStartAfterMove;
+}