feat: enhance cache management with async methods and improve disposal logic

Author: mashrulhaque

src/EasyAppDev.Blazor.Store/AsyncActions/AsyncActionExecutor.cs

@@ -20,7 +20,7 @@ public sealed class AsyncActionExecutor<TState> : IAsyncActionExecutor<TState>,
     private readonly Dictionary<string, CachedOperation> _inFlightOperations = new();
     private readonly Dictionary<string, CachedResult> _cachedResults = new();
     private readonly SemaphoreSlim _lock = new(1, 1);
-    private bool _disposed;
+    private int _disposed; // 0 = not disposed, 1 = disposed (use int for Interlocked)
 
     /// <summary>
     /// Tracks an in-flight operation for deduplication.
@@ -300,7 +300,29 @@ public void InvalidateCache(string cacheKey)
         ThrowIfDisposed();
         ArgumentNullException.ThrowIfNull(cacheKey);
 
-        _lock.Wait();
+        // Use timeout to prevent indefinite blocking in edge cases
+        if (!_lock.Wait(TimeSpan.FromSeconds(5)))
+        {
+            _logger?.LogWarning("InvalidateCache timed out waiting for lock. Consider using InvalidateCacheAsync instead.");
+            return;
+        }
+        try
+        {
+            _cachedResults.Remove(cacheKey);
+        }
+        finally
+        {
+            _lock.Release();
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task InvalidateCacheAsync(string cacheKey)
+    {
+        ThrowIfDisposed();
+        ArgumentNullException.ThrowIfNull(cacheKey);
+
+        await _lock.WaitAsync().ConfigureAwait(false);
         try
         {
             _cachedResults.Remove(cacheKey);
@@ -317,7 +339,36 @@ public void InvalidateCacheByPrefix(string prefix)
         ThrowIfDisposed();
         ArgumentNullException.ThrowIfNull(prefix);
 
-        _lock.Wait();
+        // Use timeout to prevent indefinite blocking in edge cases
+        if (!_lock.Wait(TimeSpan.FromSeconds(5)))
+        {
+            _logger?.LogWarning("InvalidateCacheByPrefix timed out waiting for lock. Consider using InvalidateCacheByPrefixAsync instead.");
+            return;
+        }
+        try
+        {
+            var keysToRemove = _cachedResults.Keys
+                .Where(k => k.StartsWith(prefix, StringComparison.Ordinal))
+                .ToList();
+
+            foreach (var key in keysToRemove)
+            {
+                _cachedResults.Remove(key);
+            }
+        }
+        finally
+        {
+            _lock.Release();
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task InvalidateCacheByPrefixAsync(string prefix)
+    {
+        ThrowIfDisposed();
+        ArgumentNullException.ThrowIfNull(prefix);
+
+        await _lock.WaitAsync().ConfigureAwait(false);
         try
         {
             var keysToRemove = _cachedResults.Keys
@@ -340,7 +391,28 @@ public void ClearCache()
     {
         ThrowIfDisposed();
 
-        _lock.Wait();
+        // Use timeout to prevent indefinite blocking in edge cases
+        if (!_lock.Wait(TimeSpan.FromSeconds(5)))
+        {
+            _logger?.LogWarning("ClearCache timed out waiting for lock. Consider using ClearCacheAsync instead.");
+            return;
+        }
+        try
+        {
+            _cachedResults.Clear();
+        }
+        finally
+        {
+            _lock.Release();
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task ClearCacheAsync()
+    {
+        ThrowIfDisposed();
+
+        await _lock.WaitAsync().ConfigureAwait(false);
         try
         {
             _cachedResults.Clear();
@@ -394,15 +466,18 @@ private void PerformCacheCleanup()
     /// </summary>
     public void Dispose()
     {
-        if (_disposed) return;
-        _disposed = true;
-        _lock.Dispose();
+        // Use Interlocked.Exchange for atomic check-and-set to prevent race conditions
+        if (Interlocked.Exchange(ref _disposed, 1) != 0)
+            return;
+
         _inFlightOperations.Clear();
         _cachedResults.Clear();
+        _lock.Dispose();
     }
 
     private void ThrowIfDisposed()
     {
-        ObjectDisposedException.ThrowIf(_disposed, this);
+        if (Volatile.Read(ref _disposed) != 0)
+            throw new ObjectDisposedException(nameof(AsyncActionExecutor<TState>));
     }
 }

src/EasyAppDev.Blazor.Store/AsyncActions/IAsyncActionExecutor.cs

@@ -206,23 +206,58 @@ Task ExecuteCachedAsync<TResult>(
     /// <param name="cacheKey">The cache key to invalidate.</param>
     /// <remarks>
     /// This does not affect in-flight operations. Only cached results are removed.
+    /// Prefer <see cref="InvalidateCacheAsync"/> in async contexts to avoid potential deadlocks.
     /// </remarks>
     void InvalidateCache(string cacheKey);
 
+    /// <summary>
+    /// Removes a specific cached result by key asynchronously.
+    /// </summary>
+    /// <param name="cacheKey">The cache key to invalidate.</param>
+    /// <returns>A task representing the async operation.</returns>
+    /// <remarks>
+    /// This does not affect in-flight operations. Only cached results are removed.
+    /// Preferred over <see cref="InvalidateCache"/> in async contexts.
+    /// </remarks>
+    Task InvalidateCacheAsync(string cacheKey);
+
     /// <summary>
     /// Removes all cached results with keys starting with the specified prefix.
     /// </summary>
     /// <param name="prefix">The prefix to match cache keys against.</param>
     /// <remarks>
     /// Useful for invalidating related cache entries (e.g., "product-" invalidates "product-1", "product-2", etc.).
+    /// Prefer <see cref="InvalidateCacheByPrefixAsync"/> in async contexts to avoid potential deadlocks.
     /// </remarks>
     void InvalidateCacheByPrefix(string prefix);
 
+    /// <summary>
+    /// Removes all cached results with keys starting with the specified prefix asynchronously.
+    /// </summary>
+    /// <param name="prefix">The prefix to match cache keys against.</param>
+    /// <returns>A task representing the async operation.</returns>
+    /// <remarks>
+    /// Useful for invalidating related cache entries (e.g., "product-" invalidates "product-1", "product-2", etc.).
+    /// Preferred over <see cref="InvalidateCacheByPrefix"/> in async contexts.
+    /// </remarks>
+    Task InvalidateCacheByPrefixAsync(string prefix);
+
     /// <summary>
     /// Clears all cached results.
     /// </summary>
     /// <remarks>
     /// This does not affect in-flight operations. Only cached results are removed.
+    /// Prefer <see cref="ClearCacheAsync"/> in async contexts to avoid potential deadlocks.
     /// </remarks>
     void ClearCache();
+
+    /// <summary>
+    /// Clears all cached results asynchronously.
+    /// </summary>
+    /// <returns>A task representing the async operation.</returns>
+    /// <remarks>
+    /// This does not affect in-flight operations. Only cached results are removed.
+    /// Preferred over <see cref="ClearCache"/> in async contexts.
+    /// </remarks>
+    Task ClearCacheAsync();
 }

src/EasyAppDev.Blazor.Store/Query/QueryClient.cs

@@ -18,7 +18,7 @@ public sealed class QueryClient : IQueryClient, IDisposable
     private readonly QueryClientOptions _options;
     private readonly ILogger<QueryClient>? _logger;
     private readonly Timer _cleanupTimer;
-    private bool _disposed;
+    private int _disposed; // 0 = not disposed, 1 = disposed (use int for Interlocked)
 
     /// <summary>
     /// Creates a new query client with the specified options.
@@ -249,7 +249,7 @@ private async Task TriggerRefetchAsync(string key)
 
     private void CleanupExpiredEntries(object? state)
     {
-        if (_disposed) return;
+        if (Volatile.Read(ref _disposed) != 0) return;
 
         var now = DateTime.UtcNow;
         var expiredKeys = new List<string>();
@@ -288,8 +288,9 @@ private void CleanupExpiredEntries(object? state)
     /// </summary>
     public void Dispose()
     {
-        if (_disposed) return;
-        _disposed = true;
+        // Use Interlocked.Exchange for atomic check-and-set to prevent race conditions
+        if (Interlocked.Exchange(ref _disposed, 1) != 0)
+            return;
 
         _cleanupTimer.Dispose();
         _cache.Clear();

src/EasyAppDev.Blazor.Store/ServerSync/ServerSyncMiddleware.cs

@@ -487,11 +487,29 @@ private async void SendPendingUpdate()
         catch (Exception ex)
         {
             _logger?.LogWarning(ex, "Failed to send state update");
-            if (_options.EnableOfflineQueue)
+
+            // Guard QueueOfflineUpdate to prevent exceptions escaping async void
+            try
             {
-                QueueOfflineUpdate(update);
+                if (_options.EnableOfflineQueue)
+                {
+                    QueueOfflineUpdate(update);
+                }
+            }
+            catch (Exception queueEx)
+            {
+                _logger?.LogError(queueEx, "Failed to queue offline update");
+            }
+
+            // Guard OnError callback to prevent user code exceptions escaping async void
+            try
+            {
+                _options.OnError?.Invoke(ex);
+            }
+            catch (Exception callbackEx)
+            {
+                _logger?.LogError(callbackEx, "OnError callback threw an exception");
             }
-            _options.OnError?.Invoke(ex);
         }
     }
 
@@ -540,7 +558,15 @@ private async void SendPendingCursor()
         }
         catch (Exception ex)
         {
-            _logger?.LogDebug(ex, "Failed to send cursor update");
+            // Guard logger call to prevent exceptions escaping async void
+            try
+            {
+                _logger?.LogDebug(ex, "Failed to send cursor update");
+            }
+            catch
+            {
+                // Swallow logging exceptions to prevent async void crash
+            }
         }
     }
 

src/EasyAppDev.Blazor.Store/Utilities/DebounceManager.cs

@@ -200,7 +200,18 @@ public void Dispose()
     {
         if (_disposed) return;
 
-        _lock.Wait();
+        // Use timeout to prevent indefinite blocking during dispose
+        if (!_lock.Wait(TimeSpan.FromSeconds(5)))
+        {
+            // Force dispose even if lock timeout - cancel all CTS without lock
+            _disposed = true;
+            foreach (var cts in _pendingActions.Values)
+            {
+                try { cts.Cancel(); cts.Dispose(); } catch { }
+            }
+            _lock.Dispose();
+            return;
+        }
         try
         {
             foreach (var cts in _pendingActions.Values)

src/EasyAppDev.Blazor.Store/Utilities/ILazyCache.cs

@@ -22,7 +22,7 @@ namespace EasyAppDev.Blazor.Store.Utilities;
 /// }
 /// </code>
 /// </example>
-public interface ILazyCache : IDisposable
+public interface ILazyCache : IDisposable, IAsyncDisposable
 {
     /// <summary>
     /// Gets data from cache or loads it using the provided loader function if not cached or expired.
@@ -76,5 +76,17 @@ Task<T> GetOrLoadAsync<T>(
     /// Gets the current number of entries in the cache, including expired entries.
     /// </summary>
     /// <value>The total count of entries in the cache (includes expired entries).</value>
+    /// <remarks>
+    /// Prefer <see cref="GetCountAsync"/> in async contexts to avoid potential deadlocks.
+    /// </remarks>
     int Count { get; }
+
+    /// <summary>
+    /// Gets the current number of entries in the cache asynchronously.
+    /// </summary>
+    /// <returns>The total count of entries in the cache (includes expired entries).</returns>
+    /// <remarks>
+    /// Preferred over <see cref="Count"/> property in async contexts.
+    /// </remarks>
+    Task<int> GetCountAsync();
 }