axiodb/lib/Services/Index/IndexCache.service.d.ts

The Pure JavaScript Alternative to SQLite. Embedded NoSQL database for Node.js with MongoDB-style queries, zero native dependencies, built-in InMemoryCache, and web GUI. Perfect for desktop apps, CLI tools, and embedded systems. No compilation, no platfor

/**
 * Structure of index data stored in index files
 */
interface IndexData {
    fieldName: string;
    indexEntries: {
        [value: string]: string[];
    };
}
/**
 * In-memory cache for index data
 *
 * Features:
 * - Eagerly loads all indexes on collection initialization
 * - Keeps indexes in both memory (speed) and disk (persistence)
 * - Cold start recovery: Loads from disk on cache miss
 * - Thread-safe with simple lock mechanism
 * - Dual-write: Updates both memory and disk atomically
 *
 * @example
 * ```typescript
 * const indexCache = new IndexCache('/path/to/collection');
 * await indexCache.loadAllIndexes();  // Eager load
 * const indexData = await indexCache.getIndex('email');  // O(1) memory access
 * ```
 */
export declare class IndexCache {
    private cache;
    private readonly indexFolderPath;
    private readonly indexMetaPath;
    private readonly fileManager;
    private readonly converter;
    private locks;
    private cleanupInterval;
    private static readonly MIN_TTL_MS;
    private static readonly MAX_TTL_MS;
    private static readonly CLEANUP_INTERVAL_MS;
    constructor(collectionPath: string);
    /**
     * Generates a random TTL between 5-15 minutes
     * Randomization prevents cache stampede (thundering herd problem)
     */
    private generateRandomTTL;
    /**
     * Starts periodic cleanup of expired cache entries
     */
    private startCleanupInterval;
    /**
     * Removes all expired entries from cache
     */
    private cleanupExpiredEntries;
    /**
     * Checks if a cached entry is expired
     */
    private isExpired;
    /**
     * Eagerly loads all indexes into memory
     * Called during collection initialization for maximum query performance
     *
     * @returns Promise that resolves when all indexes are loaded
     */
    loadAllIndexes(): Promise<void>;
    /**
     * Gets index data for a specific field
     * Returns from memory if available, loads from disk if not (cold start recovery)
     *
     * @param fieldName - The indexed field name (e.g., 'email', 'age')
     * @returns Index data or null if index doesn't exist
     */
    getIndex(fieldName: string): Promise<IndexData | null>;
    /**
     * Updates an index in both memory and disk atomically
     * Thread-safe with simple lock mechanism
     *
     * @param fieldName - The indexed field name
     * @param indexData - The updated index data
     * @returns True if update successful, false otherwise
     */
    updateIndex(fieldName: string, indexData: IndexData): Promise<boolean>;
    /**
     * Invalidates a specific index (removes from memory)
     * Disk copy remains for persistence and recovery
     *
     * @param fieldName - The indexed field name to invalidate
     */
    invalidateIndex(fieldName: string): Promise<void>;
    /**
     * Invalidates all indexes (removes all from memory)
     * Used when indexes are dropped or collection is cleared
     * Disk copies remain for recovery
     */
    invalidateAll(): Promise<void>;
    /**
     * Simple lock acquisition for thread safety
     * Waits if another operation is currently holding the lock
     *
     * @param key - The lock key (typically field name)
     * @private
     */
    private acquireLock;
    /**
     * Releases the lock for a specific key
     *
     * @param key - The lock key to release
     * @private
     */
    private releaseLock;
    /**
     * Gets current cache statistics for monitoring
     *
     * @returns Object containing cache size and loaded index count
     */
    getCacheStats(): {
        indexCount: number;
        fieldNames: string[];
    };
}
export {};