feat: add synchronous localStorage operations and state hydration support in WebAssembly

Author: mashrulhaque

src/EasyAppDev.Blazor.Store/Blazor/StoreBuilderExtensions.cs

@@ -1,3 +1,4 @@
+using System.Text.Json;
 using EasyAppDev.Blazor.Store.Core;
 #if DEBUG
 using EasyAppDev.Blazor.Store.Diagnostics;
@@ -60,6 +61,7 @@ public static StoreBuilder<TState> WithDefaults<TState>(
 
     /// <summary>
     /// Adds persistence middleware with automatic LocalStorageProvider creation.
+    /// In WebAssembly mode, state is automatically hydrated from localStorage on store creation.
     /// Requires the store to be registered as scoped (via AddScopedStore or AddScopedStoreWithUtilities)
     /// so that IJSRuntime is available during store creation.
     /// </summary>
@@ -99,9 +101,77 @@ public static StoreBuilder<TState> WithPersistence<TState>(
         }
 
         var provider = new LocalStorageProvider(jsRuntime);
+
+        // In WebAssembly mode, synchronous JS interop is available
+        // Load persisted state before building the store
+        if (provider.SupportsSyncOperations)
+        {
+            builder = TryHydrateStateSync(builder, provider, key);
+        }
+
         return builder.WithPersistence(provider, key);
     }
 
+    /// <summary>
+    /// Attempts to hydrate state synchronously from localStorage (WebAssembly only).
+    /// </summary>
+    private static StoreBuilder<TState> TryHydrateStateSync<TState>(
+        StoreBuilder<TState> builder,
+        LocalStorageProvider provider,
+        string key)
+        where TState : notnull
+    {
+        try
+        {
+            var json = provider.LoadSync(key);
+            if (string.IsNullOrEmpty(json))
+            {
+                return builder;
+            }
+
+            var jsonOptions = new JsonSerializerOptions
+            {
+                PropertyNamingPolicy = JsonNamingPolicy.CamelCase
+            };
+
+            // Try to deserialize as new format (with wrapper)
+            string stateJson;
+            try
+            {
+                var wrapper = JsonSerializer.Deserialize<PersistedStateWrapper>(json, jsonOptions);
+                if (wrapper != null && !string.IsNullOrEmpty(wrapper.State))
+                {
+                    stateJson = wrapper.State;
+                }
+                else
+                {
+                    // Legacy format - plain JSON state
+                    stateJson = json;
+                }
+            }
+            catch
+            {
+                // Deserialization failed, try legacy format
+                stateJson = json;
+            }
+
+            var loadedState = JsonSerializer.Deserialize<TState>(stateJson, jsonOptions);
+            if (loadedState != null)
+            {
+                // Create new builder with hydrated state, preserving configuration
+                return builder.WithInitialState(loadedState);
+            }
+        }
+        catch (Exception ex)
+        {
+            // Log but don't fail - fall back to initial state
+            System.Diagnostics.Debug.WriteLine(
+                $"[EasyAppDev.Store] Failed to hydrate state for {typeof(TState).Name} from key '{key}': {ex.Message}");
+        }
+
+        return builder;
+    }
+
     /// <summary>
     /// Adds diagnostics middleware if IDiagnosticsService is registered.
     /// </summary>

src/EasyAppDev.Blazor.Store/Core/StoreBuilder.cs

@@ -38,6 +38,31 @@ public static StoreBuilder<TState> Create(TState initialState)
         return new StoreBuilder<TState>(initialState);
     }
 
+    /// <summary>
+    /// Creates a new builder with the specified initial state while preserving all other configuration.
+    /// Used internally for state hydration from persistence.
+    /// </summary>
+    /// <param name="newInitialState">The new initial state.</param>
+    /// <returns>A new builder with the updated initial state and all existing configuration.</returns>
+    public StoreBuilder<TState> WithInitialState(TState newInitialState)
+    {
+        ArgumentNullException.ThrowIfNull(newInitialState);
+
+        var newBuilder = new StoreBuilder<TState>(newInitialState)
+        {
+            _comparer = this._comparer,
+            _middlewarePipelineLogger = this._middlewarePipelineLogger,
+            _storeLogger = this._storeLogger,
+            _subscriptionManagerLogger = this._subscriptionManagerLogger,
+            _middlewareOptions = this._middlewareOptions,
+            _errorHandler = this._errorHandler,
+            _stateValidator = this._stateValidator,
+            _requireValidation = this._requireValidation
+        };
+        newBuilder._middlewares.AddRange(this._middlewares);
+        return newBuilder;
+    }
+
     /// <summary>
     /// Gets the configured state validator, if any.
     /// </summary>

src/EasyAppDev.Blazor.Store/Persistence/LocalStorageProvider.cs

@@ -12,10 +12,12 @@ namespace EasyAppDev.Blazor.Store.Persistence;
 /// Operations are async due to Blazor's JS interop requirements.
 /// Errors are logged at Warning level and don't throw exceptions to ensure
 /// application stability when storage is unavailable or quota exceeded.
+/// In WebAssembly mode, synchronous operations are available via <see cref="IJSInProcessRuntime"/>.
 /// </remarks>
 public class LocalStorageProvider : IPersistenceProvider
 {
     private readonly IJSRuntime _jsRuntime;
+    private readonly IJSInProcessRuntime? _jsInProcessRuntime;
     private readonly ILogger<LocalStorageProvider>? _logger;
 
     /// <summary>
@@ -29,9 +31,57 @@ public class LocalStorageProvider : IPersistenceProvider
     public LocalStorageProvider(IJSRuntime jsRuntime, ILogger<LocalStorageProvider>? logger = null)
     {
         _jsRuntime = jsRuntime ?? throw new ArgumentNullException(nameof(jsRuntime));
+        _jsInProcessRuntime = jsRuntime as IJSInProcessRuntime;
         _logger = logger;
     }
 
+    /// <summary>
+    /// Gets whether synchronous operations are available (WebAssembly mode).
+    /// </summary>
+    public bool SupportsSyncOperations => _jsInProcessRuntime != null;
+
+    /// <summary>
+    /// Synchronously loads a value from localStorage.
+    /// Only available in WebAssembly mode where <see cref="IJSInProcessRuntime"/> is available.
+    /// </summary>
+    /// <param name="key">The storage key.</param>
+    /// <returns>The stored value, or null if not found.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when called in Blazor Server mode where synchronous JS interop is not available.
+    /// </exception>
+    public string? LoadSync(string key)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(key);
+
+        if (_jsInProcessRuntime == null)
+        {
+            throw new InvalidOperationException(
+                "Synchronous JS interop is not available. " +
+                "Use LoadAsync instead, or ensure you're running in WebAssembly mode.");
+        }
+
+        try
+        {
+            var value = _jsInProcessRuntime.Invoke<string?>("localStorage.getItem", key);
+
+            if (value != null)
+            {
+                _logger?.LogDebug("Loaded from localStorage key: {Key}, Size: {Size:N0} bytes (sync)", key, value.Length);
+            }
+            else
+            {
+                _logger?.LogDebug("No value found in localStorage for key: {Key} (sync)", key);
+            }
+
+            return value;
+        }
+        catch (Exception ex)
+        {
+            _logger?.LogWarning(ex, "Failed to load from localStorage key: {Key} (sync)", key);
+            return null;
+        }
+    }
+
     /// <inheritdoc />
     public async Task<string?> LoadAsync(string key)
     {