Actions & Action Hooks

## Actions are the store's methods Pinia's docs describe **actions** as the equivalent of component methods, and the place for business logic. There is no separate mutation layer: an action changes state directly, calls APIs, calls other actions and returns whatever it likes. | Store style | How an action is declared | How it reaches state | |---|---|---| | Option store | a method under `actions` | `this.items`, `this.status` | | Setup store | a function returned from the setup function | closures over refs: `items.value` | ## Option-store actions and this In an option store, Pinia calls each action with the store as `this`, fully typed, including state, getters and other actions. That is why actions are written as **regular functions**: an arrow function takes `this` from its surrounding scope and never sees the store. The docs' own example carries the comment: since we rely on `this`, we cannot use an arrow function. Pinia also binds actions for you: calling a destructured action, `const { addItem } = order; addItem(item)`, still runs with the store as `this`, so actions (unlike state) can be destructured safely. ## Async actions Unlike getters, actions can be `async`. A typical checkout action follows four steps: 1. set a status: `this.status = 'submitting'`; 2. await the API: `const { id } = await api.placeOrder(this.items)`; 3. write the result: `this.lastOrderId = id; this.items = []; this.status = 'placed'`; 4. on failure, record it: `this.status = 'failed'; this.error = message`. The action returns a **promise**. Whatever the function returns becomes the resolved value, so `placeOrder` can return the new order id to the component that needs to navigate to a confirmation page. ## Errors and partial writes - A thrown error or a rejected promise **propagates to the caller**. If no one catches it, it becomes an unhandled rejection. - Pinia does **not** roll back state when an action fails. `status` stays `'submitting'` unless the action's own `catch` resets it. - Two common designs: the action catches, stores `error`, and resolves (the component just reads `order.error`); or the action rethrows and the component shows the failure. Pick one per store and be consistent. ## Calling actions from a component - `order.addItem(item)`: a plain call, synchronous. - `await order.placeOrder()` inside an `async` handler, wrapped in `try`/`catch` when the action rethrows. - In a template: `@click="order.addItem(item)"`. - Disable the submit button while `order.status === 'submitting'`, so a double click does not place two orders. There is no `order.dispatch('placeOrder')` or `commit`: those belong to Vuex, which Pinia replaced. ## Setup-store actions In a setup store the same actions are plain functions: ```ts function addItem(item: CartItem) { items.value.push(item) } async function placeOrder() { status.value = 'submitting' const { id } = await api.placeOrder(items.value) status.value = 'placed' return id } return { items, status, addItem, placeOrder } ``` There is no `this`; the functions close over the refs. Pinia wraps each returned function as an action, so it behaves the same for callers and for action hooks. ## Slips interviewers listen for - Writing option-store actions as arrow functions. - Reaching for `dispatch` or `commit` out of Vuex habit. - Calling an async action without awaiting or catching it: a rejection then surfaces as an unhandled promise rejection. - Assuming a failed action restores the state it changed. ## Arguments, return values and typing Actions take any arguments and return anything, and Pinia infers both for callers: `order.addItem` is typed from its parameter, and `await order.placeOrder()` is typed as whatever the action returns, here the order id. In an option store, `this` inside an action is typed as the whole store, including state, getters and the other actions, so annotations are rarely needed; unlike `this`-based getters, actions normally get their return types inferred. Actions can also call each other: `this.addItem(item)` in an option store, or a plain call in a setup store. An async action can `await` another action as easily as an API call, which is how larger flows such as validate-then-submit are composed out of small actions. ## When logic belongs in an action 1. It changes the store's state, possibly after asynchronous work. 2. More than one component needs it, such as the cart page and the mini-cart both adding items. 3. It needs to be observable or testable in isolation from the UI. Logic that only formats data for one component stays in that component; logic that only derives values from state belongs in a getter.