feat: add ExecuteCachedAsync for deduplicated async actions with caching

- Introduced ExecuteCachedAsync method in AsyncActionExecutor to handle deduplication of async fetch and state updates.
- Updated IAsyncActionExecutor interface to include new caching methods.
- Enhanced StoreComponentWithUtilities to support ExecuteCachedAsync.
- Added comprehensive unit tests for ExecuteCachedAsync covering various scenarios including concurrent calls, caching behavior, and error handling.
- Updated documentation and navigation links in async helpers to include ExecuteCachedAsync.

Author: mashrulhaque

README.md

@@ -385,6 +385,38 @@ async Task LoadUserDetails(int userId)
 }
 ```
 
+### 6. ExecuteCachedAsync - Deduplicated State Updates
+
+Combines caching with automatic state management. Unlike `ExecuteAsync` + `LazyLoad`, this deduplicates **both** the fetch **and** the state updates:
+
+```csharp
+// Multiple components calling this concurrently:
+// - Only ONE loading state update
+// - Only ONE async fetch
+// - Only ONE success/error state update
+// Result: 2 state updates instead of 2×N
+async Task LoadProduct(int productId, CancellationToken ct = default)
+{
+    var product = await ExecuteCachedAsync(
+        $"product-{productId}",
+        async () => await ProductService.GetAsync(productId),
+        loading: s => s with { Product = s.Product.ToLoading() },
+        success: (s, product) => s with { Product = AsyncData.Success(product) },
+        error: (s, ex) => s with { Product = AsyncData.Failure(ex.Message) },
+        cacheFor: TimeSpan.FromMinutes(5),
+        cancellationToken: ct  // Optional cancellation support
+    );
+}
+```
+
+**When to use which helper:**
+
+| Scenario | Method |
+|----------|--------|
+| Multiple components load same data | `ExecuteCachedAsync` |
+| Single component, no deduplication needed | `ExecuteAsync` |
+| Need data without state updates | `LazyLoad` |
+
 ---
 
 ## Optimistic Updates
@@ -1078,6 +1110,7 @@ protected Task UpdateDebounced(Func<TState, TState> updater, int delayMs);
 protected Task UpdateThrottled(Func<TState, TState> updater, int intervalMs);
 protected Task ExecuteAsync<T>(Func<Task<T>> action, ...);
 protected Task<T> LazyLoad<T>(string key, Func<Task<T>> loader, TimeSpan? cacheFor);
+protected Task<T> ExecuteCachedAsync<T>(string key, Func<Task<T>> action, ..., TimeSpan? cacheFor, CancellationToken ct = default);
 ```
 
 ### Registration

docs-site/api-reference.html

@@ -64,6 +64,7 @@
               <li><a href="./async-helpers/execute-async.html" class="nav-link"><span class="nav-icon">⚡</span><span>ExecuteAsync</span></a></li>
               <li><a href="./async-helpers/update-throttled.html" class="nav-link"><span class="nav-icon">💧</span><span>UpdateThrottled</span></a></li>
               <li><a href="./async-helpers/lazy-load.html" class="nav-link"><span class="nav-icon">📥</span><span>LazyLoad</span></a></li>
+              <li><a href="./async-helpers/execute-cached-async.html" class="nav-link"><span class="nav-icon">🔗</span><span>ExecuteCachedAsync</span></a></li>
             </ul>
           </div>
 
@@ -145,6 +146,14 @@ <h2 id="store-component">StoreComponent&lt;TState&gt;</h2>
         Func&lt;TState, T, TState&gt; success,
         Func&lt;TState, Exception, TState&gt;? error = null);
     protected Task&lt;T&gt; LazyLoad&lt;T&gt;(string key, Func&lt;Task&lt;T&gt;&gt; loader, TimeSpan? cacheFor = null);
+    protected Task&lt;T&gt; ExecuteCachedAsync&lt;T&gt;(
+        string key,
+        Func&lt;Task&lt;T&gt;&gt; action,
+        Func&lt;TState, TState&gt; loading,
+        Func&lt;TState, T, TState&gt; success,
+        Func&lt;TState, Exception, TState&gt;? error = null,
+        TimeSpan? cacheFor = null,
+        CancellationToken ct = default);
 }</code></pre>
               </div>
 
