@dollhousemcp/mcp-server/dist/services/query/PaginationService.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * PaginationService - Element-agnostic pagination service
 *
 * Provides consistent pagination behavior across all element types following
 * the patterns established in CollectionSearch.ts.
 *
 * Key Features:
 * - 1-indexed pages (page 1 = first page)
 * - Configurable page size with sensible defaults
 * - Complete pagination metadata for UI/API responses
 * - Input validation and security logging
 * - Stateless and injectable via DI
 *
 * Security:
 * - Validates all inputs to prevent DoS attacks
 * - Logs validation failures via SecurityMonitor
 * - Enforces maximum page size limits
 *
 * @see src/types/query/types.ts for interface definitions
 * @see src/collection/CollectionSearch.ts for pagination patterns
 */
import { IPaginationService, PaginationOptions, PaginatedResult, PaginationMetadata } from './types.js';
/**
 * Implementation of IPaginationService providing element-agnostic pagination
 *
 * This service is stateless and can be safely shared across multiple consumers.
 * It follows the pagination patterns from CollectionSearch.ts:
 * - 1-indexed pages
 * - Default pageSize of 25
 * - Maximum pageSize of 100
 * - Accurate hasNextPage/hasPrevPage calculations
 *
 * @template T - Type of items being paginated (can be any type)
 *
 * @example
 * ```typescript
 * const service = new PaginationService();
 * const result = service.paginate(items, { page: 2, pageSize: 10 });
 * console.log(result.items); // items 11-20
 * console.log(result.pagination.hasNextPage); // true if more items exist
 * ```
 */
export declare class PaginationService<T = any> implements IPaginationService<T> {
    /**
     * Paginate an array of items
     *
     * @param items - Complete array of items to paginate
     * @param options - Pagination configuration (page, pageSize)
     * @returns Paginated result with items and metadata
     * @throws {Error} If pagination options are invalid
     *
     * @example
     * ```typescript
     * const service = new PaginationService();
     *
     * // Basic usage with defaults (page 1, pageSize 25)
     * const result1 = service.paginate(items);
     *
     * // Custom page and page size
     * const result2 = service.paginate(items, { page: 3, pageSize: 50 });
     *
     * // Access results
     * console.log(result2.items); // Items 101-150
     * console.log(result2.pagination.totalPages); // Total number of pages
     * console.log(result2.pagination.hasNextPage); // true if page 4 exists
     * ```
     */
    paginate(items: T[], options?: PaginationOptions): PaginatedResult<T>;
    /**
     * Calculate pagination metadata without returning items
     *
     * Useful for API responses where you need metadata but already
     * have the items, or when you need to provide pagination info
     * before fetching the actual data.
     *
     * @param totalItems - Total number of items in full result set
     * @param options - Pagination configuration (page, pageSize)
     * @returns Pagination metadata only
     * @throws {Error} If pagination options are invalid
     *
     * @example
     * ```typescript
     * const service = new PaginationService();
     *
     * // Calculate metadata for a known total count
     * const metadata = service.calculateMetadata(237, { page: 5, pageSize: 25 });
     * console.log(metadata.totalPages); // 10
     * console.log(metadata.hasNextPage); // true (pages 6-10 exist)
     * console.log(metadata.hasPrevPage); // true (pages 1-4 exist)
     * ```
     */
    calculateMetadata(totalItems: number, options?: PaginationOptions): PaginationMetadata;
    /**
     * Validate pagination options
     *
     * Ensures that page and pageSize values are within acceptable ranges
     * to prevent DoS attacks and invalid pagination states.
     *
     * Security considerations:
     * - Page must be >= 1 (1-indexed)
     * - PageSize must be >= 1
     * - PageSize must be <= MAX_PAGE_SIZE (prevents memory exhaustion)
     *
     * @param page - Page number to validate
     * @param pageSize - Page size to validate
     * @throws {Error} If validation fails
     *
     * @private
     */
    private validatePaginationOptions;
}
/**
 * Factory function to create a new PaginationService instance
 *
 * Useful for dependency injection scenarios where you want to ensure
 * a fresh instance per consumer.
 *
 * @template T - Type of items being paginated
 * @returns New PaginationService instance
 *
 * @example
 * ```typescript
 * const paginationService = createPaginationService<MyElementType>();
 * const result = paginationService.paginate(items, { page: 1, pageSize: 25 });
 * ```
 */
export declare function createPaginationService<T = any>(): IPaginationService<T>;
/**
 * Singleton instance for convenience
 *
 * Use this when you don't need DI or when sharing a single instance
 * across the application is acceptable. Since the service is stateless,
 * sharing is safe.
 *
 * @example
 * ```typescript
 * import { paginationService } from './PaginationService.js';
 *
 * const result = paginationService.paginate(items, { page: 2, pageSize: 50 });
 * ```
 */
export declare const paginationService: PaginationService<any>;
//# sourceMappingURL=PaginationService.d.ts.map