Add middleware context and persistence options for state management

- Introduced MiddlewareContext<TState> to encapsulate state and execution phase information for middleware.
- Enhanced PersistenceMiddleware<TState> to support custom persistence options including transformation on save/load and hydration callbacks.
- Created PersistenceOptions<TState> class to configure persistence behavior, including debounce settings and hydration control.
- Implemented unit tests for middleware and persistence options to ensure correct behavior and error handling.
- Added selector subscription tests to verify correct notifications on state changes.

Author: mashrulhaque

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

@@ -140,4 +140,42 @@ IDisposable Subscribe<TSelected>(
         Func<TState, TSelected> selector,
         Action<TSelected> callback,
         IEqualityComparer<TSelected> comparer);
+
+    /// <summary>
+    /// Subscribes to state changes using a memoized selector.
+    /// The callback is only invoked when the selector result changes.
+    /// </summary>
+    /// <typeparam name="TSelected">The type of the selected value from the state.</typeparam>
+    /// <param name="selector">A memoized selector that computes the derived value.</param>
+    /// <param name="callback">Callback invoked when the selected value changes.</param>
+    /// <returns>Disposable subscription. Call Dispose to unsubscribe.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="selector"/> or <paramref name="callback"/> is null.</exception>
+    /// <remarks>
+    /// <para>
+    /// This overload uses a pre-defined <see cref="Selectors.ISelector{TState, TResult}"/> for efficient
+    /// memoized state derivation. Useful for complex computed values that should only recompute
+    /// when their dependencies change.
+    /// </para>
+    /// <para>
+    /// The selector is responsible for memoization; this method simply uses its Select method.
+    /// </para>
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Define selectors once (e.g., in a static class)
+    /// public static class CartSelectors
+    /// {
+    ///     public static readonly ISelector&lt;CartState, decimal&gt; Total =
+    ///         Selectors.Create&lt;CartState, decimal&gt;(s => s.Items.Sum(i => i.Price * i.Quantity));
+    /// }
+    ///
+    /// // Subscribe using the selector
+    /// var subscription = store.Subscribe(CartSelectors.Total, total => {
+    ///     Console.WriteLine($"Cart total: {total:C}");
+    /// });
+    /// </code>
+    /// </example>
+    IDisposable Subscribe<TSelected>(
+        Selectors.ISelector<TState, TSelected> selector,
+        Action<TSelected> callback);
 }

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

@@ -1,4 +1,5 @@
 using EasyAppDev.Blazor.Store.Middleware;
+using EasyAppDev.Blazor.Store.Selectors;
 using Microsoft.Extensions.Logging;
 
 namespace EasyAppDev.Blazor.Store.Core;
@@ -17,6 +18,7 @@ public class Store<TState> : IStore<TState>, IDisposable where TState : notnull
     private readonly ISubscriptionManager<TState> _subscriptionManager;
     private readonly MiddlewarePipeline<TState>? _middlewarePipeline;
     private readonly ILogger<Store<TState>>? _logger;
+    private readonly StoreErrorHandler<TState>? _errorHandler;
     private bool _disposed;
     private readonly AsyncLocal<int> _updateDepth = new();
 
@@ -30,20 +32,23 @@ public class Store<TState> : IStore<TState>, IDisposable where TState : notnull
     /// <param name="middlewarePipelineLogger">Optional logger for middleware pipeline.</param>
     /// <param name="logger">Optional logger for store operations.</param>
     /// <param name="middlewareOptions">Optional configuration options for middleware pipeline.</param>
