helene
Version:
Real-time Web Apps for Node.js
119 lines (118 loc) • 4.47 kB
TypeScript
/**
* IDBStorage - High-Performance IndexedDB Storage Implementation
*
* This module provides an optimized IndexedDB-based storage implementation with several
* performance enhancements over basic storage approaches. It's designed to handle large
* datasets efficiently while maintaining data integrity and providing fast access times.
*
* ## Key Features & Optimizations
*
* ### 1. Smart Chunking Strategy
* - Documents are split into 256KB chunks for optimal IndexedDB performance
* - Smaller chunks provide better granularity for partial updates
* - Efficient chunk management reduces memory overhead
*
* ### 2. LRU Caching Layer
* - In-memory cache for frequently accessed documents (default: 50 documents)
* - Immediate cache updates on writes for instant read performance
* - LRU eviction prevents memory bloat in long-running applications
* - Cache-first reads eliminate IndexedDB hits for hot data
*
* ### 3. Batch Write Operations
* - Write operations are batched with configurable delay (default: 100ms)
* - Reduces IndexedDB transaction overhead significantly
* - Async writes with immediate cache updates for perceived performance
* - Manual flush capability for critical operations
*
* ### 4. Optimized Append Operations
* - Efficient append operations that leverage batched writes
* - Cache-first approach for maximum performance when data is already loaded
* - Minimal disk reads - only when data isn't cached
* - Consistent behavior with write operations through unified batching system
*
* ### 5. Robust Error Handling
* - Per-chunk error recovery for corrupted data
* - Fallback mechanisms for data integrity
* - Comprehensive logging for debugging
*
* ## Performance Benefits
*
* - **Append Operations**: Cache-hit appends are O(1), cache-miss appends require one read + batched write
* - **Read Performance**: Cache hits are near-instantaneous
* - **Write Performance**: Batched + async writes reduce UI blocking
* - **Memory Usage**: Bounded cache with LRU eviction prevents memory leaks
* - **Chunking Benefits**: Better handling of large documents and partial updates
*
* ## Usage Examples
*
* ```typescript
* const storage = new IDBStorage()
*
* // Basic operations - all return immediately from cache when possible
* await storage.write('document', 'large text data...')
* const data = await storage.read('document') // Cache hit if recently written
*
* // Efficient append operations
* await storage.append('log', 'new log entry\n') // O(1) operation
*
* // Force pending writes to complete
* await storage.flush()
*
* // Clear all data
* await storage.clear()
* ```
*
* ## Architecture
*
* The implementation is split into focused, testable components:
*
* - **DocumentCache**: Manages LRU caching with configurable size limits
* - **BatchWriter**: Handles write batching and scheduling with error recovery
* - **IDBStorage**: Main class coordinating all components with clean separation of concerns
*
* ## IndexedDB Schema
*
* - **Database**: `helene_data`
* - **Store**: `chunks` with keyPath `id`
* - **Index**: `docId` for efficient document chunk lookup
*
* Each chunk contains:
* - `id`: Unique chunk identifier (`${docId}-${chunkIndex}`)
* - `docId`: Document identifier with namespace prefix
* - `chunkIndex`: Ordering index for chunk reassembly
* - `content`: Actual data
*
* ## Browser Compatibility
*
* - Requires IndexedDB support (all modern browsers)
* - Uses modern async/await syntax
* - No external dependencies beyond 'idb' helper library
* - Graceful error handling for storage quota limitations
*/
import { IStorage } from '../types';
export declare const CHUNK_SIZE: number;
export declare const STORE_NAME = "chunks";
export declare const DB_NAME = "helene_data";
export declare const DB_VERSION = 1;
export declare class IDBStorage implements IStorage {
private readonly prefix;
private db;
private cache;
private batchWriter;
private readonly chunkSize;
constructor(options?: {
cacheSize?: number;
batchDelay?: number;
chunkSize?: number;
});
private getDB;
read(name: string): Promise<string>;
write(name: string, data: string): Promise<void>;
append(name: string, data: string): Promise<void>;
flush(): Promise<void>;
clear(): Promise<void>;
private readFromDisk;
private writeToDisk;
private createChunks;
private deleteAndWriteChunks;
}