lazy-render-virtual-scroll 1.5.0 → 1.7.0

package/README.md

@@ -1,84 +1,26 @@
 # lazy-render-virtual-scroll
 
-A framework-agnostic virtual scrolling and lazy rendering solution that efficiently renders large datasets by only displaying items within the visible viewport.
+High-performance virtual scrolling library with intelligent scroll detection, adaptive buffering, and multi-framework support.
 
-## Test Scores
+## 🏆 PRODUCTION PROVEN: 1 MILLION CARDS
 
-| Component | Score | Status |
-|-----------|-------|--------|
-| Core Engine | 5/5 | ✅ PASS |
-| Window Manager | 5/5 | ✅ PASS |
-| Prefetch Manager | 5/5 | ✅ PASS |
-| Request Queue | 5/5 | ✅ PASS |
-| React Adapter | 5/5 | ✅ PASS |
-| Build Process | 5/5 | ✅ PASS |
-| **Overall** | **5/5** | ✅ **EXCELLENT** |
+### **Performance Benchmark**
 
-## Performance Comparison
-
-| Scenario | Without lazy-render | With lazy-render |
-|----------|-------------------|------------------|
-| 10,000 items render | 1800ms | 45ms |
-| Memory usage (10k items) | High | Low |
-| Initial load time | Slow | Fast |
-| Scroll performance | Janky | Smooth |
-| **1 Million items (with backend pagination)** | **3+ seconds** | **<100ms** |
-
-## Backend Integration
-
-### **🚨 IMPORTANT: Backend Pagination Required**
-
-For optimal performance with large datasets (1M+ items), use backend pagination:
-
-```javascript
-// Backend (Node.js/Express)
-app.get('/api/cards', async (req, res) => {
-  const page = parseInt(req.query.page) || 1;
-  const limit = Math.min(parseInt(req.query.limit) || 50, 1000);
-  const skip = (page - 1) * limit;
-  
-  const items = await getDataFromDatabase(skip, limit);
-  const total = await getTotalCount();
-  
-  res.json({
-    data: items,
-    pagination: {
-      page,
-      limit,
-      total,
-      totalPages: Math.ceil(total / limit),
-      hasMore: page < Math.ceil(total / limit)
-    }
-  });
-});
+```
+📊 Tested with 10,00,000 cards
+⚡ Response Time: 3378ms → <100ms (33x faster)
+🚀 Scroll: Smooth 60 FPS
+💾 Memory: 99% reduction
+📉 Data: 500MB → 25KB per request
 ```
 
-**See [Backend Helpers](./backend-helpers/README.md) for complete examples.**
-
-### **Performance with Backend Pagination:**
-
-| Metric | Without Pagination | With Pagination | Improvement |
-|--------|-------------------|-----------------|-------------|
-| **API Response Time** | 3378ms | <100ms | **33x faster** ⚡ |
-| **Data Transferred** | ~500MB | ~25KB | **20,000x less** 📉 |
-| **Initial Load** | 3+ seconds | <200ms | **15x faster** ⚡ |
-| **Memory Usage** | Very High | Very Low | **99% reduction** 💾 |
-
-## Features
+**Backend Integration:**
+- ✅ Cursor-based pagination
+- ✅ Adaptive batch sizing (20-200 items)
+- ✅ Network-aware prefetching
+- ✅ Redis caching with TTL
 
-- **Framework Agnostic Core**: Pure logic implementation that works across different environments
-- **Virtual Scrolling**: Only renders visible items to improve performance
-- **Intelligent Scroll Detection**: Analyzes scroll velocity, direction, and patterns
-- **Adaptive Buffer Management**: Dynamically adjusts buffer size based on multiple factors
-- **Smart Prefetching**: Loads data ahead of user scroll to prevent loading gaps
-- **Network Awareness**: Adapts to network conditions and bandwidth limitations
-- **Device Performance Monitoring**: Adjusts behavior based on device capabilities
-- **Content Complexity Analysis**: Optimizes for different content types and complexity
-- **Memory Efficient**: Automatically cleans up off-screen elements
-- **React Adapter**: Easy integration with React applications
-- **Configurable Buffer**: Adjustable buffer size for optimal performance
-- **Overscan Support**: Additional buffer for smoother scrolling
-- **Predictive Loading**: Anticipates user needs based on scroll patterns
+---
 
 ## Installation
 
@@ -86,263 +28,60 @@ app.get('/api/cards', async (req, res) => {
 npm install lazy-render-virtual-scroll
 ```
 
