From d1b866565269cea503bafb38b7e0d3cd2f55d201 Mon Sep 17 00:00:00 2001
From: Damjan Savic <info@damjan-savic.com>
Date: Sun, 25 Jan 2026 06:32:11 +0100
Subject: [PATCH] auto-claude: subtask-1-2 - Add JSDoc to cache.ts (Cache class
 and its 5 methods)

---
 src/utils/cache.ts | 50 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 46 insertions(+), 4 deletions(-)

diff --git a/src/utils/cache.ts b/src/utils/cache.ts
index d04a660..9f701e0 100644
--- a/src/utils/cache.ts
+++ b/src/utils/cache.ts
@@ -1,18 +1,39 @@
+/**
+ * In-Memory Cache Utility
+ * Provides simple key-value caching with TTL (Time To Live) support
+ */
+
+/**
+ * Cache item structure with value, timestamp, and TTL
+ */
 type CacheItem<T> = {
   value: T;
   timestamp: number;
   ttl: number;
 };
 
+/**
+ * In-memory cache implementation with automatic expiration
+ */
 class Cache {
   private storage: Map<string, CacheItem<any>>;
   private readonly defaultTTL: number;
 
+  /**
+   * Create a new cache instance
+   * @param defaultTTL - Default time-to-live in milliseconds (default: 5 minutes)
+   */
   constructor(defaultTTL = 5 * 60 * 1000) { // 5 minutes default TTL
     this.storage = new Map();
     this.defaultTTL = defaultTTL;
   }
 
+  /**
+   * Store a value in cache with optional TTL
+   * @param key - Cache key
+   * @param value - Value to cache
+   * @param ttl - Time-to-live in milliseconds (uses default if not specified)
+   */
   set<T>(key: string, value: T, ttl = this.defaultTTL): void {
     this.storage.set(key, {
       value,
@@ -21,30 +42,51 @@ class Cache {
     });
   }
 
+  /**
+   * Retrieve a value from cache
+   * Returns null if key doesn't exist or has expired
+   * @param key - Cache key
+   * @returns Cached value or null
+   */
   get<T>(key: string): T | null {
     const item = this.storage.get(key);
-    
+
     if (!item) return null;
-    
+
     if (Date.now() > item.timestamp + item.ttl) {
       this.storage.delete(key);
       return null;
     }
-    
+
     return item.value;
   }
 
+  /**
+   * Check if a key exists and is not expired
+   * @param key - Cache key
+   * @returns True if key exists and is valid
+   */
   has(key: string): boolean {
     return this.get(key) !== null;
   }
 
+  /**
+   * Remove a specific key from cache
+   * @param key - Cache key to delete
+   */
   delete(key: string): void {
     this.storage.delete(key);
   }
 
+  /**
+   * Clear all cached items
+   */
   clear(): void {
     this.storage.clear();
   }
 }
 
-export const cache = new Cache();
\ No newline at end of file
+/**
+ * Shared cache instance with 5-minute default TTL
+ */
+export const cache = new Cache();