/**
 * ID Length Cache Service
 *
 * Provides efficient caching for ID hash length calculation.
 * This service avoids querying element count on every ID generation
 * by caching the count and calculated length with periodic invalidation.
 *
 * The cache is automatically invalidated:
 * - After a configurable TTL (default: 60 seconds)
 * - When explicitly refreshed
 * - After a significant number of creates (growth threshold)
 */
import type { StorageBackend } from '@stoneforge/storage';
/**
 * Configuration for the ID length cache
 */
export interface IdLengthCacheConfig {
    /**
     * Time-to-live for cached values in milliseconds.
     * After this time, the cache will be refreshed on next access.
     * Default: 60000 (60 seconds)
     */
    ttlMs?: number;
    /**
     * Minimum number of element creations before triggering a refresh.
     * This helps catch rapid growth before TTL expires.
     * Default: 100
     */
    growthThreshold?: number;
    /**
     * Minimum hash length to use, regardless of element count.
     * Default: 4 (provides reasonable collision resistance)
     */
    minLength?: number;
}
/**
 * Statistics for cache monitoring
 */
export interface IdLengthCacheStats {
    /** Current element count */
    elementCount: number;
    /** Current hash length */
    hashLength: number;
    /** Number of cache hits since creation */
    hits: number;
    /** Number of cache misses (refreshes) since creation */
    misses: number;
    /** Cache hit rate (0-1) */
    hitRate: number;
    /** Time since last refresh in milliseconds */
    ageMs: number;
    /** Whether cache is currently stale */
    isStale: boolean;
}
/**
 * Service for caching ID hash length calculations.
 *
 * This service provides efficient access to the optimal ID hash length
 * without querying the database on every ID generation.
 *
 * @example
 * ```typescript
 * const cache = createIdLengthCache(storage);
 *
 * // Get optimal hash length for ID generation
 * const hashLength = cache.getHashLength();
 *
 * // Notify cache of new element creation (for growth tracking)
 * cache.notifyCreate();
 *
 * // Force refresh if needed
 * cache.refresh();
 * ```
 */
export declare class IdLengthCache {
    private readonly db;
    private cache;
    private hits;
    private misses;
    private readonly ttlMs;
    private readonly growthThreshold;
    private readonly minLength;
    constructor(db: StorageBackend, config?: IdLengthCacheConfig);
    /**
     * Get the optimal hash length for ID generation.
     *
     * Returns the cached hash length if valid, otherwise refreshes
     * the cache first. This is the main method to call when generating IDs.
     *
     * @returns The optimal hash length (3-8)
     */
    getHashLength(): number;
    /**
     * Get the cached element count.
     *
     * This is the element count at the last refresh, not necessarily
     * the current count in the database.
     *
     * @returns The cached element count
     */
    getElementCount(): number;
    /**
     * Notify the cache that a new element was created.
     *
     * This increments the internal counter and may trigger a refresh
     * if the growth threshold is exceeded.
     */
    notifyCreate(): void;
    /**
     * Force a cache refresh.
     *
     * Queries the database for the current element count and
     * recalculates the optimal hash length.
     */
    refresh(): void;
    /**
     * Check if the cache is stale and needs refresh.
     */
    isStale(): boolean;
    /**
     * Clear the cache, forcing a refresh on next access.
     */
    clear(): void;
    /**
     * Get cache statistics for monitoring.
     */
    getStats(): IdLengthCacheStats;
    /**
     * Calculate the optimal hash length for an element count.
     *
     * Applies the minimum length constraint.
     */
    private calculateLength;
}
/**
 * Create a new IdLengthCache instance.
 *
 * @param db - Storage backend for querying element count
 * @param config - Optional cache configuration
 * @returns A new IdLengthCache instance
 *
 * @example
 * ```typescript
 * // Basic usage
 * const cache = createIdLengthCache(storage);
 *
 * // With custom configuration
 * const cache = createIdLengthCache(storage, {
 *   ttlMs: 30000, // 30 second TTL
 *   growthThreshold: 50, // Refresh after 50 creates
 *   minLength: 5, // Minimum 5-character hashes
 * });
 * ```
 */
export declare function createIdLengthCache(db: StorageBackend, config?: IdLengthCacheConfig): IdLengthCache;
//# sourceMappingURL=id-length-cache.d.ts.map