@@ -270,6 +279,43 @@ <h4><code>LazyLoad</code></h4>
     $"user-{userId}",
     () => UserService.GetUserAsync(userId),
     TimeSpan.FromMinutes(5)
+);</code></pre>
+                </div>
+              </div>
+
+              <div class="api-section">
+                <h4><code>ExecuteCachedAsync</code></h4>
+                <p>Executes an async operation with full deduplication of both the fetch AND the state updates. When multiple components call this with the same key, only 2 state updates occur instead of N×2.</p>
+                <div class="code-block">
+                  <pre><code class="language-csharp">protected Task&lt;T&gt; ExecuteCachedAsync&lt;T&gt;(
+    string key,
+    Func&lt;Task&lt;T&gt;&gt; action,
+    Func&lt;TState, TState&gt; loading,
+    Func&lt;TState, T, TState&gt; success,
+    Func&lt;TState, Exception, TState&gt;? error = null,
+    TimeSpan? cacheFor = null,
+    CancellationToken ct = default)</code></pre>
+                </div>
+                <p><strong>Parameters:</strong></p>
+                <ul>
+                  <li><code>key</code> - Unique cache key for deduplication</li>
+                  <li><code>action</code> - Async operation to execute</li>
+                  <li><code>loading</code> - State transformation for loading state</li>
+                  <li><code>success</code> - State transformation for success with result</li>
+                  <li><code>error</code> - Optional state transformation for error handling</li>
+                  <li><code>cacheFor</code> - Optional cache duration</li>
+                  <li><code>ct</code> - Optional cancellation token to cancel the operation</li>
+                </ul>
+                <p><strong>Example:</strong></p>
+                <div class="code-block">
+                  <pre><code class="language-csharp">// Multiple components calling this = only 2 state updates
+var product = await ExecuteCachedAsync(
+    $"product-{productId}",
+    async () => await ProductService.GetAsync(productId),
+    loading: s => s with { Product = s.Product.ToLoading() },
+    success: (s, p) => s with { Product = AsyncData.Success(p) },
+    error: (s, ex) => s with { Product = AsyncData.Failure(ex.Message) },
+    cacheFor: TimeSpan.FromMinutes(5)
 );</code></pre>
                 </div>
               </div>
@@ -889,6 +935,10 @@ <h2 id="quick-reference">Quick Reference</h2>
                     <td><code>LazyLoad()</code></td>
                     <td>Caching with request deduplication</td>
                   </tr>
+                  <tr>
+                    <td><code>ExecuteCachedAsync()</code></td>
+                    <td>Full deduplication of fetch and state updates</td>
+                  </tr>
                   <tr>
                     <td><code>AsyncData&lt;T&gt;</code></td>
                     <td>Async state representation</td>

docs-site/async-helpers/async-data.html

@@ -64,6 +64,7 @@
               <li><a href="../async-helpers/execute-async.html" class="nav-link"><span class="nav-icon">⚡</span><span>ExecuteAsync</span></a></li>
               <li><a href="../async-helpers/update-throttled.html" class="nav-link"><span class="nav-icon">💧</span><span>UpdateThrottled</span></a></li>
               <li><a href="../async-helpers/lazy-load.html" class="nav-link"><span class="nav-icon">📥</span><span>LazyLoad</span></a></li>
+              <li><a href="../async-helpers/execute-cached-async.html" class="nav-link"><span class="nav-icon">🔗</span><span>ExecuteCachedAsync</span></a></li>
             </ul>
           </div>
 

docs-site/async-helpers/execute-async.html

@@ -64,6 +64,7 @@
               <li><a href="../async-helpers/execute-async.html" class="nav-link"><span class="nav-icon">⚡</span><span>ExecuteAsync</span></a></li>
               <li><a href="../async-helpers/update-throttled.html" class="nav-link"><span class="nav-icon">💧</span><span>UpdateThrottled</span></a></li>
               <li><a href="../async-helpers/lazy-load.html" class="nav-link"><span class="nav-icon">📥</span><span>LazyLoad</span></a></li>
+              <li><a href="../async-helpers/execute-cached-async.html" class="nav-link"><span class="nav-icon">🔗</span><span>ExecuteCachedAsync</span></a></li>
             </ul>
           </div>