Enhance documentation for UpdateThrottled and Getting Started

- Updated UpdateThrottled page with detailed examples, API signature, and best practices for throttling.
- Added explanations for leading vs trailing edge throttling and included recommended intervals for various use cases.
- Improved the Getting Started page by clarifying registration options and emphasizing the importance of required services for utilities and async actions.

Author: mashrulhaque

README.md

@@ -72,6 +72,38 @@ dotnet add package EasyAppDev.Blazor.Store
 
 ---
 
+## Required Services
+
+Before using `StoreComponent<TState>` or async helpers, you **MUST** register utility services:
+
+### Quick Setup (Recommended)
+```csharp
+builder.Services.AddStoreWithUtilities(
+    new MyState(),
+    (store, sp) => store.WithDefaults(sp, "MyStore"));
+```
+
+### Manual Setup
+```csharp
+// 1. Register utilities (required for UpdateDebounced, UpdateThrottled, LazyLoad)
+builder.Services.AddStoreUtilities();
+
+// 2. Register async executor (required for ExecuteAsync)
+builder.Services.AddAsyncActionExecutor<MyState>();
+
+// 3. Register store
+builder.Services.AddStore(
+    new MyState(),
+    (store, sp) => store.WithDefaults(sp, "MyStore"));
+```
+
+### What Each Service Provides
+- **`AddStoreUtilities()`**: Registers `IDebounceManager`, `IThrottleManager`, `ILazyCache` (scoped)
+- **`AddAsyncActionExecutor<T>()`**: Enables `ExecuteAsync` helper methods (scoped)
+- **`AddStoreWithUtilities()`**: One-liner that combines all registrations (recommended)
+
+---
+
 ## Quick Start
 
 **3 steps. 1 minute. Zero boilerplate.**
@@ -104,12 +136,21 @@ public record CounterState(int Count, string? LastAction = null)
 In your `Program.cs`:
 
 ```csharp
+// Option 1: All-in-one registration (RECOMMENDED)
+builder.Services.AddStoreWithUtilities(
+    new CounterState(0),
+    (store, sp) => store.WithDefaults(sp, "Counter"));
+
+// Option 2: Manual registration (if you need more control)
+builder.Services.AddStoreUtilities();                    // Required for async helpers
+builder.Services.AddAsyncActionExecutor<CounterState>(); // Required for ExecuteAsync
 builder.Services.AddStore(
     new CounterState(0),
     (store, sp) => store.WithDefaults(sp, "Counter"));
 ```
 
-> 💡 **Tip**: Use `WithDefaults()` for one-liner setup with JSRuntime, DevTools, and Logging!
+> 💡 **Tip**: Use `AddStoreWithUtilities()` for one-liner setup that includes all required services!
+> 💡 **Tip**: Use `WithDefaults()` for JSRuntime, DevTools, and Logging configuration!
 
 ### Step 3: Use in Components
 
@@ -708,7 +749,7 @@ public record CounterState(int Count, string? LastAction = null)
 }
 
 // Program.cs
-builder.Services.AddStore(
+builder.Services.AddStoreWithUtilities(
     new CounterState(0),
     (store, sp) => store.WithDefaults(sp, "Counter"));
 
@@ -758,7 +799,7 @@ public record TodoState(ImmutableList<Todo> Todos)
 }
 
 // Program.cs
