jezweb-mcp-core/dist/shared/core/pagination-utils.d.ts

Jezweb Model Context Protocol (MCP) Core - A universal server for providing AI tools and resources, designed for seamless integration with various AI models and clients. Features adaptable multi-provider support, comprehensive tool and resource management

/**
 * Pagination Utilities - Cursor-based pagination helpers for MCP compliance
 *
 * This module provides utilities for implementing cursor-based pagination
 * across all MCP list methods (tools/list, resources/list, prompts/list).
 *
 * Features:
 * - Base64-encoded cursor generation and parsing
 * - Consistent pagination logic across all endpoints
 * - Edge case handling (invalid cursors, end of results)
 * - Type-safe pagination interfaces
 */
/**
 * Pagination cursor structure
 */
export interface PaginationCursor {
    /** Index position in the array */
    index: number;
    /** Total count of items (for validation) */
    total: number;
    /** Timestamp when cursor was created */
    timestamp: number;
}
/**
 * Pagination request parameters
 */
export interface PaginationParams {
    /** Cursor for pagination position */
    cursor?: string;
    /** Maximum number of items to return */
    limit?: number;
}
/**
 * Pagination result
 */
export interface PaginationResult<T> {
    /** Items for current page */
    items: T[];
    /** Next cursor if more results available */
    nextCursor?: string;
    /** Total count of items */
    total: number;
    /** Whether there are more results */
    hasMore: boolean;
}
/**
 * Default pagination settings
 */
export declare const PAGINATION_DEFAULTS: {
    /** Default page size */
    readonly DEFAULT_LIMIT: 1000;
    /** Maximum page size */
    readonly MAX_LIMIT: 1000;
    /** Minimum page size */
    readonly MIN_LIMIT: 1;
    /** Cursor expiration time (1 hour) */
    readonly CURSOR_EXPIRY_MS: number;
};
/**
 * Encode pagination cursor to base64 string
 */
export declare function encodeCursor(cursor: PaginationCursor): string;
/**
 * Decode pagination cursor from base64 string
 */
export declare function decodeCursor(cursorString: string): PaginationCursor;
/**
 * Validate pagination parameters
 */
export declare function validatePaginationParams(params: PaginationParams): {
    limit: number;
    startIndex: number;
};
/**
 * Paginate an array of items
 */
export declare function paginateArray<T>(items: T[], params: PaginationParams): PaginationResult<T>;
/**
 * Create pagination metadata for logging/debugging
 */
export declare function createPaginationMetadata(params: PaginationParams, result: PaginationResult<any>): Record<string, any>;
/**
 * Helper to create first page cursor for a collection
 */
export declare function createFirstPageCursor(total: number): string;
/**
 * Helper to check if pagination is needed for a collection
 */
export declare function isPaginationNeeded(totalItems: number, limit?: number): boolean;
/**
 * Helper to get pagination summary for logging
 */
export declare function getPaginationSummary<T>(params: PaginationParams, result: PaginationResult<T>): string;
//# sourceMappingURL=pagination-utils.d.ts.map