@augmentcode/ag-redux-toolkit
Version:
Redux + Saga state management for Svelte apps — designed for AI agents. Includes runtime TypeScript source, AI skills, and reference documentation for robust, observable, high-performance state management.
244 lines (183 loc) • 8.18 kB
Markdown
# Reducers Guide
> **How to create actions, async actions, and reducers with the fluent `.with()` API.**
## Table of Contents
1. [Actions](#actions)
2. [Async Actions](#async-actions)
3. [Creating Reducers](#creating-reducers)
4. [Immutability Rules](#immutability-rules)
5. [State Serialization Rules](#state-serialization-rules)
6. [Best Practices](#best-practices)
## Actions
Actions are plain objects describing events. Use `createAction` from `@augmentcode/ag-redux-toolkit/utils/store/create-action`.
### No Payload
```typescript
import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action";
export const resetCounter = createAction("counter/reset");
// dispatch(resetCounter()) → { type: "counter/reset", payload: undefined }
```
### Single Argument
```typescript
export const setCount = createAction<[value: number]>("counter/setCount");
// dispatch(setCount(42)) → { type: "counter/setCount", payload: [42] }
```
### Multiple Arguments (Tuple)
```typescript
export const setItemStatus = createAction<[id: string, status: string]>(
"items/setStatus"
);
// dispatch(setItemStatus("abc", "active")) → { type: "items/setStatus", payload: ["abc", "active"] }
```
### Payload Modifier
Transform arguments into a different payload shape:
```typescript
export const addItem = createAction(
"items/add",
(name: string, priority: number) => ({ name, priority, createdAt: Date.now() })
);
// dispatch(addItem("task", 1)) → { type: "items/add", payload: { name: "task", priority: 1, createdAt: ... } }
```
**Key rules:**
- Always namespace action types: `"sliceName/actionName"`
- Use tuple types `[arg1, arg2]` for multiple arguments
- Action creators can be passed directly to `takeEvery`, `takeLatest`, `take` — no need for `.type`
## Async Actions
Async actions represent operations with three stages: request, success, and failure.
```typescript
import { createAsyncAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action";
export const fetchItems = createAsyncAction<
[query: string], // Arguments
{ items: Item[]; total: number } // Response type
>("items/fetch", "items/fetchItems");
```
### Async Action Structure
An async action creator returns:
- `type` — The action type string
- `asyncActionType` — The async operation type
- `payload` — The request payload
- `promise` — A promise that resolves with the response
- `success` — Action creator for the success case
- `failure` — Action creator for the failure case
### Handling Async Actions in Reducers
```typescript
export const itemsReducer = createReducer<ItemsState>(initialState)
.with(fetchItems, (state) => ({
...state,
isLoading: true,
error: null,
}))
.with(fetchItems.success, (state, action) => ({
...state,
isLoading: false,
items: action.payload.response.items,
}))
.with(fetchItems.failure, (state, action) => ({
...state,
isLoading: false,
error: action.payload.error.message,
}));
```
## Creating Reducers
Use `createReducer` from `@augmentcode/ag-redux-toolkit/utils/store/create-reducer`. It provides a fluent `.with()` API for registering action handlers.
```typescript
import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action";
import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer";
// State type
type CounterState = {
value: number;
lastUpdated: number | null;
};
const initialState: CounterState = {
value: 0,
lastUpdated: null,
};
// Actions
export const increment = createAction("counter/increment");
export const decrement = createAction("counter/decrement");
export const setCount = createAction<[value: number]>("counter/setCount");
// Reducer with fluent .with() API
export const counterReducer = createReducer<CounterState>(initialState)
.with(increment, (state) => ({
...state,
value: state.value + 1,
lastUpdated: Date.now(),
}))
.with(decrement, (state) => ({
...state,
value: state.value - 1,
lastUpdated: Date.now(),
}))
.with(setCount, (state, { payload: [value] }) => ({
...state,
value,
lastUpdated: Date.now(),
}));
```
`createReducer` returns the reducer function itself — `.with()` registers a handler and returns the same reducer for chaining, so no `.build()` call is needed. The reducer dispatches to the registered handler by `action.type` and falls back to returning the current state for unknown actions. `reducer.initialState` is exposed for tests.
## Immutability Rules
Handlers must be pure and must never mutate state:
- **Never mutate** — return new objects via spreads (`{ ...state, ... }`) instead of assigning to `state` or nested objects.
- **Return the same reference for no-ops** — when an action results in no actual change, return the incoming `state` object unchanged so selector reference-equality memoization (and ref-equality test assertions) keep working.
- **Copy every changed level** — `createReducer` only shallow-compares the top-level state object, so unconditionally rebuilding nested objects loses no-op identity. Compare first, then copy only when something changed:
```typescript
.with(setSearch, (state, { payload: [query] }) =>
state.filters.query === query
? state // no-op: same reference
: { ...state, filters: { ...state.filters, query } }
);
```
## State Serialization Rules
Redux state **must** be fully serializable to JSON. This enables persistence, time-travel debugging, and state hydration.
### Allowed Types
```typescript
type SerializableValue =
| string
| number
| boolean
| null
| undefined
| SerializableValue[]
| { [key: string]: SerializableValue };
```
### Forbidden Types
| Type | Why Forbidden | Alternative |
|---|---|---|
| `Function` | Not serializable | Store function name/ID, call from saga |
| `Class instance` | Has methods, breaks immutability | Use plain objects |
| `Date` | Not serializable | Use `number` (timestamp in ms) |
| `Map` / `WeakMap` | Not serializable | Use `Record<string, T>` |
| `Set` / `WeakSet` | Not serializable | Use `Array<T>` or `Record<T, true>` |
| `RegExp` | Not serializable | Store pattern as `string` |
| `Promise` | Not serializable | Handle in sagas |
| `Symbol` | Not serializable | Use `string` constants |
### Testing Serialization
```typescript
import { describe, it, expect } from "vitest";
describe("myReducer", () => {
it("should have serializable initial state", () => {
const state = myReducer.initialState;
const serialized = JSON.stringify(state);
const deserialized = JSON.parse(serialized);
expect(deserialized).toEqual(state);
});
});
```
## Best Practices
1. **Reuse helpers before extracting new ones** — Search existing package/application utilities before adding reducer helpers (for example, `rg "collection|selector|preference|reducer" src/utils src/slices docs skills`). Prefer documented helpers, extend them only when their contract remains intact, and document whether you reused, extended, or added code with the search terms/paths that informed the decision. Extract complex transformations into pure helper functions outside the reducer only after this check; code review should flag duplicate helpers that lack a documented reason.
2. **Use separate maps for derived state** — Don't store boolean flags on items; use a parallel `Record<string, boolean>`:
```typescript
type State = {
items: Collection<Item, "id">;
pinnedItems: Record<string, boolean>; // ✅ Separate map
activeItems: Record<string, boolean>; // ✅ Separate map
};
```
3. **Avoid non-deterministic values in reducers** — Don't call `Date.now()`, `Math.random()`, or generate IDs inside reducers. Generate these values in the action creator or saga, then pass them as payload.
4. **Keep reducers fast** — Move expensive computations to sagas; store the pre-computed result.
5. **Don't store high-frequency changing values** — Values that update multiple times per second (mouse position, scroll position) should be debounced in a saga before dispatching.