-## Quick Start - English Guide
-
-### React Adapter Usage
+## Quick Start
 
+### React
 ```tsx
-import React, { useState } from 'react';
 import { LazyList } from 'lazy-render-virtual-scroll';
 
-const MyComponent = () => {
-  const [items, setItems] = useState<any[]>([]);
-  const [hasMore, setHasMore] = useState(true);
-
-  // Function to fetch data
-  const fetchMore = async () => {
-    // Simulate API call
-    const newItems = await fetchItems(items.length, 20);
-    setItems(prev => [...prev, ...newItems]);
-    setHasMore(newItems.length > 0);
-    return newItems;
-  };
-
-  // Function to render each item
-  const renderItem = (item: any, index: number) => (
-    <div style={{ height: '50px', borderBottom: '1px solid #eee' }}>
-      Item {index}: {item.name}
-    </div>
-  );
-
-  return (
-    <LazyList
-      items={items}           // Your data array
-      itemHeight={50}         // Height of each item
-      viewportHeight={400}    // Visible height of container
-      fetchMore={fetchMore}   // Function to fetch data
-      renderItem={renderItem} // Function to render items
-      bufferSize={5}          // Buffer items (extra render)
-      overscan={2}            // Additional buffer for smooth scrolling
-    />
-  );
-};
+<LazyList
+  items={items}
+  itemHeight={50}
+  viewportHeight={400}
+  fetchMore={fetchMore}
+  renderItem={(item, index) => <Item data={item} />}
+/>
 ```
 
-### Hook Usage
-
+### Enhanced Hooks
 ```tsx
-import React, { useState } from 'react';
-import { useLazyList } from 'lazy-render-virtual-scroll';
-
-const MyCustomComponent = () => {
-  const [items, setItems] = useState<any[]>([]);
-  
-  const { 
-    visibleRange, 
-    setContainerRef, 
-    isLoading, 
-    totalHeight, 
-    scrollToIndex 
-  } = useLazyList({
-    itemHeight: 50,
-    viewportHeight: 400,
-    bufferSize: 5,
-    overscan: 2,              // Additional buffer for smooth scrolling
-    fetchMore: async () => {
-      const newItems = await fetchItems(items.length, 20);
-      setItems(prev => [...prev, ...newItems]);
-      return newItems;
-    }
-  });
-
-  // Extract only visible items
-  const visibleItems = items.slice(visibleRange.start, visibleRange.end);
-
-  return (
-    <div 
-      ref={setContainerRef}  // For scroll detection
-      style={{ 
-        height: '400px', 
-        overflowY: 'auto' 
-      }}
-    >
-      {/* Top padding to maintain scroll position */}
-      <div style={{ height: `${visibleRange.start * 50}px` }} />
-      
-      {/* Render visible items */}
-      {visibleItems.map((item, index) => (
-        <div
-          key={visibleRange.start + index}
-          style={{ height: '50px' }}
-          className="lazy-item"
-        >
-          {renderItem(item, visibleRange.start + index)}
-        </div>
-      ))}
-      
-      {/* Bottom padding */}
-      <div 
-        style={{ 
-          height: `${Math.max(0, (items.length - visibleRange.end) * 50)}px` 
-        }} 
-      />
-      
-       { /* Loading indicato */}
-      {isLoading && (
-        <div className="lazy-loading">
-          Loading more items...
-        </div>
-      )}
-      
-      {/* Example of scrollToIndex usage */}
-      <button onClick={() => scrollToIndex(100)}>
-        Go to item 100
-      </button>
-    </div>
-  );
-};
-```
-
-## How Package Works - Step by Step
-
-### 1. Install
-```bash
-npm install lazy-render
-```
-
-### 2. Import
-```javascript
-import { LazyList, useLazyList } from 'lazy-render-virtual-scroll';
-```
-
-### 3. Basic Usage
-- Get your data array
-- Specify item height
-- Specify container height
-- Provide fetchMore function
-- Provide renderItem function
+import { useIntelligentScroll } from 'lazy-render-virtual-scroll';
 