+    /// <param name="errorHandler">Optional centralized error handler for store errors.</param>
     public Store(
         TState initialState,
         ISubscriptionManager<TState> subscriptionManager,
         IEqualityComparer<TState>? comparer = null,
         IEnumerable<IMiddleware<TState>>? middlewares = null,
         ILogger<MiddlewarePipeline<TState>>? middlewarePipelineLogger = null,
         ILogger<Store<TState>>? logger = null,
-        MiddlewarePipelineOptions? middlewareOptions = null)
+        MiddlewarePipelineOptions? middlewareOptions = null,
+        StoreErrorHandler<TState>? errorHandler = null)
     {
         _state = initialState ?? throw new ArgumentNullException(nameof(initialState));
         _subscriptionManager = subscriptionManager ?? throw new ArgumentNullException(nameof(subscriptionManager));
         _lock = new SemaphoreSlim(1, 1);
         _comparer = comparer ?? EqualityComparer<TState>.Default;
         _logger = logger;
+        _errorHandler = errorHandler;
 
         if (middlewares?.Any() == true)
         {
@@ -229,6 +234,22 @@ public IDisposable Subscribe<TSelected>(
         return _subscriptionManager.Subscribe(selector, callback, () => _state, comparer);
     }
 
+    /// <inheritdoc />
+    public IDisposable Subscribe<TSelected>(
+        ISelector<TState, TSelected> selector,
+        Action<TSelected> callback)
+    {
+        ArgumentNullException.ThrowIfNull(selector);
+        ArgumentNullException.ThrowIfNull(callback);
+        ThrowIfDisposed();
+
+        return _subscriptionManager.Subscribe(
+            state => selector.Select(state),
+            callback,
+            () => _state,
+            EqualityComparer<TSelected>.Default);
+    }
+
     private void NotifySubscribers()
     {
         _subscriptionManager.NotifyAll();
@@ -240,6 +261,25 @@ private void ThrowIfDisposed()
             throw new ObjectDisposedException(nameof(Store<TState>));
     }
 
+    /// <summary>
+    /// Reports an error to the registered error handler.
+    /// </summary>
+    internal void HandleError(Exception exception, ErrorLocation location, string? action = null)
+    {
+        var error = new StoreError<TState>(exception, _state, action, location);
+
+        _logger?.LogError(exception, "Store error in {Location}: {Message}", location, exception.Message);
+
+        try
+        {
+            _errorHandler?.Invoke(error);
+        }
+        catch (Exception handlerEx)
+        {
+            _logger?.LogError(handlerEx, "Error in store error handler");
+        }
+    }
+
     /// <inheritdoc />
     public void Dispose()
     {

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

@@ -18,6 +18,7 @@ public class StoreBuilder<TState> where TState : notnull
     private ILogger<Store<TState>>? _storeLogger;
     private ILogger<SubscriptionManager<TState>>? _subscriptionManagerLogger;
     private MiddlewarePipelineOptions? _middlewareOptions;
+    private StoreErrorHandler<TState>? _errorHandler;
 
     private StoreBuilder(TState initialState)
     {
@@ -141,6 +142,49 @@ public StoreBuilder<TState> ConfigureMiddleware(Action<MiddlewarePipelineOptions
         return this;
     }
 
+    /// <summary>
+    /// Registers a centralized error handler for store operations.
+    /// Errors from middleware, subscribers, and persistence are routed to this handler.
+    /// </summary>
+    /// <param name="errorHandler">The error handler delegate.</param>
+    /// <returns>The builder instance for chaining.</returns>
+    /// <example>
+    /// <code>
+    /// builder.OnError(error =>
+    /// {
+    ///     logger.LogError(error.Exception,
+    ///         "Store error in {Location}: {Message}",
+    ///         error.Location,
+    ///         error.Exception.Message);
+    ///
+    ///     // Report to error tracking service
+    ///     errorTracker.CaptureException(error.Exception, new Dictionary&lt;string, object&gt;
+    ///     {
+    ///         ["store"] = typeof(TState).Name,
+    ///         ["action"] = error.Action ?? "unknown",
+    ///         ["location"] = error.Location.ToString()
+    ///     });
+    /// });
+    /// </code>
+    /// </example>
+    public StoreBuilder<TState> OnError(StoreErrorHandler<TState> errorHandler)
+    {
+        _errorHandler = errorHandler ?? throw new ArgumentNullException(nameof(errorHandler));
+        return this;
+    }
+
+    /// <summary>
+    /// Registers an error handler using an action that receives the error.
+    /// </summary>
+    /// <param name="handler">The error handler action.</param>
+    /// <returns>The builder instance for chaining.</returns>
+    public StoreBuilder<TState> OnError(Action<StoreError<TState>> handler)
+    {
+        ArgumentNullException.ThrowIfNull(handler);
+        _errorHandler = handler.Invoke;
+        return this;
+    }
+
     /// <summary>
     /// Enables Redux DevTools integration with lazy IJSRuntime resolution.
     /// Works in all render modes: Server, WebAssembly, and Auto (Server → WASM).
@@ -184,6 +228,35 @@ public StoreBuilder<TState> WithPersistence(
         return hydratedBuilder.WithMiddleware(middleware);
     }
 
+    /// <summary>
+    /// Adds state persistence with full configuration options.
+    /// </summary>
+    /// <param name="provider">The persistence provider.</param>
+    /// <param name="options">The persistence configuration options.</param>
+    /// <returns>The builder instance for chaining.</returns>
+    /// <example>
+    /// <code>
+    /// .WithPersistence(provider, new PersistenceOptions&lt;CartState&gt;
+    /// {
+    ///     Key = "cart-state",
+    ///     DebounceMs = 500,
+    ///     OnHydrationSuccess = state => logger.LogInformation("Loaded {Count} items", state.Items.Count),
+    ///     ShouldPersist = (prev, curr, action) => action != "TEMP_UPDATE",
+    ///     TransformOnLoad = state => state with { CheckoutInProgress = false }
+    /// })
+    /// </code>
+    /// </example>
+    public StoreBuilder<TState> WithPersistence(
+        IPersistenceProvider provider,
+        PersistenceOptions<TState> options)
+    {
+        ArgumentNullException.ThrowIfNull(provider);
+        ArgumentNullException.ThrowIfNull(options);
+
+        var middleware = new PersistenceMiddleware<TState>(provider, options);
+        return WithMiddleware(middleware);
+    }
+
     /// <summary>
     /// Attempts to load persisted state. Since synchronous JS interop is not available
     /// without explicit IJSInProcessRuntime, this method now returns the current builder.
@@ -229,7 +302,8 @@ public async Task<StoreBuilder<TState>> WithHydratedStateAsync(
                         _middlewarePipelineLogger = this._middlewarePipelineLogger,
                         _storeLogger = this._storeLogger,
                         _subscriptionManagerLogger = this._subscriptionManagerLogger,
-                        _middlewareOptions = this._middlewareOptions
+                        _middlewareOptions = this._middlewareOptions,
+                        _errorHandler = this._errorHandler
                     };
                     builder._middlewares.AddRange(this._middlewares);
                     return builder;
@@ -261,6 +335,7 @@ public IStore<TState> Build()
             middlewares: _middlewares,
             middlewarePipelineLogger: _middlewarePipelineLogger,
             logger: _storeLogger,
-            middlewareOptions: _middlewareOptions);
+            middlewareOptions: _middlewareOptions,
+            errorHandler: _errorHandler);
     }
 }

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

