lazy-render-virtual-scroll 1.0.1

package/src/adapters/react/useLazyList.ts

@@ -0,0 +1,87 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { Engine } from '../../core/Engine';
+import { EngineConfig, VisibleRange, FetchMoreCallback } from '../../core/types';
+
+interface LazyListConfig extends EngineConfig {
+  fetchMore: FetchMoreCallback;
+}
+
+export const useLazyList = (config: LazyListConfig) => {
+  const { fetchMore, ...engineConfig } = config;
+  const engineRef = useRef<Engine | null>(null);
+  const containerRef = useRef<HTMLElement | null>(null);
+  
+  const [visibleRange, setVisibleRange] = useState<VisibleRange>({ start: 0, end: 0 });
+  const [loadedItems, setLoadedItems] = useState<any[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  // Initialize engine
+  useEffect(() => {
+    engineRef.current = new Engine(engineConfig);
+    engineRef.current.setFetchMoreCallback(fetchMore);
+
+    return () => {
+      if (engineRef.current) {
+        engineRef.current.cleanup();
+      }
+    };
+  }, []);
+
+  // Update engine when config changes
+  useEffect(() => {
+    if (engineRef.current) {
+      engineRef.current.updateDimensions(
+        engineConfig.viewportHeight,
+        engineConfig.itemHeight
+      );
+    }
+  }, [engineConfig.viewportHeight, engineConfig.itemHeight]);
+
+  // Handle scroll events
+  const handleScroll = useCallback((scrollTop: number) => {
+    if (engineRef.current) {
+      engineRef.current.updateScrollPosition(scrollTop);
+      
+      // Update state based on engine
+      const state = engineRef.current.getState();
+      setVisibleRange(state.visibleRange);
+      setIsLoading(state.isLoading);
+    }
+  }, []);
+
+  // Set container reference
+  const setContainerRef = (element: HTMLElement | null) => {
+    if (element) {
+      containerRef.current = element;
+      
+      // Initialize scroll observer when container is available
+      if (typeof window !== 'undefined' && element) {
+        // In a real implementation, we would use ScrollObserver here
+        // For now, we'll just attach a basic scroll listener
+        const handleScrollEvent = () => {
+          handleScroll(element.scrollTop);
+        };
+        
+        element.addEventListener('scroll', handleScrollEvent, { passive: true });
+        
+        // Cleanup
+        return () => {
+          element.removeEventListener('scroll', handleScrollEvent);
+        };
+      }
+    }
+  };
+
+  return {
+    visibleRange,
+    loadedItems,
+    isLoading,
+    setContainerRef,
+    // Helper function to trigger manual refresh
+    refresh: () => {
+      if (engineRef.current) {
+        engineRef.current.updateScrollPosition(containerRef.current?.scrollTop || 0);
+      }
+    }
+  };
+};

package/src/core/Engine.ts

@@ -0,0 +1,134 @@
+import { EngineConfig, VisibleRange, FetchMoreCallback, EngineState } from './types';
+import { WindowManager } from './WindowManager';
+import { PrefetchManager } from './PrefetchManager';
+import { RequestQueue } from './RequestQueue';
+
+export class Engine {
+  private config: EngineConfig;
+  private windowManager: WindowManager;
+  private prefetchManager: PrefetchManager;
+  private requestQueue: RequestQueue;
+  
+  private state: EngineState;
+  private fetchMoreCallback: FetchMoreCallback | null = null;
+  private totalItems: number;
+
+  constructor(config: EngineConfig) {
+    this.config = {
+      ...config,
+      bufferSize: config.bufferSize || 5
+    };
+    
+    this.windowManager = new WindowManager(
+      this.config.itemHeight,
+      this.config.viewportHeight,
+      this.config.bufferSize
+    );
+    
+    this.prefetchManager = new PrefetchManager(this.config.bufferSize);
+    this.requestQueue = new RequestQueue(1); // Single request at a time
+    
+    this.totalItems = this.config.totalItems || Number.MAX_SAFE_INTEGER;
+    
+    this.state = {
+      scrollTop: 0,
+      visibleRange: { start: 0, end: 0 },
+      loadedItems: 0,
+      isLoading: false
+    };
+  }
+
+  /**
+   * Update scroll position and recalculate visible range
+   */
+  updateScrollPosition(scrollTop: number): void {
+    this.state.scrollTop = scrollTop;
+    this.state.visibleRange = this.windowManager.calculateVisibleRange(scrollTop);
+    
+    // Check if we need to fetch more items
+    if (this.shouldFetchMore()) {
+      this.fetchMore();
+    }
+  }
+
+  /**
+   * Get the current visible range
+   */
+  getVisibleRange(): VisibleRange {
+    return this.state.visibleRange;
+  }
+
+  /**
+   * Check if more items should be fetched
+   */
+  shouldFetchMore(): boolean {
+    if (!this.fetchMoreCallback) return false;
+    if (this.state.isLoading) return false;
+    if (this.state.loadedItems >= this.totalItems) return false;
+    
+    return this.prefetchManager.shouldPrefetch(
+      this.state.visibleRange.end,
+      this.state.loadedItems
+    );
+  }
+
+  /**
+   * Fetch more items
+   */
+  async fetchMore(): Promise<void> {
+    if (!this.fetchMoreCallback || this.state.isLoading) return;
+    
+    this.state.isLoading = true;
+    
+    try {
+      const result = await this.requestQueue.add(this.fetchMoreCallback);
+      // Assuming the result contains new items
+      // In a real implementation, this would update the loaded items count
+      this.state.loadedItems += Array.isArray(result) ? result.length : 1;
+    } catch (error) {
+      console.error('Error fetching more items:', error);
+    } finally {
+      this.state.isLoading = false;
+    }
+  }
+
+  /**
+   * Set the fetchMore callback function
+   */
+  setFetchMoreCallback(callback: FetchMoreCallback): void {
+    this.fetchMoreCallback = callback;
+  }
+
+  /**
+   * Update total items count
+   */
+  updateTotalItems(count: number): void {
+    this.totalItems = count;
+  }
+
+  /**
+   * Get current engine state
+   */
+  getState(): EngineState {
+    return { ...this.state };
+  }
+
+  /**
+   * Update viewport dimensions
+   */
+  updateDimensions(viewportHeight: number, itemHeight: number): void {
+    this.windowManager.updateViewportHeight(viewportHeight);
+    this.windowManager.updateItemHeight(itemHeight);
+    
+    // Recalculate visible range with new dimensions
+    this.state.visibleRange = this.windowManager.calculateVisibleRange(this.state.scrollTop);
+  }
+
+  /**
+   * Cleanup resources
+   */
+  cleanup(): void {
+    this.requestQueue.clear();
+    this.fetchMoreCallback = null;
+  }
+}

package/src/core/PrefetchManager.ts

@@ -0,0 +1,22 @@
+export class PrefetchManager {
+  private bufferSize: number;
+
+  constructor(bufferSize: number = 5) {
+    this.bufferSize = bufferSize;
+  }
+
+  /**
+   * Determine if more items should be fetched based on visible range and loaded items
+   */
+  shouldPrefetch(visibleEnd: number, totalLoaded: number): boolean {
+    // Simple rule: if visible end is approaching the loaded boundary, fetch more
+    return visibleEnd >= totalLoaded - this.bufferSize;
+  }
+
+  /**
+   * Update buffer size if it changes
+   */
+  updateBufferSize(size: number): void {
+    this.bufferSize = size;
+  }
+}

package/src/core/RequestQueue.ts

@@ -0,0 +1,69 @@
+export class RequestQueue {
+  private queue: Array<() => Promise<any>> = [];
+  private processing: boolean = false;
+  private maxConcurrent: number;
+
+  constructor(maxConcurrent: number = 1) {
+    this.maxConcurrent = maxConcurrent;
+  }
+
+  /**
+   * Add a request to the queue
+   */
+  add(requestFn: () => Promise<any>): Promise<any> {
+    return new Promise((resolve, reject) => {
+      this.queue.push(() => requestFn().then(resolve).catch(reject));
+      
+      // Start processing if not already processing
+      if (!this.processing) {
+        this.processQueue();
+      }
+    });
+  }
+
+  /**
+   * Process the queue
+   */
+  private async processQueue(): Promise<void> {
+    if (this.queue.length === 0) {
+      this.processing = false;
+      return;
+    }
+
+    this.processing = true;
+
+    // Process up to maxConcurrent requests
+    const concurrentRequests = [];
+    const count = Math.min(this.maxConcurrent, this.queue.length);
+
+    for (let i = 0; i < count; i++) {
+      const requestFn = this.queue.shift();
+      if (requestFn) {
+        concurrentRequests.push(requestFn());
+      }
+    }
+
+    try {
+      await Promise.all(concurrentRequests);
+    } catch (error) {
+      console.error('Request queue error:', error);
+    }
+
+    // Process remaining items
+    await this.processQueue();
+  }
+
+  /**
+   * Clear the queue
+   */
+  clear(): void {
+    this.queue = [];
+  }
+
+  /**
+   * Get the current queue length
+   */
+  getLength(): number {
+    return this.queue.length;
+  }
+}

package/src/core/WindowManager.ts

@@ -0,0 +1,49 @@
+import { VisibleRange } from './types';
+
+export class WindowManager {
+  private itemHeight: number;
+  private viewportHeight: number;
+  private bufferSize: number;
+
+  constructor(itemHeight: number, viewportHeight: number, bufferSize: number = 5) {
+    this.itemHeight = itemHeight;
+    this.viewportHeight = viewportHeight;
+    this.bufferSize = bufferSize;
+  }
+
+  /**
+   * Calculate the visible range based on scroll position
+   */
+  calculateVisibleRange(scrollTop: number): VisibleRange {
+    // Calculate how many items fit in the viewport
+    const itemsPerViewport = Math.ceil(this.viewportHeight / this.itemHeight);
+    
+    // Calculate the starting index based on scroll position
+    const startIndex = Math.floor(scrollTop / this.itemHeight);
+    
+    // Calculate the ending index with buffer
+    const endIndex = Math.min(
+      startIndex + itemsPerViewport + this.bufferSize,
+      Number.MAX_SAFE_INTEGER // Will be limited by total items later
+    );
+
+    return {
+      start: Math.max(0, startIndex - this.bufferSize),
+      end: endIndex
+    };
+  }
+
+  /**
+   * Update viewport height if it changes
+   */
+  updateViewportHeight(height: number): void {
+    this.viewportHeight = height;
+  }
+
+  /**
+   * Update item height if it changes
+   */
+  updateItemHeight(height: number): void {
+    this.itemHeight = height;
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,24 @@
+// Shared type definitions for lazy-render
+
+export interface EngineConfig {
+  itemHeight: number;
+  viewportHeight: number;
+  bufferSize?: number;
+  totalItems?: number;
+}
+
+export interface VisibleRange {
+  start: number;
+  end: number;
+}
+
+export interface FetchMoreCallback {
+  (): Promise<any>;
+}
+
+export interface EngineState {
+  scrollTop: number;
+  visibleRange: VisibleRange;
+  loadedItems: number;
+  isLoading: boolean;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Core exports
+export { Engine } from './core/Engine';
+export { WindowManager } from './core/WindowManager';
+export { PrefetchManager } from './core/PrefetchManager';
+export { RequestQueue } from './core/RequestQueue';
+export type { EngineConfig, VisibleRange, FetchMoreCallback, EngineState } from './core/types';
+
+// Platform exports
+export { ScrollObserver } from './platform/browser/ScrollObserver';
+
+// React adapter exports
+export { useLazyList } from './adapters/react/useLazyList';
+export { LazyList } from './adapters/react/LazyList';
+
+// Utility exports
+export { debounce } from './utils/debounce';
+export { throttle } from './utils/throttle';

package/src/platform/browser/ScrollObserver.ts

@@ -0,0 +1,86 @@
+export class ScrollObserver {
+  private container: HTMLElement;
+  private callback: (scrollTop: number) => void;
+  private options: IntersectionObserverInit;
+  private observer: IntersectionObserver | null = null;
+  private sentinelElement: HTMLElement | null = null;
+  
+  constructor(
+    container: HTMLElement, 
+    callback: (scrollTop: number) => void,
+    options?: Partial<IntersectionObserverInit>
+  ) {
+    this.container = container;
+    this.callback = callback;
+    this.options = {
+      root: container,
+      threshold: [0, 1],
+      ...options
+    };
+  }
+
+  /**
+   * Start observing scroll events
+   */
+  observe(): void {
+    // Create a sentinel element at the bottom to detect when user scrolls near the end
+    this.sentinelElement = document.createElement('div');
+    this.sentinelElement.style.height = '1px'; // Very small element
+    this.sentinelElement.setAttribute('data-lazy-sentinel', '');
+    
+    // Add sentinel to the container
+    this.container.appendChild(this.sentinelElement);
+    
+    // Create intersection observer to detect when sentinel comes into view
+    this.observer = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          // Trigger callback with current scroll position
+          this.callback(this.container.scrollTop);
+        }
+      });
+    }, this.options);
+    
+    this.observer.observe(this.sentinelElement);
+    
+    // Also listen to scroll events for continuous updates
+    this.container.addEventListener('scroll', this.onScroll, { passive: true });
+  }
+
+  /**
+   * Handle scroll events
+   */
+  private onScroll = (): void => {
+    // Debounced scroll handler to prevent too frequent updates
+    this.debounce(() => {
+      this.callback(this.container.scrollTop);
+    }, 16); // ~60fps
+  };
+
+  /**
+   * Debounce function for scroll events
+   */
+  private debounce(func: () => void, wait: number): void {
+    let timeout: NodeJS.Timeout;
+    
+    clearTimeout(timeout);
+    timeout = setTimeout(func, wait);
+  }
+
+  /**
+   * Disconnect observer and clean up
+   */
+  disconnect(): void {
+    if (this.observer) {
+      this.observer.disconnect();
+      this.observer = null;
+    }
+    
+    if (this.sentinelElement) {
+      this.sentinelElement.remove();
+      this.sentinelElement = null;
+    }
+    
+    this.container.removeEventListener('scroll', this.onScroll);
+  }
+}

