@dephub/cache/dist/core/file.d.ts

Simple file-based cache with persistent storage for Node.js applications

import { CacheOptions, CacheValue } from './types.js';
/**
 * File-based persistent cache with asynchronous operations.
 *
 * All methods are asynchronous and automatically persist changes to disk.
 * The cache is automatically loaded from file on instantiation.
 * Values are stored as JSON, supporting only string, number, and boolean types.
 *
 * @example
 * const cache = new FileCache({ name: 'my-cache.json' });
 * await cache.set('key', 'value'); // Automatically saves to file
 * const value = await cache.get('key'); // Loaded from memory cache
 */
export declare class FileCache {
    #private;
    /**
     * Creates a new file-based cache instance.
     *
     * @param options - Configuration options for the cache file
     */
    constructor(options?: CacheOptions);
    /**
     * Sets a value in the cache and persists to file.
     *
     * @param key - Cache key (must be a string)
     * @param value - Value to store (string, number, or boolean)
     * @returns Promise that resolves with the cache instance for chaining
     * @throws {Error} If cache initialization fails
     * @throws {Error} If file write operation fails
     * @throws {Error} If key is not a string or value is invalid type
     */
    set(key: string, value: CacheValue): Promise<this>;
    /**
     * Deletes a key from the cache and persists the change to file.
     *
     * @param key - The key to delete
     * @returns Promise that resolves with true if the key was found and deleted, false otherwise
     * @throws {Error} If cache initialization fails
     * @throws {Error} If file write operation fails
     */
    delete(key: string): Promise<boolean>;
    /**
     * Clears all entries from the cache and persists the change to file.
     *
     * @returns Promise that resolves when the cache is cleared
     * @throws {Error} If file write operation fails
     */
    clear(): Promise<void>;
    /**
     * Gets a value from the cache.
     *
     * @param key - The key to look up
     * @returns Promise that resolves with the value if found, undefined otherwise
     * @throws {Error} If cache initialization fails
     */
    get(key: string): Promise<CacheValue | undefined>;
    /**
     * Checks if a key exists in the cache.
     *
     * @param key - The key to check
     * @returns Promise that resolves with true if the key exists, false otherwise
     * @throws {Error} If cache initialization fails
     */
    has(key: string): Promise<boolean>;
    /**
     * Returns the number of entries in the cache.
     *
     * @returns Promise that resolves with the number of entries
     * @throws {Error} If cache initialization fails
     */
    size(): Promise<number>;
    /**
     * Returns an array of all keys in the cache.
     *
     * @returns Promise that resolves with an array of keys
     * @throws {Error} If cache initialization fails
     */
    keys(): Promise<string[]>;
    /**
     * Returns an array of all values in the cache.
     *
     * @returns Promise that resolves with an array of values
     * @throws {Error} If cache initialization fails
     */
    values(): Promise<CacheValue[]>;
    /**
     * Returns an array of [key, value] pairs in the cache.
     *
     * @returns Promise that resolves with an array of entries
     * @throws {Error} If cache initialization fails
     */
    entries(): Promise<[string, CacheValue][]>;
    /**
     * Executes a callback for each entry in the cache.
     *
     * @param callback - The function to call for each entry, receiving value and key
     * @returns Promise that resolves when the iteration is complete
     * @throws {Error} If cache initialization fails
     */
    forEach(callback: (value: CacheValue, key: string) => void): Promise<void>;
}