lazy-render-virtual-scroll 1.5.0 → 1.6.0

package/dist/index.d.ts

@@ -41,6 +41,9 @@ declare class Engine {
     private performanceOptimizer;
     private memoryManager;
     private gpuAccelerator;
+    private batchSizeOptimizer;
+    private requestDeduplicator;
+    private priorityRequestQueue;
     private state;
     private fetchMoreCallback;
     private totalItems;
@@ -384,6 +387,683 @@ declare class GPUAccelerator {
     getRecommendations(): string[];
 }
 
+/**
+ * Batch Size Optimizer
+ * Dynamically adjusts batch size based on scroll speed, network, and performance
+ */
+
+interface BatchConfig {
+    minBatchSize: number;
+    maxBatchSize: number;
+    baseBatchSize: number;
+    scrollSpeedThreshold: number;
+}
+interface BatchMetrics {
+    currentBatchSize: number;
+    scrollSpeed: number;
+    networkQuality: 'excellent' | 'good' | 'poor' | 'offline';
+    performanceScore: number;
+    avgRenderTime: number;
+}
+declare class BatchSizeOptimizer {
+    private config;
+    private networkDetector;
+    private performanceMonitor;
+    private currentBatchSize;
+    private scrollSpeedHistory;
+    private renderTimeHistory;
+    private readonly HISTORY_SIZE;
+    constructor(config?: Partial<BatchConfig>, networkDetector?: NetworkSpeedDetector, performanceMonitor?: DevicePerformanceMonitor);
+    /**
+     * Calculate optimal batch size based on all factors
+     */
+    calculateOptimalBatchSize(scrollSpeed: number): Promise<number>;
+    /**
+     * Calculate multiplier based on scroll speed
+     */
+    private calculateSpeedMultiplier;
+    /**
+     * Calculate multiplier based on network quality
+     */
+    private calculateNetworkMultiplier;
+    /**
+     * Calculate multiplier based on device performance
+     */
+    private calculatePerformanceMultiplier;
+    /**
+     * Track scroll speed for averaging
+     */
+    private trackScrollSpeed;
+    /**
+     * Get average scroll speed
+     */
+    private getAverageScrollSpeed;
+    /**
+     * Track render time for performance monitoring
+     */
+    trackRenderTime(renderTime: number): void;
+    /**
+     * Get average render time
+     */
+    getAverageRenderTime(): number;
+    /**
+     * Get current batch metrics
+     */
+    getMetrics(): BatchMetrics;
+    /**
+     * Get current batch size
+     */
+    getCurrentBatchSize(): number;
+    /**
+     * Reset optimizer
+     */
+    reset(): void;
+    /**
+     * Get optimization statistics
+     */
+    getStats(): {
+        avgScrollSpeed: number;
+        avgRenderTime: number;
+        currentBatchSize: number;
+        totalAdjustments: number;
+    };
+}
+
+/**
+ * Request Deduplication
+ * Prevents duplicate requests from being sent
+ */
+declare class RequestDeduplicator {
+    private pendingRequests;
+    private requestCount;
+    /**
+     * Execute request with deduplication
+     * If same request is already pending, return existing promise
+     */
+    request<T>(key: string, requestFn: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Clear specific request
+     */
+    clear(key: string): void;
+    /**
+     * Clear all requests
+     */
+    clearAll(): void;
+    /**
+     * Get pending request count
+     */
+    getPendingCount(): number;
+    /**
+     * Get request statistics
+     */
+    getStats(): {
+        pending: number;
+        totalRequests: number;
+        deduplicationRate: number;
+    };
+}
+
+/**
+ * Priority-based Request Queue
+ * Processes high-priority requests first
+ */
+declare enum Priority {
+    LOW = 0,
+    NORMAL = 1,
+    HIGH = 2,
+    CRITICAL = 3
+}
+declare class PriorityRequestQueue {
+    private queues;
+    private processing;
+    private maxConcurrent;
+    private activeRequests;
+    constructor(maxConcurrent?: number);
+    /**
+     * Add request with priority
+     */
+    add<T>(requestFn: () => Promise<T>, priority?: Priority): Promise<T>;
+    /**
+     * Process queue by priority
+     */
+    private processQueue;
+    /**
+     * Get next request by priority
+     */
+    private getNextRequest;
+    /**
+     * Check if there are pending requests
+     */
+    private hasPendingRequests;
+    /**
+     * Get queue statistics
+     */
+    getStats(): {
+        totalPending: number;
+        byPriority: {
+            critical: number;
+            high: number;
+            normal: number;
+            low: number;
+        };
+        activeRequests: number;
+    };
+    /**
+     * Clear all queues
+     */
+    clear(): void;
+    /**
+     * Clear specific priority queue
+     */
+    clearPriority(priority: Priority): void;
+}
+
+interface HeightCacheStats {
+    totalItems: number;
+    measuredItems: number;
+    estimatedItems: number;
+    cacheSize: number;
+    hitRate: number;
+}
+declare class HeightMeasurementCache {
+    private heightMap;
+    private offsetMap;
+    private estimatedHeight;
+    private totalHeight;
+    private accessCount;
+    private hitCount;
+    private readonly DEFAULT_TTL;
+    constructor(estimatedHeight?: number);
+    /**
+     * Measure and cache height for an item
+     */
+    measureHeight(index: number, element: HTMLElement): number;
+    /**
+     * Get height for an item (measured or estimated)
+     */
+    getHeight(index: number): number;
+    /**
+     * Get offset (cumulative height) for an item
+     */
+    getOffset(index: number): number;
+    /**
+     * Check if item height is measured
+     */
+    isMeasured(index: number): boolean;
+    /**
+     * Mark item as needing remeasurement
+     */
+    invalidate(index: number): void;
+    /**
+     * Clear specific item from cache
+     */
+    clear(index: number): void;
+    /**
+     * Clear entire cache
+     */
+    clearAll(): void;
+    /**
+     * Recalculate all offsets
+     */
+    private recalculateOffsets;
+    /**
+     * Get total height of all items
+     */
+    getTotalHeight(totalItems: number): number;
+    /**
+     * Find item index at a specific scroll position
+     */
+    findIndexAtPosition(position: number, totalItems: number): number;
+    /**
+     * Get cache statistics
+     */
+    getStats(totalItems: number): HeightCacheStats;
+    /**
+     * Update estimated height
+     */
+    updateEstimatedHeight(height: number): void;
+    /**
+     * Get estimated height
+     */
+    getEstimatedHeight(): number;
+    /**
+     * Cleanup old entries (older than TTL)
+     */
+    cleanup(ttl?: number): void;
+    /**
+     * Get all measured heights
+     */
+    getAllHeights(): Map<number, number>;
+    /**
+     * Set heights in bulk (for initial data load)
+     */
+    setHeightsBulk(heights: Map<number, number>): void;
+}
+
+interface VariableHeightConfig {
+    estimatedHeight: number;
+    minHeight: number;
+    maxHeight: number;
+    bufferSize: number;
+}
+interface ItemPosition {
+    index: number;
+    offset: number;
+    height: number;
+}
+declare class VariableHeightManager {
+    private heightCache;
+    private config;
+    private totalItems;
+    private lastMeasuredIndex;
+    constructor(config?: Partial<VariableHeightConfig>);
+    /**
+     * Set total number of items
+     */
+    setTotalItems(total: number): void;
+    /**
+     * Measure item height from DOM element
+     */
+    measureElement(index: number, element: HTMLElement | null): number;
+    /**
+     * Get item position (offset and height)
+     */
+    getItemPosition(index: number): ItemPosition;
+    /**
+     * Calculate visible range for variable heights
+     */
+    calculateVisibleRange(scrollTop: number, viewportHeight: number): VisibleRange;
+    /**
+     * Get total height of all items
+     */
+    getTotalHeight(): number;
+    /**
+     * Scroll to specific item index
+     */
+    scrollToIndex(index: number): number;
+    /**
+     * Get items to render for current viewport
+     */
+    getItemsToRender(scrollTop: number, viewportHeight: number): {
+        items: ItemPosition[];
+        totalHeight: number;
+    };
+    /**
+     * Handle height change (when item height changes dynamically)
+     */
+    onHeightChange(index: number, newHeight: number): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): HeightCacheStats;
+    /**
+     * Clear cache for specific range
+     */
+    clearRange(startIndex: number, endIndex: number): void;
+    /**
+     * Clear entire cache
+     */
+    clearCache(): void;
+    /**
+     * Get last measured index
+     */
+    getLastMeasuredIndex(): number;
+    /**
+     * Check if item is measured
+     */
+    isItemMeasured(index: number): boolean;
+    /**
+     * Get measured items count
+     */
+    getMeasuredCount(): number;
+}
+
+interface DynamicHeightConfig extends EngineConfig {
+    estimatedItemHeight: number;
+    minItemHeight: number;
+    maxItemHeight: number;
+    heightBufferSize: number;
+}
+interface DynamicHeightState extends EngineState {
+    totalContentHeight: number;
+    measuredItems: number;
+    estimatedItems: number;
+}
+declare class DynamicHeightEngine {
+    private config;
+    private variableHeightManager;
+    private heightCache;
+    private state;
+    private containerElement;
+    private itemElements;
+    constructor(config?: Partial<DynamicHeightConfig>);
+    /**
+     * Initialize with container element
+     */
+    init(container: HTMLElement): void;
+    /**
+     * Setup scroll listener
+     */
+    private setupScrollListener;
+    /**
+     * Handle scroll event
+     */
+    private onScroll;
+    /**
+     * Update visible range based on scroll position
+     */
+    private updateVisibleRange;
+    /**
+     * Measure item height from DOM element
+     */
+    measureItem(index: number, element: HTMLElement): number;
+    /**
+     * Called when item height is measured
+     */
+    private onHeightMeasured;
+    /**
+     * Get items to render for current viewport
+     */
+    getItemsToRender(): {
+        items: Array<{
+            index: number;
+            offset: number;
+            height: number;
+        }>;
+        totalHeight: number;
+        visibleRange: VisibleRange;
+    };
+    /**
+     * Scroll to specific item index
+     */
+    scrollToIndex(index: number): void;
+    /**
+     * Set total number of items
+     */
+    setTotalItems(total: number): void;
+    /**
+     * Get current state
+     */
+    getState(): DynamicHeightState;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): HeightCacheStats;
+    /**
+     * Clear cache for range
+     */
+    clearCacheRange(startIndex: number, endIndex: number): void;
+    /**
+     * Clear entire cache
+     */
+    clearCache(): void;
+    /**
+     * Cleanup
+     */
+    cleanup(): void;
+    /**
+     * Update viewport height
+     */
+    updateViewportHeight(height: number): void;
+    /**
+     * Get item offset for styling
+     */
+    getItemOffset(index: number): number;
+    /**
+     * Get item height
+     */
+    getItemHeight(index: number): number;
+    /**
+     * Check if item is measured
+     */
+    isItemMeasured(index: number): boolean;
+}
+
+/**
+ * Smart Prefetch Algorithm
+ * Recognizes scroll patterns and predicts data loading needs
+ */
+interface ScrollPattern {
+    type: 'fast-scroll' | 'slow-scroll' | 'paused' | 'oscillating' | 'steady';
+    velocity: number;
+    acceleration: number;
+    direction: 'up' | 'down' | 'stationary';
+    confidence: number;
+}
+interface PrefetchPrediction {
+    shouldPrefetch: boolean;
+    prefetchDistance: number;
+    batchSize: number;
+    priority: 'low' | 'normal' | 'high' | 'critical';
+    confidence: number;
+}
+declare class SmartPrefetchAlgorithm {
+    private velocityHistory;
+    private directionHistory;
+    private readonly HISTORY_SIZE;
+    private lastPrefetchTime;
+    private prefetchCooldown;
+    /**
+     * Analyze scroll pattern
+     */
+    analyzeScrollPattern(velocity: number, acceleration: number, direction: 'up' | 'down' | 'stationary'): ScrollPattern;
+    /**
+     * Predict prefetch needs based on scroll pattern
+     */
+    predictPrefetchNeeds(pattern: ScrollPattern, visibleEnd: number, totalLoaded: number): PrefetchPrediction;
+    /**
+     * Track velocity history
+     */
+    private trackVelocity;
+    /**
+     * Track direction history
+     */
+    private trackDirection;
+    /**
+     * Get average velocity
+     */
+    private getAverageVelocity;
+    /**
+     * Get velocity variance
+     */
+    private getVelocityVariance;
+    /**
+     * Count direction changes
+     */
+    private countDirectionChanges;
+    /**
+     * Reset history
+     */
+    reset(): void;
+    /**
+     * Get prediction confidence
+     */
+    getConfidence(): number;
+}
+
+interface CacheConfig {
+    maxSize: number;
+    defaultTTL: number;
+    cleanupThreshold: number;
+}
+declare class PreemptiveCache<T> {
+    private cache;
+    private config;
+    private accessHistory;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Preemptively cache data with priority
+     */
+    preemptiveCache(index: number, data: T, priority?: 'low' | 'normal' | 'high' | 'critical'): void;
+    /**
+     * Get cached data
+     */
+    get(index: number): T | null;
+    /**
+     * Check if data is cached
+     */
+    has(index: number): boolean;
+    /**
+     * Get cached data for range
+     */
+    getRange(startIndex: number, endIndex: number): T[];
+    /**
+     * Delete cached data
+     */
+    delete(index: number): boolean;
+    /**
+     * Clear cache
+     */
+    clear(): void;
+    /**
+     * Cleanup old/low-priority entries
+     */
+    cleanup(): void;
+    /**
+     * Track access for analytics
+     */
+    private trackAccess;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+        avgAccessCount: number;
+        byPriority: {
+            critical: number;
+            high: number;
+            normal: number;
+            low: number;
+        };
+    };
+    /**
+     * Get all cached indices
+     */
+    getCachedIndices(): number[];
+    /**
+     * Preemptively cache range
+     */
+    cacheRange(startIndex: number, endIndex: number, dataFetcher: (index: number) => T, priority?: 'low' | 'normal' | 'high' | 'critical'): void;
+    /**
+     * Get memory usage estimate
+     */
+    getMemoryUsage(): number;
+}
+
+/**
+ * Intelligent Pagination
+ * Adaptive page size with cursor-based pagination
+ */
+interface PaginationState {
+    currentPage: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasMore: boolean;
+    cursor?: string;
+    nextCursor?: string;
+    prevCursor?: string;
+}
+interface CursorData {
+    page: number;
+    limit: number;
+    timestamp: number;
+    checksum?: string;
+}
+declare class IntelligentPagination {
+    private currentPage;
+    private basePageSize;
+    private adaptivePageSize;
+    private totalItems;
+    private loadHistory;
+    private readonly MIN_PAGE_SIZE;
+    private readonly MAX_PAGE_SIZE;
+    /**
+     * Get current pagination state
+     */
+    getState(): PaginationState;
+    /**
+     * Set total items
+     */
+    setTotalItems(total: number): void;
+    /**
+     * Go to next page
+     */
+    nextPage(): PaginationState;
+    /**
+     * Go to previous page
+     */
+    prevPage(): PaginationState;
+    /**
+     * Go to specific page
+     */
+    goToPage(page: number): PaginationState;
+    /**
+     * Record load time for adaptive sizing
+     */
+    recordLoadTime(page: number, loadTimeMs: number): void;
+    /**
+     * Adapt page size based on performance
+     */
+    private adaptPageSize;
+    /**
+     * Create cursor for page
+     */
+    createCursor(page: number): string;
+    /**
+     * Decode cursor
+     */
+    decodeCursor(cursor: string): CursorData | null;
+    /**
+     * Go to page from cursor
+     */
+    goToCursor(cursor: string): PaginationState;
+    /**
+     * Calculate checksum for cursor validation
+     */
+    private calculateChecksum;
+    /**
+     * Validate cursor checksum
+     */
+    private validateChecksum;
+    /**
+     * Get items to fetch for current page
+     */
+    getFetchRange(): {
+        skip: number;
+        limit: number;
+    };
+    /**
+     * Reset pagination
+     */
+    reset(): void;
+    /**
+     * Get load history for analytics
+     */
+    getLoadHistory(): {
+        page: number;
+        loadTime: number;
+    }[];
+    /**
+     * Get average load time
+     */
+    getAverageLoadTime(): number;
+    /**
+     * Set base page size
+     */
+    setBasePageSize(size: number): void;
+    /**
+     * Get current page size
+     */
+    getPageSize(): number;
+    /**
+     * Get current page number
+     */
+    getCurrentPage(): number;
+}
+
 declare class ScrollObserver {
     private container;
     private callback;
@@ -587,5 +1267,5 @@ declare class LazyScrollElementClass {
 }
 declare const LazyScrollElement: typeof LazyScrollElementClass;
 
-export { AdaptiveBufferCalculator, ContentComplexityAnalyzer, DevicePerformanceMonitor, Engine, GPUAccelerator, IntelligentScrollDetector, LazyList, LazyScroll, LazyScrollElement, MemoryManager, NetworkAwarePrefetchManager, NetworkAwareRequestQueue, NetworkSpeedDetector, PerformanceOptimizer, PrefetchManager, RequestQueue, ScrollObserver, WindowManager, createLazyScroll, debounce, throttle, useLazyList };
+export { AdaptiveBufferCalculator, BatchSizeOptimizer, ContentComplexityAnalyzer, DevicePerformanceMonitor, DynamicHeightEngine, Engine, GPUAccelerator, HeightMeasurementCache, IntelligentPagination, IntelligentScrollDetector, LazyList, LazyScroll, LazyScrollElement, MemoryManager, NetworkAwarePrefetchManager, NetworkAwareRequestQueue, NetworkSpeedDetector, PerformanceOptimizer, PreemptiveCache, PrefetchManager, Priority, PriorityRequestQueue, RequestDeduplicator, RequestQueue, ScrollObserver, SmartPrefetchAlgorithm, VariableHeightManager, WindowManager, createLazyScroll, debounce, throttle, useLazyList };
 export type { EngineConfig, EngineState, FetchMoreCallback, ScrollAnalysis, VisibleRange };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazy-render-virtual-scroll",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A framework-agnostic virtual scrolling and lazy rendering solution",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",