docs(cache): document cache coordination flow (JhaSourav07#3186)

## Description

Fixes JhaSourav07#2246

## Summary

* Added JSDoc for `DistributedCache.getOrSet()`
* Documented local Promise deduplication flow
* Added explanations for Redis lock coordination and fallback behavior
* Improved readability without changing functionality

## Pillar

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

## Visual Preview

N/A (documentation-only change)

## Checklist before requesting a review:

- [x] I have read the `CONTRIBUTING.md` file.
* [ ] I have tested these changes locally.
* [ ] I have run formatting/lint checks locally.
- [x] My commits follow the Conventional Commits format.
* [ ] I updated README if required.
- [ ] I have only one commit in this PR.

Author: JhaSourav07

lib/cache.ts

@@ -437,29 +437,35 @@ return c`;
   }
 
   /**
-   * Gets a value from the cache, or executes the load function if missing or stale.
-   * Employs both an in-memory Promise lock (L1) and a Redis Mutex (L2) to prevent Cache Stampedes.
+   * Returns cached data when available, otherwise loads and stores fresh data.
+   *
+   * Uses a two-layer coordination strategy to reduce cache stampedes:
+   * 1. Local Promise deduplication (L1) prevents duplicate fetches within the same instance.
+   * 2. Redis mutex locking (L2) prevents duplicate fetches across distributed instances.
+   *
+   * `loadFn` receives the current cached value (or null) so callers can implement
+   * stale refresh logic when needed.
    *
    * @param key - Cache key.
-   * @param loadFn - Async function to fetch the data. Receives the stale cached value if one exists.
-   * @param ttlMs - Time to live in milliseconds.
-   * @param shouldFetch - Optional predicate to force fetching even if a cache value exists (e.g. for stale delta sync).
+   * @param loadFn - Async function used to load fresh data.
+   * @param ttlMs - Cache expiration time in milliseconds.
+   * @param shouldFetch - Optional predicate that forces refresh even on cache hits.
    */
   async getOrSet(
     key: string,
     loadFn: (cached: T | null) => Promise<T>,
     ttlMs: number,
     shouldFetch?: (cached: T) => boolean
   ): Promise<T> {
-    // 1. L1 & L2 Cache Check
+    // Attempt to retrieve an existing value before triggering a refresh.
     const cached = await this.get(key);
 
-    // If we have a cache hit and we don't need to force a refresh, return it early.
     if (cached !== null && (!shouldFetch || !shouldFetch(cached))) {
       return cached;
     }
 
-    // 2. L1 Promise Deduping (Local Lock)
+    // Join an existing in-flight request instead of creating duplicate fetches
+    // within the same runtime instance.
     const pendingLocal = this.localLocks.get(key);
     if (pendingLocal) return pendingLocal;
 
@@ -478,7 +484,8 @@ return c`;
 
       while (Date.now() - start < maxPollTime) {
         try {
-          // Attempt to acquire Redis Mutex
+          // NX: acquire only if lock doesn't already exist.
+          // PX 10000: auto-expire lock after 10 seconds to avoid deadlocks.
           const lockRes = await fetch(`${this.redisUrl}/`, {
             method: 'POST',
             headers: {
@@ -491,12 +498,12 @@ return c`;
           if (lockRes.ok) {
             const lockData = await lockRes.json();
             if (lockData.result === 'OK') {
-              // Lock acquired! Execute loadFn.
               try {
                 const freshData = await loadFn(cached);
                 await this.set(key, freshData, ttlMs);
 
-                // Release lock early
+                // Release immediately after caching data instead of waiting
+                // for lock expiration so other instances can continue sooner.
                 await fetch(`${this.redisUrl}/`, {
                   method: 'POST',
                   headers: {
@@ -508,7 +515,8 @@ return c`;
 
                 return freshData;
               } catch (err) {
-                // Release lock on error so others can retry
+                // Remove lock even on failure so other instances don't wait
+                // for the full lock timeout period.
                 await fetch(`${this.redisUrl}/`, {
                   method: 'POST',
                   headers: {
@@ -529,10 +537,11 @@ return c`;
           return fallbackData;
         }
 
-        // Lock not acquired. Wait and poll L2 cache.
+        // Wait briefly before checking whether another instance populated the cache.
         await new Promise((resolve) => setTimeout(resolve, pollInterval));
         const doubleCheck = await this.get(key);
-        // If doubleCheck satisfies the condition, return it
+
+        // Another instance may have already populated the cache while waiting.
         if (doubleCheck !== null && (!shouldFetch || !shouldFetch(doubleCheck))) {
           return doubleCheck;
         }
@@ -544,10 +553,11 @@ return c`;
       return finalFallback;
     };
 
-    // Execute with local Promise lock
+    // Ensure local lock cleanup even if request execution fails.
     const promise = executeAndLock().finally(() => {
       this.localLocks.delete(key);
     });
+
     this.localLocks.set(key, promise);
 
     return promise;