docs(cache): add JSDoc comments for TTLCache

Author: tamilr0727-ux

lib/cache.ts

@@ -1,13 +1,30 @@
+/**
+ * Represents a cached item with its expiration timestamp.
+ */
 type CacheItem<T> = {
   value: T;
   expiresAt: number;
 };
 
+/**
+ * A Simple in-memory TTL(Time To Live) cache.
+ *
+ * Stores values in-process only and automatically removes expired entries.
+ * This cache is not shared accross multiple server instances or severless invocations.
+ *
+ * @typeParam T - Type of values stored in the cache.
+ */
 export class TTLCache<T> {
   private store = new Map<string, CacheItem<T>>();
   private cleanupInterval: ReturnType<typeof setInterval> | null = null;
   private readonly maxSize?: number;
 
+  /**
+   * Creates a new TTL cache instance.
+   *
+   * @param maxSize - Maximum number of items allowed in the cache.
+   * @param cleanupIntervalMs - Interval in milliseconds for cleaning expired entries.
+   */
   constructor(maxSize?: number, cleanupIntervalMs: number = 60000) {
     this.maxSize = maxSize === undefined ? undefined : Math.max(1, maxSize);
     const interval = Math.max(1000, cleanupIntervalMs);
@@ -35,6 +52,17 @@ export class TTLCache<T> {
     }
   }
 
+  /**
+   * Retrieves a value from the cache.
+   *
+   * Returns 'null' if the key does not exist or if the entry has expired.
+   *
+   * @param key - Cache key.
+   * @returns The cached value or 'null'.
+   *
+   * @example
+   * const user = cache.get("user:1");
+   */
   get(key: string): T | null {
     const hit = this.store.get(key);
     if (!hit) return null;
@@ -47,6 +75,20 @@ export class TTLCache<T> {
     return hit.value;
   }
 
+  /**
+   * Stores a value in the cache with a TTL.
+   *
+   * If the cache reaches its maximum capacity, the oldest item
+   * may be removed to make room for new entries.
+   *
+   * @param key - Cache key.
+   * @param value - Value to cache.
+   * @param ttlMs - Time to live in milliseconds.
+   * @returns void
+   *
+   * @example
+   * cache.set("user:1",userData,5000);
+   */
   set(key: string, value: T, ttlMs: number): void {
     // Capacity eviction (FIFO / LRU-lite)
     const maxSize = this.maxSize;
@@ -64,10 +106,23 @@ export class TTLCache<T> {
     this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
   }
 
+  /**
+   * Removes all entries from the cache.
+   *
+   * @returns void
+   *
+   * @example
+   * cache.clear();
+   */
   clear(): void {
     this.store.clear();
   }
 
+  /**
+   * Stops the cleanup interval and clears the cache.
+   *
+   * @returns void
+   */
   destroy(): void {
     if (this.cleanupInterval) {
       clearInterval(this.cleanupInterval);