States

Defining a State

A state represents a slice of your application's data. It should be:

• Immutable (defined as a record)
• Serializable (for debugging, testing, or persistence)
• Focused (represents a single domain or feature)

Example: Counter State

CounterState.cs

public record CounterState : IStateFeature
{
    public int Count { get; init; }
}

🎯 Manual State Hooking

The manual subscription approach is the most performant and reliable way to handle state updates — in StatePulse or any other state management library.

By explicitly subscribing and unsubscribing to a specific state, only the components that depend on that state are re-rendered.
This avoids unnecessary rendering and offers precise control.

✅ Why This Is Optimal

• No overhead from global tracking or base components
• Fine-grained control over component updates
• Best performance, especially in large apps
• Works without any framework-specific magic

⚠️ The downside? It requires more boilerplate.
That's why many libraries introduce alternatives like global components, wrappers, or base components — but these come with trade-offs in flexibility or overhead.

🛠️ Example: Manual State Hook

Counter.razor.cs

public partial class Counter : ComponentBase, IAsyncDisposable
{
    [Inject] IStateAccessor<CounterState> State { get; set; }
    [Inject] private IDispatcher Dispatcher { get; set; }

    protected override void OnInitialized()
    {
        State.OnStateChangedNoDetails += ShouldUpdate;
    }

    private void ShouldUpdate(object? sender, EventArgs e)
    {
        _ = InvokeAsync(StateHasChanged);
    }

    private async Task Increment()
    {
        await Dispatcher.Prepare<IncrementCounterAction>()
             .With(p => p.Delay, 1)
             .DispatchAsync();
    }

    public ValueTask DisposeAsync()
    {
        State.OnStateChangedNoDetails -= ShouldUpdate;
        return ValueTask.CompletedTask;
    }
}

🌀 Zero-Boilerplate Without Compromise

StatePulse does not force you to inherit from a base component or use a global component to track state changes.
Instead, StatePulse provides a clever and efficient mechanism to track components that request state,
binding them automatically with:

• ✅ Memory leak protection
• ⚡ Optimized getters
• 🧼 Zero boilerplate on your side

This ensures no architectural compromises burden placed on you.

StatePulse offers a zero-boilerplate way to subscribe to and track component-bound state changes — using IStatePulse.

This method requires no manual subscription or disposal, yet still tracks updates per component, safely and efficiently.

🛠️ Example: Zero-Boilerplate State Hook

Counter.razor.cs

public partial class Counter : ComponentBase
{
    [Inject] IStatePulse Pulse { get; set; }
    private CounterState State => Pulse.StateOf<CounterState>(() => this, ShouldUpdate);
    public Task ShouldUpdate() => InvokeAsync(StateHasChanged);
    private async Task Increment()
    {
        await Pulse.Dispatcher.Prepare<IncrementCounterAction>()
             .With(p => p.Delay, 1)
             .DispatchAsync();
    }
}

Note: when injecting IStatePulse, you do not need to inject IDispatcher.

📝 Note on StateOf() Usage

You might notice that Pulse.StateOf<CounterState>(() => this, ShouldUpdate) is called during every render.
At first glance, this may seem inefficient or even odd syntax but it’s actually intentional, efficient and necessary.

When StateOf() is called:

• StatePulse checks whether the component (identified by ()=> this) is already being tracked.
• If not, it sets up the binding and associates the provided ShouldUpdate method as a re-render callback (Slow first hit).
• If it is already tracked, the call becomes a fast property access with near-zero overhead (subsequent accesses are fast).

Mandatory Syntax As of v2.0+ compiler will generate an error when ()=> this is not exactly that and when ShouldUpdate is a lambda which is forbidden and has to be named method to avoid runtime issues.

The only cost is during the initial setup.
All future calls are optimized, cached and safe to run on every render, on every line.

This design ensures you always have up-to-date, reactive state with no boilerplate and minimal performance impact.