Actions for Async Work

Put state transitions behind named actions

Pinia actions are functions on a store that can read and update its state. They provide a named entry point for domain transitions such as loading a user, saving preferences, or clearing a session. An action can be synchronous or async, and can call other actions. Keeping coordinated updates in one place prevents components from each implementing slightly different loading, error, and success behavior.

A store action should express a domain operation rather than mirror every HTTP endpoint mechanically. For example, loadProfile can set pending state, call the API client, assign the profile, and map errors into a stable state. The component decides how that state is presented. Keep transport details in an API service when several stores or callers share them, and avoid making the store depend on a particular view's toast or layout.

Model async states explicitly

For a simple request, use separate data, pending, and error fields or a clear status union. Define whether old data stays visible while refreshing and when an error is cleared. Set pending before awaiting work and restore it in a finally block so both success and failure leave the store consistent. An action should return a useful result or rethrow an error if its caller needs to decide the next operation; swallowing every failure makes the UI assume success.

Concurrent actions need a policy. Two load calls can finish out of order, allowing an older response to overwrite newer data. Use a request key, generation counter, or AbortController to ensure only the current request commits. For writes, client cancellation does not prove the server did not commit; use idempotency and operation status when retries can duplicate side effects.

Keep invariants in the store

If changing one field requires updating others, expose one action that performs the transition. A checkout action might set the order, selected address, and status together. Avoid direct component mutations that can create combinations the domain does not permit. Pinia permits direct state writes, but convention and typed actions make transitions traceable in devtools and tests.

For setup stores, return refs, computed values, and functions. Returned refs become state and returned functions become actions. Do not return a private mutable ref if the store should own it; keep it unreturned or expose readonly state plus an action. Be aware of serialization and SSR requirements when deciding what is returned as state.

Coordinate actions without cycles

An action can call another store when a domain operation spans stores, but circular dependencies make initialization and tests harder. Keep dependency direction clear: a feature action can call an identity store, while the identity store should not call back into the feature. If several stores require the same operation, move the shared logic to a service or a higher-level orchestrator.

Actions are observable through Pinia devtools and can be instrumented with $onAction for timing or diagnostics. Do not log sensitive payloads or tokens. Use action hooks for cross-cutting measurement, not for hidden business mutations. The action remains the named unit that tests and components can understand.

Build a load action

Create a setup store with profile, pending, and error refs, plus a loadProfile action that calls an API service. The action sets pending, clears the prior error, awaits the service, assigns the result, maps a failure into a stable message or error code, and resets pending in finally. The component calls the action and renders the state; it does not duplicate request bookkeeping.

If the user can switch account ids quickly, associate each request with its id. Keep an active request key and only commit a response when it still matches. Abort the prior read where supported. A late failure from an old request should not replace the current account's state. Clear old profile data or label it as stale while loading according to the product's UX.

Add a save action with clear semantics

A save action should validate required local invariants before sending, capture a payload snapshot, and handle server validation separately from network failure. Return a result the caller can inspect, or throw a typed error for the component to display. Do not return a success-shaped empty object after a failed request. If the server may commit after a timeout, use an idempotency key or fetch the operation status before retrying.

Keep action names aligned with user or domain intent, such as savePreferences or acceptInvite, rather than generic setData. This makes devtools timelines understandable. For multi-step state transitions, use one action so subscribers do not observe a partially updated state between unrelated component writes.

Test success, failure, and overlap

Mock the API service and test the action's public contract. On success, verify state and returned result. On rejection, verify pending resets, prior data policy is respected, and the error is represented. Resolve two requests out of order and assert the stale result cannot overwrite the latest state. Test a retry after failure and confirm the error clears at the intended point.

Create a fresh Pinia instance per test and install it into the test app before calling the store. Shared singleton state can leak between test cases and create order-dependent results. If an action uses another store, provide the required store in the same Pinia instance. Stub the API boundary rather than mocking internal refs so tests exercise the action's actual transitions.

Observe without leaking data

Use devtools and action hooks to inspect timing and failures during development. In production instrumentation, record action name, duration, outcome, and safe identifiers. Avoid logging authentication tokens, full personal records, or request payloads. A centralized API service can attach trace context and handle common HTTP concerns while the store keeps domain state coherent.

As an exercise, implement a load action, add a stale-response test, then refactor a component that makes the same request directly. Confirm the component becomes simpler while state ownership remains clear. If the store grows into an unrelated request catalog, split it by domain instead of adding more generic flags.

The action should also define whether a failed refresh preserves the last successful value or clears it; consumers need a consistent policy.

Store actions should not become a second framework

Actions centralize transitions, but a giant store that handles every endpoint, toast, route, and cache policy becomes difficult to test. Keep actions cohesive around a domain and delegate transport to a shared API service. Let components own presentation and navigation while the store owns cross-view state and invariants. Use a query library for server cache lifecycle when freshness, deduplication, and invalidation are the main concern.

Pinia permits direct mutation, but unrestricted writes from many components make transitions hard to trace. Use actions where a change has invariants, async behavior, or shared side effects. Simple local form edits may not need a store action. Keep the API proportional to the state it owns.

Async correctness matters

Loading and error flags are not enough if requests can overlap. Define latest-wins, cancel-previous, or merge semantics and test them. For server writes, cancellation is not rollback. Idempotency and reconciliation belong at the API boundary when duplicate effects are possible. Reset pending in finally and make the failure result explicit.

SSR and tests require isolated Pinia instances. A store created from a global singleton can leak state between requests or test runs. Install the correct Pinia before calling a store outside a component. Avoid cyclic store imports by keeping dependency direction clear or moving shared orchestration to a service.

In an interview, describe a store action that owns a meaningful state transition, how it handles loading/error, and how it prevents stale responses. Explain what belongs in the API client versus the component. Mention fresh store instances in tests and SSR. This shows an action is a domain boundary, not merely a wrapper around fetch.

Store actions should not become a second networking framework. Keep transport concerns such as base URLs, authentication headers, retry policy, and response decoding in a shared API client when several features need them. The store action then coordinates domain state and calls a typed operation. This separation makes the API client testable and prevents every store from interpreting status codes differently.

For an action that updates several fields, prefer a patch or one synchronous state transition after the awaited result. Avoid exposing half-updated state during a long request unless the UX intentionally supports optimistic updates. If the operation is optimistic, keep a snapshot and rollback behavior for failure. For non-idempotent server writes, pass an idempotency key so retry after timeout cannot duplicate the effect.

Use Pinia's action instrumentation for observability, but keep it separate from business logic. A hook can record action duration and outcome, while the action remains responsible for setting application state. Redact arguments and return values before telemetry because they may contain personal or secret fields. Error messages should be useful to the component without exposing stack traces or upstream response bodies.

The action contract should explain whether it returns data, a success result, or throws. Consistent error semantics prevent a component from treating a failed request as success. Test the contract from a caller's perspective, including what state remains after an error and how a retry behaves.