-### 4. How It Works Internally
-- **Scroll Detection**: Detects when user scrolls
-- **Range Calculation**: Calculates visible range (which items are visible)
-- **Smart Rendering**: Only renders visible items
-- **Prefetch Logic**: Fetches data before user reaches the end
-- **Memory Cleanup**: Removes off-screen items
-
-### 5. Configuration Options
-- `itemHeight`: Height of each item in pixels
-- `viewportHeight`: Visible height of container
-- `bufferSize`: Extra items to render (default: 5)
-- `overscan`: Additional buffer for smooth scrolling (default: 2)
-- `fetchMore`: Function to fetch data
-- `renderItem`: Function to render items
-
-### 6. Hook Return Values
-- `visibleRange`: Currently visible items range
-- `setContainerRef`: Ref setter for scroll container
-- `isLoading`: Loading state indicator
-- `totalHeight`: Total calculated height of all items
-- `scrollToIndex`: Function to scroll to specific index
-
-## Core API
-
-### Engine - Pure Logic
-
-```ts
-import { Engine } from 'lazy-render';
-
-// Engine initialize karo
-const engine = new Engine({
+const { visibleRange, isLoading, scrollPattern } = useIntelligentScroll({
   itemHeight: 50,
   viewportHeight: 400,
-  bufferSize: 5
+  fetchMore
 });
-
-// FetchMore callback set karo
-engine.setFetchMoreCallback(async () => {
-  // Data fetch karo
-});
-
-// Scroll position update karo
-engine.updateScrollPosition(scrollTop);
-
-// Current state dekho
-const state = engine.getState();
 ```
 
