axiodb
Version:
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
142 lines (141 loc) • 5.74 kB
TypeScript
/**
* @description This class is responsible for caching data in memory with smart TTL management
* @class InMemoryCache
* @export InMemoryCache
* @version 2.0.0
* @since 23 April 2025
*
* Features:
* - Random TTL per entry (5-15 minutes) to prevent cache stampede
* - Selective cache invalidation by collection/document
* - Auto-cleanup of expired entries
**/
export declare class InMemoryCache {
private readonly ttl;
private cacheObject;
private tempSearchQuery;
private readonly autoResetCacheInterval;
/**
* Creates a new instance of the cache operation class
* @param TTL - Time to live in seconds for cache entries. Defaults to 86400 seconds (24 hours)
*/
constructor(TTL?: string | number);
/**
* Generates a random TTL between 5-15 minutes
* This prevents cache stampede (thundering herd problem)
*
* @returns Random TTL in milliseconds
* @private
*/
private generateRandomTTL;
/**
* Sets a value in the cache with the specified key.
* Each cache entry gets a random TTL (5-15 minutes) to prevent cache stampede.
*
* OPTIMIZED:
* - Immediate caching without threshold
* - Random TTL per entry prevents synchronized expiration
* - Pre-computed expiration time for O(1) validation
*
* @param key - The unique identifier for the cached item
* @param value - The value to be stored in the cache
* @returns A Promise that resolves when the value has been cached
*
* @example
* ```typescript
* await cache.setCache('user-123', { name: 'John', age: 30 });
* ```
*/
setCache(key: string, value: any): Promise<boolean>;
setTempSearchQuery(queryString: any): Promise<boolean>;
/**
* Retrieves a value from the cache using the specified key
* Validates TTL expiration and auto-deletes expired entries
*
* @param key - The unique identifier to lookup in the cache
* @returns A Promise that resolves to the cached value if found and not expired, false otherwise
*/
getCache(key: string): Promise<any | boolean>;
/**
* Clears all cached data stored in memory.
* Resets the cache object and temporary search query array to their initial empty states.
*
* @returns A Promise that resolves to true when the cache has been successfully cleared.
*/
clearAllCache(): Promise<boolean>;
/**
* Invalidates all cache entries for a specific collection
* Used for selective cache invalidation to preserve unrelated caches
*
* @param collectionPath - The filesystem path to the collection (e.g., "/db/users")
* @returns A Promise that resolves to true when invalidation is complete
*
* @example
* ```typescript
* await cache.invalidateByCollection('/db/users');
* // Only /db/users cache cleared, /db/orders cache remains
* ```
*/
invalidateByCollection(collectionPath: string): Promise<boolean>;
/**
* Invalidates cache entries that could be affected by a single document update/delete
*
* Strategy: Conservative - invalidates entire collection cache because we can't
* determine which queries matched this specific document without re-executing them.
*
* @param collectionPath - The filesystem path to the collection
* @param documentId - The ID of the document that was modified (used for logging/future optimization)
* @returns A Promise that resolves to true when invalidation is complete
*
* @example
* ```typescript
* await cache.invalidateByDocument('/db/users', 'user123');
* ```
*/
invalidateByDocument(collectionPath: string, documentId: string): Promise<boolean>;
/**
* Invalidates cache entries affected by multiple document updates/deletes
*
* @param collectionPath - The filesystem path to the collection
* @param documentIds - Array of document IDs that were modified
* @returns A Promise that resolves to true when invalidation is complete
*
* @example
* ```typescript
* await cache.invalidateByDocuments('/db/users', ['user1', 'user2', 'user3']);
* ```
*/
invalidateByDocuments(collectionPath: string, documentIds: string[]): Promise<boolean>;
/**
* Retrieves detailed information about the current state of the cache.
*
* This method calculates:
* - Total estimated size of the cache in bytes (including keys, values, and timestamps)
* - Available system memory (in Node.js environments)
* - Number of items currently in the cache
* - Number of temporary search queries stored
*
* @returns {Promise<any>} A promise that resolves to an object containing cache details:
* - cacheSizeInBytes: Estimated size of the cache in bytes
* - availableMemoryInBytes: Available system memory in bytes (or -1 if not in Node.js)
* - cacheItemCount: Number of items in the cache
* - tempQueryCount: Number of temporary search queries
* - Or false if an error occurs during calculation
*
* @throws {Error} Logs the error to console but doesn't throw; returns false instead
*/
getCacheDetails(): Promise<any>;
/**
* Sets up an automatic cache reset mechanism.
* Periodically cleans up expired cache entries and old search query tracking.
*
* OPTIMIZED: Uses pre-computed expiresAt for O(1) expiration checks
* instead of computing time differences.
*
* @private
* @returns {Promise<void>} A promise that resolves when the interval is set up.
*/
private autoResetCache;
}
declare const _default: InMemoryCache;
export default _default;