@@ -0,0 +1,66 @@
+namespace EasyAppDev.Blazor.Store.Core;
+
+/// <summary>
+/// Represents an error that occurred during store operations.
+/// </summary>
+/// <typeparam name="TState">The type of state.</typeparam>
+/// <param name="Exception">The exception that was thrown.</param>
+/// <param name="State">The state at the time of the error (may be null if not available).</param>
+/// <param name="Action">The action name associated with the operation (if any).</param>
+/// <param name="Location">Where in the store lifecycle the error occurred.</param>
+public record StoreError<TState>(
+    Exception Exception,
+    TState? State,
+    string? Action,
+    ErrorLocation Location) where TState : notnull
+{
+    /// <summary>
+    /// Gets a concise error message including location and action.
+    /// </summary>
+    public string Message => Action != null
+        ? $"[{Location}] Error during '{Action}': {Exception.Message}"
+        : $"[{Location}] Error: {Exception.Message}";
+}
+
+/// <summary>
+/// Indicates where in the store lifecycle an error occurred.
+/// </summary>
+public enum ErrorLocation
+{
+    /// <summary>
+    /// Error occurred in middleware (OnBeforeUpdate or OnAfterUpdate).
+    /// </summary>
+    Middleware,
+
+    /// <summary>
+    /// Error occurred in the state updater function.
+    /// </summary>
+    Updater,
+
+    /// <summary>
+    /// Error occurred in a subscriber callback.
+    /// </summary>
+    Subscriber,
+
+    /// <summary>
+    /// Error occurred during state persistence (save or load).
+    /// </summary>
+    Persistence,
+
+    /// <summary>
+    /// Error occurred during DevTools integration.
+    /// </summary>
+    DevTools,
+
+    /// <summary>
+    /// Error occurred during state hydration.
+    /// </summary>
+    Hydration
+}
+
+/// <summary>
+/// Delegate for handling store errors.
+/// </summary>
+/// <typeparam name="TState">The type of state.</typeparam>
+/// <param name="error">The error that occurred.</param>
+public delegate void StoreErrorHandler<TState>(StoreError<TState> error) where TState : notnull;

