UNPKG

@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.

158 lines (120 loc) • 6.14 kB
--- name: core/actions description: >- createAction<[Params]>(type) produces action creators with positional-tuple payloads; an optional payloadModifier transforms args into any payload shape. createAsyncAction<[Args], SuccessPayload>(asyncType, stagesType) produces a request/success/failure triplet plus a promise on each request. Always namespace action types as "sliceName/actionName". Action creators expose .type and .toString, so they are passed directly to takeEvery/takeLatest — never .type. Async creators expose static .success/.failure creators on the creator itself, and per-instance success/failure/promise on each dispatched action. Each action type has one canonical owner; search for existing action creators before adding another. type: sub-skill requires: - core - core/state-integrity triggers: - create action - tuple payload - async action - action creator --- # Actions — `createAction` / `createAsyncAction` > Operational guidance for action creator work. API details and longer examples live in `docs/REDUCERS.md` → Actions and Async Actions. Public API: `@augmentcode/ag-redux-toolkit/utils/store/create-action`; related family guidance: `../SKILL.md` §3. ## Use when - Adding or reusing slice action creators. - Wiring async request/success/failure flows to reducers or sagas. - Checking action type ownership during state-integrity work. ## Do - Search first for the intended action type, creator names, and operation terms; one action type string has one canonical owner. - Namespace action types as `sliceName/actionName`. - Use tuple payload typing for positional args, e.g. `createAction<[id: string]>(...)`. - Use a payload modifier only when callers should pass positional args but reducers/sagas need a shaped payload. - Pass action creators directly to `takeEvery`/`takeLatest`; their `toString()` exposes the action type. ## Async action cues - `createAsyncAction<[Args], Success>(asyncType, stagesType)` creates the request creator plus static `.success` and `.failure` creators. - A dispatched request action carries `payload`, `promise`, and per-instance `success`/`failure` creators. - Reducers normally handle the request creator, `.success`, and `.failure` to update loading/data/error fields. - Sagas watch the request creator unless they are intentionally reacting to success/failure events. ## Examples ### No-payload action for explicit events ```ts import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; export const resetTodos = createAction("todos/reset"); const resetAction = resetTodos(); resetAction.payload satisfies undefined; ``` ### Tuple payload action consumed by reducers ```ts import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer"; const renameTodo = createAction<[id: string, title: string]>("todos/rename"); const reducer = createReducer({ titles: {} as Record<string, string> }).with( renameTodo, (state, { payload: [id, title] }) => ({ ...state, titles: { ...state.titles, [id]: title } }) ); ``` ### Payload modifier when reducers need a named object ```ts import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; export const renameTodo = createAction( "todos/rename", (id: string, title: string, requestedAtMs: number) => ({ id, title, requestedAtMs }) ); const action = renameTodo("todo-1", "Ship docs", Date.now()); action.payload.id satisfies string; ``` ### Async request/success/failure triplet ```ts import { createAsyncAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; type Todo = { id: string; title: string }; export const loadTodo = createAsyncAction<[id: string], { id: string }, Todo>( "todos/loadAsync", "todos/load", (id) => ({ id }) ); const request = loadTodo("todo-1"); const success = request.success({ id: "todo-1", title: "Ship docs" }); success.payload.request.id satisfies string; ``` ### Watch request creators directly in sagas ```ts import { takeLatest } from "typed-redux-saga"; import { createAsyncAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; const loadTodo = createAsyncAction<[id: string], { id: string }>( "todos/loadAsync", "todos/load", (id) => ({ id }) ); function* watchTodos() { yield* takeLatest(loadTodo, function* loadTodoWorker(action) { action.payload.id satisfies string; }); } ``` ### ❌ Bad: duplicate owner plus tuple/object payload drift ```ts import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; type RenameTodoPayload = { id: string; title: string }; // BAD: two modules now claim the same action type, and callers get a tuple-wrapped object. export const renameTodoFromList = createAction<[payload: RenameTodoPayload]>("todos/rename"); export const renameTodoFromDetail = createAction<[payload: RenameTodoPayload]>("todos/rename"); const [{ id, title }] = renameTodoFromList({ id: "todo-1", title: "Ship docs" }).payload; ``` ## Don't - Do not create aliases with the same type string in another module. - Do not pass `.type` to saga watchers; pass the creator. - Do not use object payload types for one-argument actions unless an existing public contract already requires that shape. - Do not place generated timestamps or IDs in reducers; generate them before dispatch. ## Verification cues - Reducer tests cover each action handler and no-op reference equality. - Saga tests prove request watchers receive the request creator, not an accidental success/failure creator. - State-integrity handoff names the canonical owner or states that no new action owner was added. ## See also - `docs/REDUCERS.md` — human reference for action and async-action examples. - `core/reducers/SKILL.md` — consuming actions in `.with()` handlers. - `core/sagas/SKILL.md` — watcher patterns and typed-redux-saga usage. - `core/state-integrity/SKILL.md` — duplicate-owner search protocol. - `core/file-structure/SKILL.md` — where action creators belong.