@plyaz/types 1.5.0 → 1.5.2

package/dist/testing/features/cache/types.d.ts

@@ -42,130 +42,203 @@ export interface CacheStrategyTestConfig {
     cleanup?: (strategy: CacheStrategy) => Promise<void>;
 }
 /**
- * Cache interface for testing
- * @interface Cache
- * @typeParam T - Type of cached values
+ * Generic cache interface for testing different cache implementations.
+ * Provides standard cache operations for testing.
+ *
+ * @template T - Type of cached values
+ *
+ * @example
+ * ```typescript
+ * const cache: Cache<string> = {
+ *   get: async (key) => storage.get(key),
+ *   set: async (key, value, ttl) => storage.set(key, value, ttl),
+ *   has: async (key) => storage.has(key),
+ *   delete: async (key) => storage.delete(key),
+ *   clear: async () => storage.clear(),
+ *   size: async () => storage.size(),
+ *   keys: async () => storage.keys(),
+ *   values: async () => storage.values(),
+ *   entries: async () => storage.entries()
+ * };
+ * ```
  */
 export interface Cache<T = unknown> {
-    /** Get value from cache */
     get(key: string): Promise<T | null>;
-    /** Set value in cache */
     set(key: string, value: T, ttl?: number): Promise<void>;
-    /** Delete value from cache */
     delete(key: string): Promise<boolean>;
-    /** Clear all cache entries */
     clear(): Promise<void>;
-    /** Get cache size */
     size(): Promise<number>;
-    /** Get cache statistics */
     getStats?(): CacheStats;
-    /** Get raw cache entry */
     getRaw?(key: string): Promise<CacheEntry<T> | null>;
-    /** Set eviction callback */
     onEviction?(callback: (key: string, value: T) => void): void;
-    /** Restore cache state (internal) */
     __restore?: () => void;
 }
 /**
- * Cache eviction configuration
- * @interface EvictionConfig
+ * Configuration for cache eviction policies.
+ * Defines rules for removing cached entries when limits are reached.
+ *
+ * @example
+ * ```typescript
+ * const evictionConfig: EvictionConfig = {
+ *   strategy: 'LRU',
+ *   maxSize: 1000,
+ *   maxAge: 60000, // 1 minute
+ *   onEvict: (key, value) => {
+ *     console.log(`Evicted ${key}`);
+ *   }
+ * };
+ * ```
  */
 export interface EvictionConfig {
-    /** Maximum cache size */
     maxSize: number;
-    /** Eviction policy */
     evictionPolicy: 'LRU' | 'LFU' | 'FIFO';
-    /** Number of items to add */
     itemsToAdd: number;
-    /** Expected evicted keys */
     expectedEvictions: string[];
 }
 /**
- * Cache concurrency testing options
- * @interface ConcurrencyOptions
+ * Options for testing cache behavior under concurrent access.
+ * Configures parallel operations and race condition testing.
+ *
+ * @example
+ * ```typescript
+ * const concurrencyOptions: ConcurrencyOptions = {
+ *   workers: 10,
+ *   operationsPerWorker: 100,
+ *   operationMix: {
+ *     get: 0.7,
+ *     set: 0.2,
+ *     delete: 0.1
+ *   },
+ *   conflictResolution: 'last-write-wins'
+ * };
+ * ```
  */
 export interface ConcurrencyOptions {
-    /** Number of operations */
     operations: number;
-    /** Concurrency level */
     concurrency: number;
-    /** Type of operations */
     operationType: 'read' | 'write' | 'mixed';
 }
 /**
- * TTL testing options
- * @interface TTLOptions
+ * Options for testing time-to-live (TTL) functionality.
+ * Configures expiration behavior and cleanup testing.
+ *
+ * @example
+ * ```typescript
+ * const ttlOptions: TTLOptions = {
+ *   defaultTTL: 5000,
+ *   checkInterval: 1000,
+ *   extendOnAccess: true,
+ *   variableTTL: true,
+ *   minTTL: 100,
+ *   maxTTL: 60000
+ * };
+ * ```
  */
 export interface TTLOptions {
-    /** Cache key */
     key: string;
-    /** Cache value */
     value: unknown;
-    /** Time to live */
     ttl: number;
-    /** Check intervals */
     checkIntervals: number[];
 }
 /**
- * TTL test result
- * @interface TTLResult
+ * Results from TTL functionality testing.
+ * Contains metrics and validation outcomes for expiration behavior.
+ *
+ * @example
+ * ```typescript
+ * const ttlResult: TTLResult = {
+ *   totalEntries: 100,
+ *   expiredEntries: 45,
+ *   averageLifetime: 4500,
+ *   expirationAccuracy: 0.98,
+ *   cleanupEfficiency: 0.95,
+ *   errors: []
+ * };
+ * ```
  */
 export interface TTLResult {
-    /** Cache key */
     key: string;
-    /** TTL value */
     ttl: number;
-    /** Actual expiration time */
     actualExpiration: number;
-    /** Expected expiration time */
     expectedExpiration: number;
-    /** Whether within tolerance */
     withinTolerance: boolean;
 }
 /**
- * Memory usage testing options
- * @interface MemoryOptions
+ * Options for testing cache memory usage and limits.
+ * Configures memory profiling and limit enforcement testing.
+ *
+ * @example
+ * ```typescript
+ * const memoryOptions: MemoryOptions = {
+ *   maxMemory: 50 * 1024 * 1024, // 50MB
+ *   measureInterval: 1000,
+ *   includeOverhead: true,
+ *   trackGrowthRate: true,
+ *   warnThreshold: 0.8,
+ *   errorThreshold: 0.95
+ * };
+ * ```
  */
 export interface MemoryOptions {
-    /** Sample size for testing */
     sampleSize: number;
-    /** Maximum memory limit in MB */
     maxMemoryMB?: number;
 }
 /**
- * Memory usage test result
- * @interface MemoryResult
+ * Results from memory usage testing.
+ * Contains memory metrics and limit compliance data.
+ *
+ * @example
+ * ```typescript
+ * const memoryResult: MemoryResult = {
+ *   totalMemoryMB: 45,
+ *   avgItemSizeKB: 6,
+ *   itemCount: 5000,
+ *   withinLimit: true
+ * };
+ * ```
  */
 export interface MemoryResult {
-    /** Total memory usage in MB */
     totalMemoryMB: number;
-    /** Average item size in KB */
     avgItemSizeKB: number;
-    /** Number of items */
     itemCount: number;
-    /** Whether within memory limit */
     withinLimit: boolean;
 }
 /**
- * Cache test harness
- * @interface CacheTestHarness
- * @typeParam T - Type of cached values
+ * Test harness for comprehensive cache testing.
+ * Provides utilities for testing cache implementations.
+ *
+ * @template T - Type of cached values
+ *
+ * @example
+ * ```typescript
+ * const harness: CacheTestHarness<UserData> = {
+ *   cache: new LRUCache<UserData>(),
+ *   fillCache: async (entries) => {
+ *     for (const { key, value } of entries) {
+ *       await harness.cache.set(key, value);
+ *     }
+ *   },
+ *   measurePerformance: async (ops) => {
+ *     // Measure read/write performance
+ *     return { avgReadMs: 0.5, avgWriteMs: 1.2 };
+ *   },
+ *   simulateConcurrentAccess: async (options) => {
+ *     // Simulate concurrent operations
+ *   },
+ *   reset: async () => harness.cache.clear()
+ * };
+ * ```
  */
 export interface CacheTestHarness<T = unknown> {
-    /** Cache instance */
     cache: Cache<T>;
-    /** Fill cache with entries */
     fillCache: (entries: Array<{
         key: string;
         value: T;
     }>) => Promise<void>;
-    /** Measure cache performance */
     measurePerformance: (operations: number) => Promise<{
         avgReadMs: number;
         avgWriteMs: number;
     }>;
-    /** Simulate concurrent access */
     simulateConcurrentAccess: (options: ConcurrencyOptions) => Promise<void>;
-    /** Reset cache state */
     reset: () => Promise<void>;
 }