docs(cache): add JSDoc comments for TTLCache (JhaSourav07#621)

## Description
Added JSDoc documentation for the TTLCache class and all public methods
in lib/cache.ts.

- Changes made
- Added class-level documentation
- Added constructor documentation
- Added @param, @returns, and @example tags for public methods
- Documented in-process cache limitation
- No functional changes

Fixes JhaSourav07#302

## Pillar

- [ ] 🎨 Pillar 1 — New Theme Design
- [ ] 📐 Pillar 2 — Geometric SVG Improvement
- [ ] 🕐 Pillar 3 — Timezone Logic Optimization
- [x] 🛠️ Other (Bug fix, refactoring, docs)

## Visual Preview
<img width="1297" height="936" alt="image"
src="https://github.com/user-attachments/assets/dc88c136-d035-4fef-ae67-eb4dbe10243e"
/>
<img width="1127" height="927" alt="image"
src="https://github.com/user-attachments/assets/d548be43-ee27-4ae3-b654-509113964ff7"
/>

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
- [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
- [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
- [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
- [x] I have updated `README.md` if I added a new theme or URL
parameter.
- [x] I have started the repo.
- [x] I have made sure that i have only one commit to merge in this PR.
- [x] The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animations, correct fonts).
- [ ] (Recommended) I joined the CommitPulse Discord community for
contributor discussions, mentorship, and faster PR support.

Author: JhaSourav07

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);