@comic-vine/in-memory-store/lib/index.d.cts

In-memory store implementations for Comic Vine client caching, deduplication, and rate limiting

import { CacheStore, DedupeStore, RateLimitStore, RateLimitConfig, AdaptiveRateLimitStore as AdaptiveRateLimitStore$1, AdaptiveConfigSchema, RequestPriority } from '@comic-vine/client';
export { AdaptiveConfig, CacheStore, DedupeStore, AdaptiveRateLimitStore as IAdaptiveRateLimitStore, RateLimitConfig, RateLimitStore, RequestPriority } from '@comic-vine/client';
import { z } from 'zod';

interface InMemoryCacheStoreOptions {
    /** Cleanup interval in milliseconds. Set to 0 to disable automatic cleanup. Default: 60000 (1 minute) */
    cleanupIntervalMs?: number;
    /** Maximum number of items to store. When exceeded, least recently used items are evicted. Default: 1000 */
    maxItems?: number;
    /** Maximum memory usage in bytes (rough estimate). When exceeded, least recently used items are evicted. Default: 50MB */
    maxMemoryBytes?: number;
    /** When evicting items, remove this percentage of LRU items. Default: 0.1 (10%) */
    evictionRatio?: number;
}
declare class InMemoryCacheStore<T = unknown> implements CacheStore<T> {
    private cache;
    private cleanupInterval?;
    private readonly maxItems;
    private readonly maxMemoryBytes;
    private readonly evictionRatio;
    private totalSize;
    constructor(options?: InMemoryCacheStoreOptions);
    get(hash: string): Promise<T | undefined>;
    set(hash: string, value: T, ttlSeconds: number): Promise<void>;
    delete(hash: string): Promise<void>;
    clear(): Promise<void>;
    /**
     * Get statistics about cache usage
     */
    getStats(): {
        totalItems: number;
        expired: number;
        memoryUsageBytes: number;
        maxItems: number;
        maxMemoryBytes: number;
        memoryUtilization: number;
        itemUtilization: number;
    };
    /**
     * Clean up expired cache entries
     */
    cleanup(): void;
    /**
     * Enforce memory and item count limits using LRU eviction
     */
    private enforceMemoryLimits;
    /**
     * Evict the least recently used items
     */
    private evictLRUItems;
    /**
     * Calculate rough memory usage
     */
    private calculateMemoryUsage;
    /**
     * Get items sorted by last accessed time (for debugging/monitoring)
     */
    getLRUItems(limit?: number): Array<{
        hash: string;
        lastAccessed: Date;
        size: number;
    }>;
    /**
     * Destroy the cache and cleanup resources
     */
    destroy(): void;
    /**
     * Estimate the size in bytes of a cache entry (key + value + metadata)
     */
    private estimateEntrySize;
}

interface InMemoryDedupeStoreOptions {
    jobTimeoutMs?: number;
    cleanupIntervalMs?: number;
}
declare class InMemoryDedupeStore<T = unknown> implements DedupeStore<T> {
    private jobs;
    private readonly jobTimeoutMs;
    private cleanupInterval?;
    private totalJobsProcessed;
    private destroyed;
    constructor({ 
    /** Job timeout in milliseconds. Defaults to 5 minutes. */
    jobTimeoutMs, 
    /** Cleanup interval in milliseconds. Defaults to 1 minute. */
    cleanupIntervalMs, }?: InMemoryDedupeStoreOptions);
    waitFor(hash: string): Promise<T | undefined>;
    register(hash: string): Promise<string>;
    complete(hash: string, value: T): Promise<void>;
    fail(hash: string, error: Error): Promise<void>;
    isInProgress(hash: string): Promise<boolean>;
    /**
     * Get statistics about current dedupe jobs
     */
    getStats(): {
        activeJobs: number;
        totalJobsProcessed: number;
        expiredJobs: number;
        oldestJobAgeMs: number;
    };
    /**
     * Clean up expired jobs
     */
    cleanup(): void;
    /**
     * Clear all jobs
     */
    clear(): void;
    /**
     * Destroy the store and clean up resources
     */
    destroy(): void;
}

interface InMemoryRateLimitStoreOptions {
    defaultConfig?: RateLimitConfig;
    resourceConfigs?: Map<string, RateLimitConfig>;
    cleanupIntervalMs?: number;
}
declare class InMemoryRateLimitStore implements RateLimitStore {
    private limits;
    private defaultConfig;
    private resourceConfigs;
    private cleanupInterval?;
    private totalRequests;
    constructor({ 
    /** Global/default rate-limit config applied when a resource-specific override is not provided. */
    defaultConfig, 
    /** Optional per-resource overrides. */
    resourceConfigs, 
    /** Cleanup interval in milliseconds. Defaults to 1 minute. */
    cleanupIntervalMs, }?: InMemoryRateLimitStoreOptions);
    canProceed(resource: string): Promise<boolean>;
    record(resource: string): Promise<void>;
    getStatus(resource: string): Promise<{
        remaining: number;
        resetTime: Date;
        limit: number;
    }>;
    reset(resource: string): Promise<void>;
    getWaitTime(resource: string): Promise<number>;
    /**
     * Set rate limit configuration for a specific resource
     */
    setResourceConfig(resource: string, config: RateLimitConfig): void;
    /**
     * Get rate limit configuration for a resource
     */
    getResourceConfig(resource: string): RateLimitConfig;
    /**
     * Get statistics for all resources
     */
    getStats(): {
        totalResources: number;
        activeResources: number;
        rateLimitedResources: number;
        totalRequests: number;
    };
    /**
     * Clear all rate limit data
     */
    clear(): void;
    /**
     * Clean up expired requests for all resources
     */
    cleanup(): void;
    /**
     * Destroy the store and clean up resources
     */
    destroy(): void;
    private getOrCreateRateLimitInfo;
    private cleanupExpiredRequests;
}

interface AdaptiveRateLimitStoreOptions {
    adaptiveConfig?: Partial<z.input<typeof AdaptiveConfigSchema>>;
}
/**
 * In-memory rate limiting store with adaptive priority-based capacity allocation
 */
declare class AdaptiveRateLimitStore implements AdaptiveRateLimitStore$1 {
    private activityMetrics;
    private capacityCalculator;
    private lastCapacityUpdate;
    private cachedCapacity;
    constructor(options?: AdaptiveRateLimitStoreOptions);
    canProceed(resource: string, priority?: RequestPriority): Promise<boolean>;
    record(resource: string, priority?: RequestPriority): Promise<void>;
    getStatus(resource: string): Promise<{
        remaining: number;
        resetTime: Date;
        limit: number;
        adaptive?: {
            userReserved: number;
            backgroundMax: number;
            backgroundPaused: boolean;
            recentUserActivity: number;
            reason: string;
        };
    }>;
    reset(resource: string): Promise<void>;
    getWaitTime(resource: string, priority?: RequestPriority): Promise<number>;
    private calculateCurrentCapacity;
    private getOrCreateActivityMetrics;
    private getCurrentUsage;
    private cleanupOldRequests;
    private getResourceLimit;
    private getDefaultCapacity;
}

export { AdaptiveRateLimitStore, type AdaptiveRateLimitStoreOptions, InMemoryCacheStore, type InMemoryCacheStoreOptions, InMemoryDedupeStore, type InMemoryDedupeStoreOptions, InMemoryRateLimitStore, type InMemoryRateLimitStoreOptions };