@sschepis/magazine 0.1.0

package/src/components/Paginator.js

@@ -0,0 +1,343 @@
+/**
+ * Paginator - Efficient pagination for large event datasets
+ */
+export default class Paginator {
+    constructor(logger) {
+        this.logger = logger.child({ context: 'Paginator' });
+        this.logger.info('Paginator initialized');
+    }
+
+    /**
+     * Create a paginated result set
+     * @param {Array} items - Items to paginate
+     * @param {Object} options - Pagination options
+     * @param {number} options.page - Current page (1-based)
+     * @param {number} options.pageSize - Items per page
+     * @param {boolean} options.includeMeta - Include pagination metadata
+     * @returns {Object} Paginated result
+     */
+    paginate(items, options = {}) {
+        const {
+            page = 1,
+            pageSize = 100,
+            includeMeta = true
+        } = options;
+
+        // Validate inputs
+        if (!Array.isArray(items)) {
+            this.logger.warn('Invalid items array provided to paginate');
+            return this._createEmptyResult(includeMeta);
+        }
+
+        if (page < 1 || pageSize < 1) {
+            this.logger.warn('Invalid pagination parameters', { page, pageSize });
+            return this._createEmptyResult(includeMeta);
+        }
+
+        const totalItems = items.length;
+        const totalPages = Math.ceil(totalItems / pageSize);
+        const startIndex = (page - 1) * pageSize;
+        const endIndex = Math.min(startIndex + pageSize, totalItems);
+
+        // Get page items
+        const pageItems = items.slice(startIndex, endIndex);
+
+        this.logger.debug('Created paginated result', {
+            page,
+            pageSize,
+            totalItems,
+            totalPages,
+            itemsInPage: pageItems.length
+        });
+
+        // Build result
+        const result = {
+            data: pageItems
+        };
+
+        if (includeMeta) {
+            result.meta = {
+                page,
+                pageSize,
+                totalItems,
+                totalPages,
+                hasNextPage: page < totalPages,
+                hasPreviousPage: page > 1,
+                startIndex: startIndex + 1, // 1-based for display
+                endIndex: endIndex
+            };
+        }
+
+        return result;
+    }
+
+    /**
+     * Create an async iterator for large datasets
+     * @param {Array|Function} itemsOrGetter - Items array or async function to get items
+     * @param {Object} options - Iterator options
+     * @param {number} options.pageSize - Items per page
+     * @returns {AsyncIterator} Async iterator
+     */
+    async *iterate(itemsOrGetter, options = {}) {
+        const { pageSize = 100 } = options;
+        let page = 1;
+        let hasMore = true;
+
+        while (hasMore) {
+            let items;
+
+            // Handle both array and async getter function
+            if (typeof itemsOrGetter === 'function') {
+                items = await itemsOrGetter(page, pageSize);
+            } else if (Array.isArray(itemsOrGetter)) {
+                const result = this.paginate(itemsOrGetter, { page, pageSize, includeMeta: true });
+                items = result.data;
+                hasMore = result.meta.hasNextPage;
+            } else {
+                this.logger.error('Invalid itemsOrGetter provided to iterate');
+                return;
+            }
+
+            if (!items || items.length === 0) {
+                hasMore = false;
+                break;
+            }
+
+            // Yield each item
+            for (const item of items) {
+                yield item;
+            }
+
+            // If using array, check if we have more pages
+            if (Array.isArray(itemsOrGetter)) {
+                page++;
+            } else {
+                // For async getter, assume no more items if less than pageSize returned
+                hasMore = items.length === pageSize;
+                page++;
+            }
+        }
+
+        this.logger.debug('Iterator completed', { totalPages: page - 1 });
+    }
+
+    /**
+     * Create a cursor-based pagination result
+     * @param {Array} items - Items to paginate
+     * @param {Object} options - Cursor pagination options
+     * @param {string} options.cursor - Current cursor position
+     * @param {number} options.limit - Number of items to return
+     * @param {string} options.cursorField - Field to use for cursor (default: 'id')
+     * @param {string} options.direction - Pagination direction ('forward' or 'backward')
+     * @returns {Object} Cursor-paginated result
+     */
+    paginateCursor(items, options = {}) {
+        const {
+            cursor = null,
+            limit = 100,
+            cursorField = 'id',
+            direction = 'forward'
+        } = options;
+
+        if (!Array.isArray(items)) {
+            this.logger.warn('Invalid items array provided to paginateCursor');
+            return this._createEmptyCursorResult();
+        }
+
+        let filteredItems = [...items];
+
+        // Apply cursor filter
+        if (cursor !== null) {
+            filteredItems = filteredItems.filter(item => {
+                const itemValue = item[cursorField];
+                if (direction === 'forward') {
+                    return itemValue > cursor;
+                } else {
+                    return itemValue < cursor;
+                }
+            });
+        }
+
+        // Sort items based on direction
+        filteredItems.sort((a, b) => {
+            const aVal = a[cursorField];
+            const bVal = b[cursorField];
+            if (direction === 'forward') {
+                return aVal < bVal ? -1 : 1;
+            } else {
+                return aVal > bVal ? -1 : 1;
+            }
+        });
+
+        // Get limited items
+        const pageItems = filteredItems.slice(0, limit);
+        const hasMore = filteredItems.length > limit;
+
+        // Determine cursors
+        const firstItem = pageItems[0];
+        const lastItem = pageItems[pageItems.length - 1];
+
+        const result = {
+            data: pageItems,
+            cursors: {
+                before: firstItem ? firstItem[cursorField] : null,
+                after: lastItem ? lastItem[cursorField] : null,
+                hasNext: hasMore,
+                hasPrevious: cursor !== null
+            }
+        };
+
+        this.logger.debug('Created cursor-paginated result', {
+            cursor,
+            limit,
+            cursorField,
+            direction,
+            itemsReturned: pageItems.length,
+            hasMore
+        });
+
+        return result;
+    }
+
+    /**
+     * Create a page info object for GraphQL-style pagination
+     * @param {Object} paginationMeta - Pagination metadata
+     * @returns {Object} Page info
+     */
+    createPageInfo(paginationMeta) {
+        return {
+            hasNextPage: paginationMeta.hasNextPage || false,
+            hasPreviousPage: paginationMeta.hasPreviousPage || false,
+            startCursor: paginationMeta.startCursor || null,
+            endCursor: paginationMeta.endCursor || null,
+            totalCount: paginationMeta.totalItems || 0
+        };
+    }
+
+    /**
+     * Calculate optimal page size based on data characteristics
+     * @param {Object} options - Options for calculation
+     * @param {number} options.totalItems - Total number of items
+     * @param {number} options.avgItemSize - Average item size in bytes
+     * @param {number} options.maxMemory - Maximum memory to use (bytes)
+     * @param {number} options.minPageSize - Minimum page size
+     * @param {number} options.maxPageSize - Maximum page size
+     * @returns {number} Optimal page size
+     */
+    calculateOptimalPageSize(options = {}) {
+        const {
+            totalItems = 1000,
+            avgItemSize = 1024, // 1KB default
+            maxMemory = 10 * 1024 * 1024, // 10MB default
+            minPageSize = 10,
+            maxPageSize = 1000
+        } = options;
+
+        // Calculate based on memory constraints
+        let optimalSize = Math.floor(maxMemory / avgItemSize);
+
+        // Apply bounds
+        optimalSize = Math.max(minPageSize, Math.min(maxPageSize, optimalSize));
+
+        // Adjust for total items
+        if (totalItems < optimalSize) {
+            optimalSize = totalItems;
+        }
+
+        this.logger.debug('Calculated optimal page size', {
+            totalItems,
+            avgItemSize,
+            maxMemory,
+            optimalSize
+        });
+
+        return optimalSize;
+    }
+
+    /**
+     * Create empty result for error cases
+     * @private
+     */
+    _createEmptyResult(includeMeta) {
+        const result = { data: [] };
+        if (includeMeta) {
+            result.meta = {
+                page: 1,
+                pageSize: 0,
+                totalItems: 0,
+                totalPages: 0,
+                hasNextPage: false,
+                hasPreviousPage: false,
+                startIndex: 0,
+                endIndex: 0
+            };
+        }
+        return result;
+    }
+
+    /**
+     * Create empty cursor result for error cases
+     * @private
+     */
+    _createEmptyCursorResult() {
+        return {
+            data: [],
+            cursors: {
+                before: null,
+                after: null,
+                hasNext: false,
+                hasPrevious: false
+            }
+        };
+    }
+}
+
+/**
+ * PaginationHelper - Static utility methods for pagination
+ */
+export class PaginationHelper {
+    /**
+     * Calculate pagination offset
+     */
+    static calculateOffset(page, pageSize) {
+        return (page - 1) * pageSize;
+    }
+
+    /**
+     * Calculate total pages
+     */
+    static calculateTotalPages(totalItems, pageSize) {
+        return Math.ceil(totalItems / pageSize);
+    }
+
+    /**
+     * Validate page number
+     */
+    static isValidPage(page, totalPages) {
+        return page >= 1 && page <= totalPages;
+    }
+
+    /**
+     * Get page numbers for pagination UI
+     */
+    static getPageNumbers(currentPage, totalPages, maxVisible = 5) {
+        const pages = [];
+        const halfVisible = Math.floor(maxVisible / 2);
+        
+        let start = Math.max(1, currentPage - halfVisible);
+        let end = Math.min(totalPages, currentPage + halfVisible);
+        
+        // Adjust if we're near the beginning or end
+        if (currentPage <= halfVisible) {
+            end = Math.min(totalPages, maxVisible);
+        } else if (currentPage >= totalPages - halfVisible) {
+            start = Math.max(1, totalPages - maxVisible + 1);
+        }
+        
+        for (let i = start; i <= end; i++) {
+            pages.push(i);
+        }
+        
+        return pages;
+    }
+}