@socketsecurity/lib/dist/cache-with-ttl.d.ts

Core utilities and infrastructure for Socket.dev security tools

export interface TtlCacheOptions {
    /**
     * Time-to-live in milliseconds.
     * @default 5 * 60 * 1000 (5 minutes)
     */
    ttl?: number | undefined;
    /**
     * Enable in-memory memoization for hot data.
     * @default true
     */
    memoize?: boolean | undefined;
    /**
     * Custom cache key prefix.
     * Must not contain wildcards (*).
     * Use clear({ prefix: "pattern*" }) for wildcard matching instead.
     *
     * @default 'ttl-cache'
     * @throws {TypeError} If prefix contains wildcards
     *
     * @example
     * // Valid
     * createTtlCache({ prefix: 'socket-sdk' })
     * createTtlCache({ prefix: 'my-app:cache' })
     *
     * @example
     * // Invalid - throws TypeError
     * createTtlCache({ prefix: 'socket-*' })
     */
    prefix?: string | undefined;
}
export interface TtlCacheEntry<T> {
    data: T;
    expiresAt: number;
}
export interface ClearOptions {
    /**
     * Only clear in-memory memoization cache, not persistent cache.
     * Useful for forcing a refresh of cached data without removing it from disk.
     *
     * @default false
     */
    memoOnly?: boolean | undefined;
}
export interface TtlCache {
    /**
     * Get cached data without fetching.
     * Returns undefined if not found or expired.
     *
     * @param key - Cache key (must not contain wildcards)
     * @throws {TypeError} If key contains wildcards (*)
     */
    get<T>(key: string): Promise<T | undefined>;
    /**
     * Get all cached entries matching a pattern.
     * Supports wildcards (*) for flexible matching.
     *
     * @param pattern - Key pattern (supports * wildcards, or use '*' for all entries)
     * @returns Map of matching entries (key -> value)
     *
     * @example
     * // Get all organization entries
     * const orgs = await cache.getAll<OrgData>('organizations:*')
     * for (const [key, org] of orgs) {
     *   console.log(`${key}: ${org.name}`)
     * }
     *
     * @example
     * // Get all entries with this cache's prefix
     * const all = await cache.getAll<any>('*')
     */
    getAll<T>(pattern: string): Promise<Map<string, T>>;
    /**
     * Get cached data or fetch and cache if missing/expired.
     *
     * @param key - Cache key (must not contain wildcards)
     */
    getOrFetch<T>(key: string, fetcher: () => Promise<T>): Promise<T>;
    /**
     * Set cached data with TTL.
     *
     * @param key - Cache key (must not contain wildcards)
     * @throws {TypeError} If key contains wildcards (*)
     */
    set<T>(key: string, data: T): Promise<void>;
    /**
     * Delete a specific cache entry.
     *
     * @param key - Cache key (must not contain wildcards)
     * @throws {TypeError} If key contains wildcards (*)
     */
    delete(key: string): Promise<void>;
    /**
     * Delete all cache entries matching a pattern.
     * Supports wildcards (*) for flexible matching.
     *
     * @param pattern - Key pattern (supports * wildcards, or omit to delete all)
     * @returns Number of entries deleted
     *
     * @example
     * // Delete all entries with this cache's prefix
     * await cache.deleteAll()
     *
     * @example
     * // Delete entries matching prefix
     * await cache.deleteAll('organizations')
     *
     * @example
     * // Delete entries with wildcard pattern
     * await cache.deleteAll('scans:abc*')
     * await cache.deleteAll('npm/lodash/*')
     */
    deleteAll(pattern?: string | undefined): Promise<number>;
    /**
     * Clear all cache entries (like Map.clear()).
     * Optionally clear only in-memory cache.
     *
     * @param options - Optional configuration
     * @param options.memoOnly - If true, only clears in-memory cache
     *
     * @example
     * // Clear everything (memory + disk)
     * await cache.clear()
     *
     * @example
     * // Clear only in-memory cache (force refresh)
     * await cache.clear({ memoOnly: true })
     */
    clear(options?: ClearOptions | undefined): Promise<void>;
}
/**
 * Create a TTL-based cache instance.
 */
export declare function createTtlCache(options?: TtlCacheOptions): TtlCache;