Actions

Overview

Actions are the messages Reservoir processes to update state or run effects. They are the entry point for work handled by the store and its reducers/effects pipeline. (IAction, IStore)

What Is an Action?

An action is a simple, immutable message that represents an event that can trigger state changes or effects. Actions carry only the minimal data needed for reducers and effects to do their work. (IAction)

// Example from Spring sample: a simple action with a payload
internal sealed record SetEntityIdAction(string EntityId) : IAction;

Actions implement the IAction marker interface. The interface describes actions as immutable records that carry minimal data for reducers and effects.

Why Actions?

Reservoir uses actions to drive state changes and side effects through the store pipeline. This makes it explicit when state can change and keeps reducers/effects focused on the data they receive. (IStore)

Dispatching Actions

Actions are dispatched to the global IStore. The store is the central hub that coordinates all state management.

From a Blazor Component

If your component inherits from StoreComponent, use the Dispatch method:

public class MyComponent : StoreComponent
{
    private void HandleButtonClick()
    {
        Dispatch(new SetEntityIdAction("entity-123"));
    }
    
    private void HandleItemSelected(string itemId)
    {
        Dispatch(new SetEntityIdAction(itemId));
    }
}

From Any Service

Inject IStore and call Dispatch:

public class SelectionService
{
    private IStore Store { get; }
    
    public SelectionService(IStore store)
    {
        Store = store;
    }
    
    public void Select(string entityId)
    {
        Store.Dispatch(new SetEntityIdAction(entityId));
    }
}

The Action Lifecycle

When you dispatch an action, it flows through the store's pipeline:

1. Middleware - The action flows through any registered middleware
2. Reducers - Synchronous state updates happen here
3. Listeners - Subscribers are notified after the action is processed
4. Effects - Asynchronous work runs last and can yield more actions

Multiple feature states can have reducers that respond to the same action because the store runs each feature's root reducer when an action is dispatched. (Store.ReduceFeatureStates)

Dispatch remains synchronous through reducers and listeners; effects run asynchronously after reducers and listeners complete. (Store.CoreDispatch)

Keep Actions Lean

Actions should carry only the data needed for reducers and effects. The IAction documentation emphasizes minimal payloads to keep actions focused on intent. (IAction)

Summary

• Actions are immutable records implementing IAction
• Dispatch actions to IStore to trigger state changes and effects
• Actions flow through middleware → reducers → listeners → effects
• Multiple feature states can respond to the same action

Next Steps

• Reservoir Overview - Understand how the pieces fit together
• Reducers - Learn how reducers transform state based on actions
• Effects - Handle async operations triggered by actions
• Feature State - Organize state into feature slices
• Store - Understand the central hub that coordinates actions, reducers, and effects