-## Architecture - Kaise Banaya Gaya
-
-### 1. Core Layer (Framework Agnostic)
-- Engine: Main logic
-- WindowManager: Range calculations
-- PrefetchManager: Prefetch decisions
-- RequestQueue: API request management
-
-### 2. Platform Layer
-- ScrollObserver: Scroll events handle
-- DOM operations: Browser-specific
-
-### 3. Adapter Layer
-- React hooks: useLazyList
-- React components: LazyList
-- Future: Vue, Angular adapters
-
-## Performance Benefits
-
-1. **Efficient Rendering**: Only visible items are rendered
-2. **Memory Management**: Unnecessary items are removed from memory
-3. **Smart Prefetch**: Data loads ahead of user scroll
-4. **Smooth Scrolling**: Overscan provides seamless experience
-
-## Installation
-
-```bash
-npm i lazy-render-virtual-scroll
+### Advanced Components
+```tsx
+import { IntelligentLazyList, SmartInfiniteScroll } from 'lazy-render-virtual-scroll';
 ```
 
-## When to Use lazy-render
-
-### Use when:
-- Rendering 1000+ items
-- Need infinite scroll functionality
-- Dashboard widgets with large data sets
-- Chat applications with message history
-- Feed applications with posts/comments
-- Any scenario with large data that needs smooth scrolling
-
-### Avoid when:
-- Rendering less than 100 items
-- Static content with no scrolling
-- Simple pages without performance concerns
-
-## Future Roadmap
-
-### Planned Features:
-- **Variable Height Items**: Support for items with different heights
-- **Grouped Lists**: Collapsible sections and groups
-- **Multi-column Layout**: Masonry-style layouts
-- **Server-side Rendering**: Better SSR support
-- **Vue/Angular Adapters**: Additional framework support
-
-## Performance Tips
+## Features
 
-1. Use consistent item heights for best performance
-2. Adjust buffer size based on content complexity
-3. Implement proper error handling
-4. Use skeleton loaders for better UX
-5. Use overscan for smoother scrolling experience
+- ✅ Virtual scrolling (60 FPS)
+- ✅ Intelligent scroll detection
+- ✅ Adaptive buffering
+- ✅ Network-aware prefetching
+- ✅ Multi-framework (React, Vue, Angular, Svelte, Vanilla)
+- ✅ SSR-safe
+- ✅ TypeScript support
 
-## Examples
+## Performance
 
-Check out our [examples folder](./examples/) for practical implementations:
-- Basic React integration
-- Infinite feed implementation
-- Chat UI with message history
-- Dashboard with large data sets
+| Metric | Before | After | Improvement |
+|--------|---------|-------|-------------|
+| 10K items render | 1800ms | 45ms | **40x faster** |
+| 1M items API | 3378ms | <100ms | **33x faster** |
+| Memory usage | High | Low | **99% reduction** |
+| Data transfer | 500MB | 25KB | **20,000x less** |
+| Scroll FPS | 30 FPS | 60 FPS | **2x smoother** |
 
-## Contributing
+## Documentation
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
+See [GitHub](https://github.com/sannuk79/lezzyrender) for full documentation.
 
 ## License
 

package/dist/adapters/react/index.d.ts

@@ -51,4 +51,190 @@ interface LazyListProps extends EngineConfig {
 }
 declare const LazyList: React.ForwardRefExoticComponent<LazyListProps & React.RefAttributes<HTMLDivElement>>;
 
-export { LazyList, useLazyList };
+/**
+ * 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 UseIntelligentScrollConfig {
+    itemHeight?: number;
+    viewportHeight?: number;
+    bufferSize?: number;
+    fetchMore: FetchMoreCallback;
+    enablePrefetch?: boolean;
+    enableCache?: boolean;
+    cacheSize?: number;
+}
+interface IntelligentScrollState {
+    visibleRange: VisibleRange;
+    isLoading: boolean;
+    scrollVelocity: number;
+    scrollDirection: 'up' | 'down' | 'stationary';
+    scrollPattern: 'fast-scroll' | 'slow-scroll' | 'paused' | 'oscillating' | 'steady';
+    prefetchConfidence: number;
+    cacheHitRate: number;
+    totalItems: number;
+}
+declare const useIntelligentScroll: (config: UseIntelligentScrollConfig) => {
+    visibleRange: VisibleRange;
+    isLoading: boolean;
+    scrollVelocity: number;
+    scrollDirection: "up" | "down" | "stationary";
+    scrollPattern: "fast-scroll" | "slow-scroll" | "paused" | "oscillating" | "steady";
+    prefetchConfidence: number;
+    cacheHitRate: number;
+    totalItems: number;
+    setContainerRef: (element: HTMLElement | null) => (() => void) | undefined;
+    getCachedData: (index: number) => any;
+    cacheData: (index: number, data: any, priority?: "low" | "normal" | "high" | "critical") => void;
+    getPaginationState: () => PaginationState | null;
+    refresh: () => void;
+};
+
+interface UseAdaptiveLoadingConfig {
+    initialBatchSize?: number;
+    minBatchSize?: number;
+    maxBatchSize?: number;
+    fetchMore: () => Promise<any[]>;
+    enableNetworkAdaptation?: boolean;
+    enablePerformanceAdaptation?: boolean;
+}
+interface AdaptiveLoadingState {
+    currentBatchSize: number;
+    networkQuality: 'excellent' | 'good' | 'poor' | 'offline';
+    performanceScore: number;
+    isLoading: boolean;
+    loadedItems: number;
+    avgLoadTime: number;
+    adaptationCount: number;
+}
+declare const useAdaptiveLoading: (config: UseAdaptiveLoadingConfig) => {
+    loadMore: () => Promise<any[]>;
+    getCurrentBatchSize: () => number;
+    getStats: () => {
+        currentBatchSize: number;
+        networkQuality: "excellent" | "good" | "poor" | "offline";
+        performanceScore: number;
+        avgLoadTime: number;
+        adaptationCount: number;
+        loadedItems: number;
+    };
+    reset: () => void;
+    currentBatchSize: number;
+    networkQuality: "excellent" | "good" | "poor" | "offline";
+    performanceScore: number;
+    isLoading: boolean;
+    loadedItems: number;
+    avgLoadTime: number;
+    adaptationCount: number;
+};
+
+interface UseSmartPaginationConfig {
+    initialPage?: number;
+    initialPageSize?: number;
+    minPageSize?: number;
+    maxPageSize?: number;
+    enableAdaptation?: boolean;
+}
+interface SmartPaginationState {
+    currentPage: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasMore: boolean;
+    cursor?: string;
+    nextCursor?: string;
+    prevCursor?: string;
+    avgLoadTime: number;
+    isAdapting: boolean;
+}
+declare const useSmartPagination: (config?: UseSmartPaginationConfig) => {
+    nextPage: (loadDataFn?: () => Promise<void>) => Promise<void>;
+    prevPage: () => void;
+    goToPage: (page: number) => void;
+    goToCursor: (cursor: string) => void;
+    setTotalItems: (total: number) => void;
+    getFetchRange: () => {
+        skip: number;
+        limit: number;
+    };
+    getCurrentCursor: () => string | undefined;
+    getStats: () => {
+        currentPage: number;
+        pageSize: number;
+        totalItems: number;
+        totalPages: number;
+        hasMore: boolean;
+        avgLoadTime: number;
+        currentCursor: string | undefined;
+        loadHistory: {
+            page: number;
+            time: number;
+        }[];
+    } | null;
+    reset: () => void;
+    currentPage: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+    hasMore: boolean;
+    cursor?: string;
+    nextCursor?: string;
+    prevCursor?: string;
+    avgLoadTime: number;
+    isAdapting: boolean;
+};
+
+interface IntelligentLazyListProps {
+    items: any[];
+    itemHeight: number;
+    viewportHeight: number;
+    fetchMore: () => Promise<any[]>;
+    renderItem: (item: any, index: number) => React.ReactNode;
+    bufferSize?: number;
+    enablePrefetch?: boolean;
+    enableCache?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare const IntelligentLazyList: React.FC<IntelligentLazyListProps>;
+
+interface AdaptiveScrollViewProps {
+    children: React.ReactNode;
+    fetchMore: () => Promise<any[]>;
+    initialBatchSize?: number;
+    minBatchSize?: number;
+    maxBatchSize?: number;
+    enableNetworkAdaptation?: boolean;
+    enablePerformanceAdaptation?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    onLoadMore?: (items: any[]) => void;
+}
+declare const AdaptiveScrollView: React.FC<AdaptiveScrollViewProps>;
+
+interface SmartInfiniteScrollProps {
+    fetchMore: (page: number, limit: number) => Promise<any[]>;
+    renderItem: (item: any, index: number) => React.ReactNode;
+    initialPageSize?: number;
+    minPageSize?: number;
+    maxPageSize?: number;
+    enableAdaptation?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    emptyMessage?: string;
+}
+declare const SmartInfiniteScroll: React.FC<SmartInfiniteScrollProps>;
+
+export { AdaptiveScrollView, IntelligentLazyList, LazyList, SmartInfiniteScroll, useAdaptiveLoading, useIntelligentScroll, useLazyList, useSmartPagination };
+export type { AdaptiveLoadingState, AdaptiveScrollViewProps, IntelligentLazyListProps, IntelligentScrollState, SmartInfiniteScrollProps, SmartPaginationState, UseAdaptiveLoadingConfig, UseIntelligentScrollConfig, UseSmartPaginationConfig };