@valkey/valkey-glide/build-ts/ClientSideCache.js

General Language Independent Driver for the Enterprise (GLIDE) for Valkey

"use strict";
/**
 * Copyright Valkey GLIDE Project Contributors - SPDX Identifier: Apache-2.0
 */
Object.defineProperty(exports, "__esModule", { value: true });
exports.ClientSideCache = void 0;
const crypto_1 = require("crypto");
/**
 * Configuration class for client-side caching.
 *
 * Client-side caching reduces network round-trips and server load by storing
 * frequently accessed data locally on the client. This class provides
 * configurable TTL-based expiration, multiple eviction policies, and
 * comprehensive metrics tracking.
 *
 * @example
 * ```typescript
 * // Create cache with auto-generated ID
 * const cache = ClientSideCache.create(1024, 60000); // 1MB cache, 1 min TTL
 *
 * // Create cache with custom configuration
 * const customCache = new ClientSideCache({
 *   maxCacheKb: 2048,
 *   entryTtlMs: 300000,
 *   evictionPolicy: EvictionPolicy.LFU,
 *   enableMetrics: true
 * });
 * ```
 */
class ClientSideCache {
    /**
     * @internal
     * Unique identifier for the cache instance. Auto-generated using UUID.
     */
    cacheId;
    /**
     * Maximum memory limit for the cache in kilobytes.
     */
    maxCacheKb;
    /**
     * Time-To-Live for cache entries in milliseconds. 0 means no expiration.
     */
    entryTtlMs;
    /**
     * Optional eviction policy to use when cache reaches memory limit.
     */
    evictionPolicy;
    /**
     * Whether metrics collection is enabled for this cache.
     */
    enableMetrics;
    /**
     * Creates a new ClientSideCache instance.
     *
     * @param config - Configuration options for the cache
     * @throws {Error} If maxCacheKb is not a positive number
     * @throws {Error} If entryTtlMs is negative
     */
    constructor(config) {
        if (config.maxCacheKb <= 0) {
            throw new Error("maxCacheKb must be a positive number");
        }
        if (config.entryTtlMs < 0) {
            throw new Error("entryTtlMs must be non-negative (0 = no expiration)");
        }
        this.cacheId = (0, crypto_1.randomUUID)();
        this.maxCacheKb = config.maxCacheKb;
        this.entryTtlMs = config.entryTtlMs;
        this.evictionPolicy = config.evictionPolicy;
        this.enableMetrics = config.enableMetrics ?? false;
    }
    /**
     * Factory method to create a ClientSideCache with auto-generated cache ID.
     *
     * @param maxCacheKb - Maximum memory limit for the cache in kilobytes
     * @param entryTtlMs - TTL for cache entries in milliseconds. Use 0 for no expiration.
     * @param options - Optional configuration options
     * @returns A new ClientSideCache instance with auto-generated cache ID
     * @throws {Error} If maxCacheKb is not a positive number
     * @throws {Error} If entryTtlMs is negative
     *
     * @example
     * ```typescript
     * // Simple cache with 1MB limit and no TTL
     * const cache = ClientSideCache.create(1024, 0);
     *
     * // Cache with TTL and LFU eviction
     * const cacheWithOptions = ClientSideCache.create(2048, 300000, {
     *   evictionPolicy: EvictionPolicy.LFU,
     *   enableMetrics: false
     * });
     * ```
     */
    static create(maxCacheKb, entryTtlMs, options) {
        return new ClientSideCache({
            maxCacheKb,
            entryTtlMs,
            evictionPolicy: options?.evictionPolicy,
            enableMetrics: options?.enableMetrics,
        });
    }
}
exports.ClientSideCache = ClientSideCache;