lazy-render-virtual-scroll 1.4.0 → 1.6.0

package/backend-helpers/frontend-example.tsx

@@ -0,0 +1,122 @@
+/**
+ * FRONTEND EXAMPLE - Integration with lazy-render
+ * Solves the 1 million cards performance issue
+ */
+
+import React, { useState } from 'react';
+import { LazyList, useLazyList } from 'lazy-render-virtual-scroll';
+
+interface Card {
+  id: number;
+  title: string;
+  category: string;
+  createdAt: string;
+}
+
+interface PaginationInfo {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasMore: boolean;
+}
+
+/**
+ * ✅ CORRECT FRONTEND IMPLEMENTATION
+ * Uses lazy-render with paginated API
+ */
+export const ColorfulDashboard: React.FC = () => {
+  const [items, setItems] = useState<Card[]>([]);
+  const [page, setPage] = useState(1);
+  const [hasMore, setHasMore] = useState(true);
+  const [pagination, setPagination] = useState<PaginationInfo | null>(null);
+
+  // Fetch more data when user scrolls
+  const fetchMore = async () => {
+    if (!hasMore) return [];
+    
+    try {
+      // Fetch only 50 items at a time
+      const response = await fetch(
+        `/api/monitoring/cards?page=${page}&limit=50`
+      );
+      
+      if (!response.ok) {
+        throw new Error('Failed to fetch cards');
+      }
+      
+      const result = await response.json();
+      
+      // Update state with new items
+      setItems(prev => [...prev, ...result.data]);
+      setPagination(result.pagination);
+      setPage(prev => prev + 1);
+      setHasMore(result.pagination.hasMore);
+      
+      return result.data;
+    } catch (error) {
+      console.error('Error fetching more cards:', error);
+      return [];
+    }
+  };
+
+  // Use lazy-render hook
+  const { visibleRange, isLoading } = useLazyList({
+    itemHeight: 200,
+    viewportHeight: 600,
+    bufferSize: 5,
+    fetchMore
+  });
+
+  // Render individual card
+  const renderCard = (card: Card, index: number) => (
+    <div
+      key={card.id}
+      style={{
+        height: '200px',
+        borderBottom: '1px solid #eee',
+        padding: '16px'
+      }}
+    >
+      <h3>{card.title}</h3>
+      <p>Category: {card.category}</p>
+      <p>Created: {new Date(card.createdAt).toLocaleDateString()}</p>
+    </div>
+  );
+
+  return (
+    <div style={{ padding: '20px' }}>
+      <h1>Colorful Dashboard</h1>
+      
+      {/* Pagination Info */}
+      {pagination && (
+        <div style={{ marginBottom: '16px' }}>
+          <p>
+            Showing {items.length} of {pagination.total} cards
+            {isLoading && ' • Loading...'}
+          </p>
+        </div>
+      )}
+      
+      {/* LazyList with virtual scrolling */}
+      <LazyList
+        items={items}
+        itemHeight={200}
+        viewportHeight={600}
+        fetchMore={fetchMore}
+        renderItem={renderCard}
+        bufferSize={5}
+        overscan={2}
+      />
+      
+      {/* Load More Button (optional fallback) */}
+      {!hasMore && (
+        <div style={{ textAlign: 'center', padding: '20px' }}>
+          <p>No more cards to load</p>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default ColorfulDashboard;

package/backend-helpers/pagination.ts

@@ -0,0 +1,159 @@
+/**
+ * Backend Pagination Helper for lazy-render
+ * Solves the 1 million cards performance issue
+ */
+
+export interface PaginationParams {
+  page: number;
+  limit: number;
+  cursor?: string;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+    nextCursor?: string;
+    prevCursor?: string;
+  };
+}
+
+/**
+ * Calculate pagination metadata
+ */
+export function calculatePagination<T>(
+  items: T[],
+  page: number,
+  limit: number,
+  total: number
+): PaginatedResponse<T> {
+  const totalPages = Math.ceil(total / limit);
+  const hasMore = page < totalPages;
+  
+  return {
+    data: items,
+    pagination: {
+      page,
+      limit,
+      total,
+      totalPages,
+      hasMore,
+      nextCursor: hasMore ? String(page + 1) : undefined,
+      prevCursor: page > 1 ? String(page - 1) : undefined
+    }
+  };
+}
+
+/**
+ * Validate pagination parameters
+ */
+export function validatePaginationParams(params: PaginationParams): {
+  page: number;
+  limit: number;
+  errors: string[];
+} {
+  const errors: string[] = [];
+  
+  // Validate page
+  const page = parseInt(String(params.page)) || 1;
+  if (page < 1) {
+    errors.push('Page must be greater than 0');
+  }
+  
+  // Validate limit
+  const limit = parseInt(String(params.limit)) || 50;
+  if (limit < 1) {
+    errors.push('Limit must be greater than 0');
+  }
+  if (limit > 1000) {
+    errors.push('Limit cannot exceed 1000 items per page');
+  }
+  
+  return {
+    page: page < 1 ? 1 : page,
+    limit: limit < 1 ? 50 : limit > 1000 ? 1000 : limit,
+    errors
+  };
+}
+
+/**
+ * Express.js middleware for pagination
+ */
+export function paginationMiddleware(
+  req: any,
+  res: any,
+  next: () => void
+) {
+  const { page, limit, cursor } = req.query;
+  
+  const validated = validatePaginationParams({
+    page: parseInt(String(page)) || 1,
+    limit: parseInt(String(limit)) || 50,
+    cursor
+  });
+  
+  if (validated.errors.length > 0) {
+    return res.status(400).json({
+      error: 'Invalid pagination parameters',
+      details: validated.errors
+    });
+  }
+  
+  req.pagination = {
+    page: validated.page,
+    limit: validated.limit,
+    cursor: validated.cursor
+  };
+  
+  next();
+}
+
+/**
+ * Example Express route handler
+ */
+export function createPaginatedRoute<T>(
+  getDataFunction: (skip: number, limit: number) => Promise<{ items: T[]; total: number }>,
+  options: {
+    defaultLimit?: number;
+    maxLimit?: number;
+  } = {}
+) {
+  const defaultLimit = options.defaultLimit || 50;
+  const maxLimit = options.maxLimit || 1000;
+  
+  return async (req: any, res: any) => {
+    try {
+      const page = parseInt(req.query.page) || 1;
+      const limit = Math.min(
+        parseInt(req.query.limit) || defaultLimit,
+        maxLimit
+      );
+      const skip = (page - 1) * limit;
+      
+      // Get data with pagination
+      const { items, total } = await getDataFunction(skip, limit);
+      
+      // Return paginated response
+      const response = calculatePagination(items, page, limit, total);
+      
+      res.json(response);
+    } catch (error) {
+      console.error('Pagination error:', error);
+      res.status(500).json({
+        error: 'Failed to fetch data',
+        message: error instanceof Error ? error.message : 'Unknown error'
+      });
+    }
+  };
+}
+
+export default {
+  calculatePagination,
+  validatePaginationParams,
+  paginationMiddleware,
+  createPaginatedRoute
+};

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 };