src/EasyAppDev.Blazor.Store/EasyAppDev.Blazor.Store.csproj

@@ -15,7 +15,7 @@
   <PropertyGroup>
     <!-- NuGet Package Metadata -->
     <PackageId>EasyAppDev.Blazor.Store</PackageId>
-    <Version>1.2.0</Version>
+    <Version>2.0.0</Version>
     <Authors>Mashrul Haque</Authors>
     <Company>EasyAppDev</Company>
     <Product>EasyAppDev.Blazor.Store</Product>
@@ -28,29 +28,27 @@
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageIcon>icon.png</PackageIcon>
     <PackageReleaseNotes>
-v1.2.0 - Phase 2: Cleanup and Simplification
-
-Breaking Changes:
-- Removed deprecated synchronous Update() method from IStateWriter and Store
-- Removed deprecated WithJSRuntime() and old WithDevTools() overloads from StoreBuilder
-- StoreComponent&lt;T&gt; slimmed down - utility methods moved to StoreComponentWithUtilities&lt;T&gt;
+v2.0.0 - Phase 3: Core Enhancements
 
 New Features:
-- StoreComponentWithUtilities&lt;T&gt; for components needing debounce, throttle, lazy loading, and async execution
-- UpdateWithAsync extension method for simplified async data loading patterns
-- DevTools now uses IServiceProvider for lazy IJSRuntime resolution (Blazor Server compatibility)
+- ISelector subscription: Subscribe to stores using memoized selectors (store.Subscribe(MySelectors.Total, callback))
+- Functional middleware: Add inline middleware with .Use() and conditional .UseWhen() syntax
+- MiddlewareContext: Rich context object passed to middleware with phase info, services, and state
+- PersistenceOptions: Full configuration for persistence with callbacks (OnHydrationSuccess, OnHydrationFailure, etc.)
+- Structured error handling: StoreError&lt;T&gt; record with ErrorLocation enum for centralized error management
+- OnError handler: Register error handlers in StoreBuilder for unified error tracking
 
-Upgrade Guide:
-- Replace Update() calls with await Update() or await Store.UpdateAsync()
-- Components using UpdateDebounced, UpdateThrottled, ExecuteAsync, or LazyLoad should inherit from StoreComponentWithUtilities&lt;T&gt;
-- Replace .WithJSRuntime().WithDevTools() with .WithDevTools(sp, "StoreName")
+Breaking Changes:
+- Middleware now receives MiddlewareContext instead of raw parameters (for functional middleware)
+- IStateObservable has new Subscribe overload for ISelector
 
-v1.1.0 - Phase 1: Bug Fixes and Polish
+Migration Guide:
+- Add .OnError() to StoreBuilder for centralized error handling
+- Use new PersistenceOptions for advanced persistence control
+- Consider using .Use() for simple inline middleware
 
-- AsyncData&lt;T&gt; converted from class to record for value equality
-- MemoizedSelector thread-safety improvements
-- Proper logging for persistence hydration errors
-- Enhanced XML documentation
+v1.2.0 - Phase 2: Cleanup and Simplification
+(See previous release notes)
     </PackageReleaseNotes>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>