-builder.Services.AddStore(
+builder.Services.AddStoreWithUtilities(
     TodoState.Initial,
     (store, sp) => store
         .WithDefaults(sp, "Todos")
@@ -885,7 +926,7 @@ public record AuthState(User? CurrentUser, bool IsLoading, string? Error)
 
 // Program.cs
 builder.Services.AddScoped<IAuthService, AuthService>();
-builder.Services.AddStore(
+builder.Services.AddStoreWithUtilities(
     AuthState.Initial,
     (store, sp) => store
         .WithDefaults(sp, "Auth")
@@ -987,7 +1028,7 @@ public record ChartDataPoint(DateTime Time, decimal Value);
 public record ServerStatus(bool IsHealthy, int ResponseTimeMs);
 
 // Program.cs
-builder.Services.AddStore(
+builder.Services.AddStoreWithUtilities(
     DashboardState.Initial,
     (store, sp) => store.WithDefaults(sp, "Dashboard"));
 
@@ -1511,7 +1552,7 @@ Explore the async helpers in action with our interactive demos:
 Automatically save and restore state:
 
 ```csharp
-builder.Services.AddStore(
+builder.Services.AddStoreWithUtilities(
     new AppState(),
     (store, sp) => store
         .WithDefaults(sp, "MyApp")
@@ -1530,7 +1571,9 @@ Time-travel debugging with Redux DevTools:
 ```csharp
 builder.Services.AddStore(
     new AppState(),
-    store => store.WithDevTools("MyApp"));
+    (store, sp) => store
+        .WithJSRuntime(sp.GetRequiredService<IJSRuntime>())
+        .WithDevTools("MyApp"));
 ```
 
 **Features:**
@@ -1646,13 +1689,13 @@ public class LoggingMiddleware<TState> : IMiddleware<TState> where TState : notn
 
     public LoggingMiddleware(ILogger<LoggingMiddleware<TState>> logger) => _logger = logger;
 
-    public Task OnBeforeUpdateAsync(TState currentState, string action)
+    public Task OnBeforeUpdateAsync(TState currentState, string? action)
     {
         _logger.LogInformation("Before: {Action}", action);
         return Task.CompletedTask;
     }
 
-    public Task OnAfterUpdateAsync(TState newState, string action)
+    public Task OnAfterUpdateAsync(TState previousState, TState newState, string? action)
     {
         _logger.LogInformation("After: {Action} -> {State}", action, newState);
         return Task.CompletedTask;
@@ -1662,7 +1705,10 @@ public class LoggingMiddleware<TState> : IMiddleware<TState> where TState : notn
 // Register
 builder.Services.AddStore(
     new AppState(),
-    store => store.WithMiddleware<LoggingMiddleware<AppState>>());
+    (store, sp) => {
+        var logger = sp.GetRequiredService<ILogger<LoggingMiddleware<AppState>>>();
+        return store.WithMiddleware(new LoggingMiddleware<AppState>(logger));
+    });
 ```
 
 **Built-in middleware:**
@@ -1677,80 +1723,170 @@ builder.Services.AddStore(
 
 ### StoreComponent<TState>
 
-Base component class with automatic subscription:
+Base component class with automatic subscription and async helpers:
 
 ```csharp
 public abstract class StoreComponent<TState> : ComponentBase
 {
-    protected TState State { get; }                                    // Current state
-    protected Task Update(Func<TState, TState> updater);              // Update (returns Task)
-    protected Task UpdateAsync(Func<TState, Task<TState>> updater);   // Async update
+    // State access
+    protected TState State { get; }
+
+    // Core update methods
+    protected Task Update(Func<TState, TState> updater, string? action = null);
+    protected Task UpdateAsync(Func<TState, Task<TState>> asyncUpdater, string? action = null);
+
+    // Debounced updates
+    protected Task UpdateDebounced(
+        Func<TState, TState> updater,
+        int delayMilliseconds,
+        [CallerMemberName] string? action = null);
+    protected Task UpdateDebouncedAsync(
+        Func<TState, Task<TState>> asyncUpdater,
+        int delayMilliseconds,
+        [CallerMemberName] string? action = null);
+
+    // Throttled updates
+    protected Task UpdateThrottled(
+        Func<TState, TState> updater,
+        int intervalMilliseconds,
+        [CallerMemberName] string? action = null);
+    protected Task UpdateThrottledAsync(
+        Func<TState, Task<TState>> asyncUpdater,
+        int intervalMilliseconds,
+        [CallerMemberName] string? action = null);
+
+    // Async action execution (requires IAsyncActionExecutor<TState> registration)
+    protected Task ExecuteAsync<TResult>(
+        Func<Task<TResult>> asyncAction,
+        Func<TState, TState> loading,
+        Func<TState, TResult, TState> success,
+        Func<TState, Exception, TState>? error = null,
+        [CallerMemberName] string? action = null);
+
+    // Lazy loading with caching
+    protected Task<T> LazyLoad<T>(
+        string cacheKey,
+        Func<Task<T>> loader,
+        TimeSpan? cacheFor = null);
 }
 ```
 
+> **Note**: `[CallerMemberName]` automatically fills the `action` parameter with the calling method name for DevTools/logging.
+
 ### SelectorStoreComponent<TState>
 
 Optimized component with granular reactivity:
 
 ```csharp
 public abstract class SelectorStoreComponent<TState> : ComponentBase
 {
+    // State access
     protected TState State { get; }
     protected object? Selected { get; }
-    protected abstract object SelectState(TState state);  // Override this
+
+    // Required: Override this to select specific state slice
+    protected abstract object SelectState(TState state);
+
+    // Update methods (same as StoreComponent)
+    protected Task Update(Func<TState, TState> updater, string? action = null);
+    protected Task UpdateAsync(Func<TState, Task<TState>> asyncUpdater, string? action = null);
 }
 ```
 
+> **Note**: `SelectorStoreComponent` does NOT include async helpers (UpdateDebounced, ExecuteAsync, LazyLoad). It's focused solely on granular re-rendering optimization. Use `StoreComponent` if you need async helpers.
+
 ### IStore<TState>
 
 Store interface (rarely used directly):
 
 ```csharp
-public interface IStore<TState>
+public interface IStore<TState> :
+    IStateReader<TState>,
+    IStateWriter<TState>,
+    IStateObservable<TState>,
+    IDisposable
+    where TState : notnull
+{
+    // Composed from three segregated interfaces (Interface Segregation Principle)
+}
+```
+
+**Component Interfaces:**
+
+```csharp
+// Read-only state access
+public interface IStateReader<TState> where TState : notnull
 {
     TState GetState();
+}
+
+// State update operations
+public interface IStateWriter<TState> where TState : notnull
+{
     void Update(Func<TState, TState> updater, string? action = null);
     Task UpdateAsync(Func<TState, TState> updater, string? action = null);
     Task UpdateAsync(Func<TState, Task<TState>> asyncUpdater, string? action = null);
+}
+
+// Subscription management
+public interface IStateObservable<TState> where TState : notnull
+{
     IDisposable Subscribe(Action<TState> callback);
     IDisposable Subscribe<TSelected>(
         Func<TState, TSelected> selector,
         Action<TSelected> callback);
+    IDisposable Subscribe<TSelected>(
+        Func<TState, TSelected> selector,
+        Action<TSelected> callback,
+        IEqualityComparer<TSelected> comparer);
 }
 ```
 
+> **Note**: The segregated interface design allows components to depend only on the capabilities they need (SOLID principles).
+
 ### Registration
 
 ```csharp
-// Simple - no configuration
-services.AddStore(new MyState());
-
-// With defaults (recommended)
-services.AddStore(
+// RECOMMENDED: All-in-one with utilities
+builder.Services.AddStoreWithUtilities(
     new MyState(),
     (store, sp) => store.WithDefaults(sp, "MyStore"));
 
-// Full configuration
-services.AddStore(
+// Manual registration (when you need control)
+builder.Services.AddStoreUtilities();                  // Registers async helper services
+builder.Services.AddAsyncActionExecutor<MyState>();    // Required for ExecuteAsync
+builder.Services.AddStore(
     new MyState(),
-    (store, sp) => store
-        .WithDefaults(sp, "StoreName")
-        .WithPersistence(sp, "storage-key")
-        .WithDiagnosticsIfAvailable(sp)
-        .WithMiddleware<MyMiddleware>()
-);
+    (store, sp) => store.WithDefaults(sp, "MyStore"));
+
+// Simple - minimal configuration (no async helpers)
+builder.Services.AddStore(new MyState());
 
-// Manual configuration (for advanced scenarios)
-services.AddStore(
+// Full configuration with middleware
+builder.Services.AddStoreWithUtilities(
     new MyState(),
-    (store, sp) => store
-        .WithJSRuntime(sp.GetRequiredService<IJSRuntime>())
-        .WithDevTools("StoreName")
-        .WithLogging()
-        .WithMiddleware<MyMiddleware>()
-);
+    (store, sp) => {
+        var customMiddleware = new MyCustomMiddleware<MyState>();
+        return store
+            .WithDefaults(sp, "StoreName")
+            .WithPersistence(sp, "storage-key")
+            .WithDiagnosticsIfAvailable(sp)
+            .WithMiddleware(customMiddleware);  // Instance, not generic!
+    });
+
+// Scoped stores (Blazor Server)
+builder.Services.AddScopedStoreWithUtilities(
+    new SessionState(),
+    store => store.WithLogging());
+
+// Scoped with factory
+builder.Services.AddScopedStoreWithUtilities(
+    sp => new UserState(sp.GetRequiredService<IUserContext>().UserId),
+    store => store.WithLogging());
 ```
 
+> **Important**: Use `WithMiddleware(instance)` with a middleware **instance**, NOT `WithMiddleware<T>()` - the generic method doesn't exist!
+
 
 ---
 
@@ -1996,6 +2132,33 @@ Update(s => s.LoadDataAsync(service));  // Returns Task!
 await UpdateAsync(async s => await s.LoadDataAsync(service));
 ```
 
+### ExecuteAsync not available / throwing InvalidOperationException?
+
+❌ **Error:** `IAsyncActionExecutor<MyState> is not registered`
+
+✅ **Solution:** Register the async executor before using `ExecuteAsync`:
+
+```csharp
+// Option 1: All-in-one (recommended)
+builder.Services.AddStoreWithUtilities(
+    new MyState(),
+    (store, sp) => store.WithDefaults(sp, "MyStore"));
+
+// Option 2: Manual registration
+builder.Services.AddAsyncActionExecutor<MyState>();
+builder.Services.AddStore(new MyState(), ...);
+```
+
+### UpdateDebounced/UpdateThrottled/LazyLoad not available?
+
+✅ **Solution:** Register utility services:
+
+```csharp
+builder.Services.AddStoreUtilities();  // Required!
+// OR
+builder.Services.AddStoreWithUtilities(...);  // Includes utilities
+```
+
 ---
 
 ## Documentation