Update TypeScript definitions to match implementation

Author: avoidwork

types/lru.d.ts

@@ -24,6 +24,18 @@ export interface LRUItem<T> {
     value: T;
 }
 
+/**
+ * Represents the evicted item returned by setWithEvicted().
+ */
+export interface EvictedItem<T> {
+    /** The key of the evicted item */
+    key: any;
+    /** The value of the evicted item */
+    value: T;
+    /** The expiration timestamp of the evicted item */
+    expiry: number;
+}
+
 /**
  * High-performance Least Recently Used (LRU) cache with optional TTL support.
  * All core operations (get, set, delete) are O(1).
@@ -37,7 +49,7 @@ export class LRU<T = any> {
      * @param resetTtl Whether to reset TTL when accessing existing items via get() (default: false)
      */
     constructor(max?: number, ttl?: number, resetTtl?: boolean);
-    
+
     /** Pointer to the least recently used item (first to be evicted) */
     readonly first: LRUItem<T> | null;
     /** Hash map for O(1) key-based access to cache nodes */
@@ -52,86 +64,86 @@ export class LRU<T = any> {
     readonly size: number;
     /** Time-to-live in milliseconds (0 = no expiration) */
     readonly ttl: number;
-    
+
     /**
      * Removes all items from the cache.
      * @returns The LRU instance for method chaining
      */
     clear(): this;
-    
+
     /**
      * Removes an item from the cache by key.
      * @param key The key of the item to delete
      * @returns The LRU instance for method chaining
      */
     delete(key: any): this;
-    
+
     /**
      * Returns an array of [key, value] pairs for the specified keys.
      * Order follows LRU order (least to most recently used).
      * @param keys Array of keys to get entries for (defaults to all keys)
      * @returns Array of [key, value] pairs in LRU order
      */
-    entries(keys?: any[]): [any, T][];
-    
+    entries(keys?: any[]): [any, T | undefined][];
+
     /**
      * Removes the least recently used item from the cache.
-     * @param bypass Whether to force eviction even when cache is empty
+     * @param bypass Whether to force eviction even when cache is empty (default: false)
      * @returns The LRU instance for method chaining
      */
     evict(bypass?: boolean): this;
-    
+
     /**
      * Returns the expiration timestamp for a given key.
      * @param key The key to check expiration for
      * @returns The expiration timestamp in milliseconds, or undefined if key doesn't exist
      */
     expiresAt(key: any): number | undefined;
-    
+
     /**
      * Retrieves a value from the cache by key. Updates the item's position to most recently used.
      * @param key The key to retrieve
      * @returns The value associated with the key, or undefined if not found or expired
      */
     get(key: any): T | undefined;
-    
+
     /**
-     * Checks if a key exists in the cache.
+     * Checks if a key exists in the cache (not expired).
      * @param key The key to check for
-     * @returns True if the key exists, false otherwise
+     * @returns True if the key exists and is not expired, false otherwise
      */
     has(key: any): boolean;
-    
+
     /**
      * Returns an array of all keys in the cache, ordered from least to most recently used.
      * @returns Array of keys in LRU order
      */
     keys(): any[];
-    
+
     /**
      * Sets a value in the cache. Updates the item's position to most recently used.
      * @param key The key to set
      * @param value The value to store
-     * @param bypass Internal parameter for setWithEvicted method
-     * @param resetTtl Whether to reset the TTL for this operation
+     * @param bypass Internal parameter for setWithEvicted method (default: false)
+     * @param resetTtl Whether to reset the TTL for this operation (default: this.resetTtl)
      * @returns The LRU instance for method chaining
      */
     set(key: any, value: T, bypass?: boolean, resetTtl?: boolean): this;
-    
+
     /**
      * Sets a value in the cache and returns any evicted item.
      * @param key The key to set
      * @param value The value to store
-     * @param resetTtl Whether to reset the TTL for this operation
-     * @returns The evicted item (if any) or null
+     * @param resetTtl Whether to reset the TTL for this operation (default: this.resetTtl)
+     * @returns The evicted item (if any) with {key, value, expiry} or null
      */
-    setWithEvicted(key: any, value: T, resetTtl?: boolean): LRUItem<T> | null;
-    
+    setWithEvicted(key: any, value: T, resetTtl?: boolean): EvictedItem<T> | null;
+
     /**
      * Returns an array of all values in the cache for the specified keys.
      * Order follows LRU order (least to most recently used).
      * @param keys Array of keys to get values for (defaults to all keys)
-     * @returns Array of values corresponding to the keys in LRU order
+     * @returns Array of values corresponding to the keys (undefined for missing/expired keys)
      */
-    values(keys?: any[]): T[];
+    values(keys?: any[]): (T | undefined)[];
 }