package/src/utils/debounce.ts

@@ -0,0 +1,19 @@
+/**
+ * Debounce function to limit the rate at which a function is called
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number
+): (...args: Parameters<T>) => void {
+  let timeout: NodeJS.Timeout | null = null;
+
+  return function executedFunction(...args: Parameters<T>): void {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    
+    timeout = setTimeout(() => {
+      func.apply(this, args);
+    }, wait);
+  };
+}

package/src/utils/throttle.ts

@@ -0,0 +1,19 @@
+/**
+ * Throttle function to limit the rate at which a function is called
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  limit: number
+): (...args: Parameters<T>) => void {
+  let inThrottle: boolean;
+
+  return function executedFunction(...args: Parameters<T>): void {
+    if (!inThrottle) {
+      func.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => {
+        inThrottle = false;
+      }, limit);
+    }
+  };
+}

package/test/engine.test.ts

@@ -0,0 +1,136 @@
+import { Engine } from '../src/core/Engine';
+
+// Simple test runner for Node.js
+function describe(name: string, fn: () => void) {
+  console.log(`\nDESCRIBE: ${name}`);
+  fn();
+}
+
+function test(name: string, fn: () => void | Promise<void>) {
+  console.log(`  TEST: ${name}`);
+  
+  try {
+    const result = fn();
+    if (result instanceof Promise) {
+      return result.then(() => console.log('    PASS'))
+            .catch(err => console.error(`    FAIL: ${err.message}`));
+    } else {
+      console.log('    PASS');
+    }
+  } catch (err) {
+    console.error(`    FAIL: ${(err as Error).message}`);
+  }
+}
+
+function expect(actual: any) {
+  return {
+    toBe: (expected: any) => {
+      if (actual !== expected) {
+        throw new Error(`Expected ${actual} to be ${expected}`);
+      }
+    },
+    toBeGreaterThanOrEqual: (expected: number) => {
+      if (!(actual >= expected)) {
+        throw new Error(`Expected ${actual} to be greater than or equal to ${expected}`);
+      }
+    },
+    toBeGreaterThan: (expected: number) => {
+      if (!(actual > expected)) {
+        throw new Error(`Expected ${actual} to be greater than ${expected}`);
+      }
+    },
+    toEqual: (expected: any) => {
+      const actualStr = JSON.stringify(actual);
+      const expectedStr = JSON.stringify(expected);
+      if (actualStr !== expectedStr) {
+        throw new Error(`Expected ${actualStr} to equal ${expectedStr}`);
+      } else {
+        console.log('    PASS');
+      }
+    }
+  };
+}
+
+async function runTests() {
+  console.log('\nRunning Engine tests...\n');
+  
+  describe('Engine', () => {
+    let engine: Engine;
+
+    beforeEach(() => {
+      engine = new Engine({
+        itemHeight: 50,
+        viewportHeight: 200,
+        bufferSize: 2
+      });
+    });
+
+    afterEach(() => {
+      engine.cleanup();
+    });
+
+    test('should initialize with correct default state', () => {
+      const state = engine.getState();
+      expect(state.scrollTop).toBe(0);
+      expect(state.visibleRange.start).toBe(0);
+      expect(state.visibleRange.end).toBeGreaterThanOrEqual(0);
+      expect(state.loadedItems).toBe(0);
+      expect(state.isLoading).toBe(false);
+    });
+
+    test('should update scroll position and calculate visible range', () => {
+      engine.updateScrollPosition(100);
+      
+      const state = engine.getState();
+      expect(state.scrollTop).toBe(100);
+      // With scroll position 100 and item height 50, start should be around 2
+      expect(state.visibleRange.start).toBeGreaterThanOrEqual(0);
+    });
+
+    test('should determine when to fetch more items', () => {
+      // Initially should not need to fetch more since no fetchMore callback is set
+      const shouldFetch = engine.shouldFetchMore();
+      expect(shouldFetch).toBe(false);
+    });
+
+    test('should update dimensions correctly', () => {
+      engine.updateDimensions(300, 60);
+      
+      // Verify that the internal window manager was updated
+      // This is tested indirectly by updating scroll and checking range
+      engine.updateScrollPosition(150);
+      const state = engine.getState();
+      expect(state.scrollTop).toBe(150);
+    });
+
+    test('should handle fetchMore callback', async () => {
+      let fetchMoreCalled = false;
+      const mockFetchMore = async () => {
+        fetchMoreCalled = true;
+        return [];
+      };
+      
+      engine.setFetchMoreCallback(mockFetchMore);
+      
+      // Test that the callback is set correctly
+      // We'll test this by triggering a condition where fetchMore would be called
+      // But for this test, just verify the callback is stored
+      // @ts-ignore - accessing private property for testing
+      expect(engine.fetchMoreCallback !== null).toBe(true);
+    });
+  });
+}
+
+// Define helper functions
+function beforeEach(fn: () => void) {
+  fn();
+}
+
+function afterEach(fn: () => void) {
+  fn();
+}
+
+// Run the tests
+runTests().then(() => {
+  console.log('\nEngine tests completed.');
+});