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.

315 lines (235 loc) • 15.6 kB
--- name: core/redux-saga description: >- Generic redux-saga API reference for agents. Covers createSagaMiddleware, middleware.run, runSaga, Effect creators, effect combinators, watcher helpers, channel support, buffers, Task/Channel/Buffer/SagaMonitor interfaces, cancellation, context, blocking vs non-blocking semantics, and testing helpers. type: core sources: - https://redux-saga.js.org/docs/api triggers: - redux-saga - redux saga API - createSagaMiddleware - saga effects - saga channels - runSaga - saga cancellation - saga testing --- # redux-saga — API reference skill > Source: official redux-saga API Reference, https://redux-saga.js.org/docs/api, retrieved 2026-05-15. Use this skill for generic redux-saga API behavior. When editing this repository's`ag-redux-toolkit` code, also follow the package-specific core saga skills in sibling `../*` skill folders, especially the `typed-redux-saga` `yield*`conventions and canonical watcher ownership rules. ## Agent Preflight Compliance Contract Before editing code or docs that use this skill: - **MUST** identify whether the target code uses plain `redux-saga` or this repo's`typed-redux-saga` conventions; adapt examples accordingly. - **MUST** cite this skill and any package-specific saga skill used in the handoff. - **MUST** verify watcher ownership before adding `takeEvery`, `takeLatest`,`takeLeading`, `throttle`, or `debounce` for an existing trigger. - **SHOULD** prefer native redux-saga channel-aware effects before adding wrapperutilities. - **MUST NOT** introduce detached `spawn` in this repository; use attached `fork` so parent failure/cancellation also reaches children. - **MUST** implement repository debounce with `takeLatest` or `takeLeading` plus `delay`, not action-wrapper debounce utilities. - **NEVER** introduce runtime source, dependency, or artifact routing changes whenonly API guidance is requested. ## Setup — middleware and root saga startup `createSagaMiddleware(options)` creates Redux middleware. Supported options includeinitial `context`, `sagaMonitor`, `onError`, `effectMiddlewares`, and a custom`channel` used by `take` and `put` effects. In ag-redux-toolkit app setup, the concrete Store owns saga middleware creation. Use this low-level API reference to understand redux-saga behavior, but configure Store-owned monitoring by passing `{ sagaMonitor: true }` in the third `Store`/`ReactStore`/`StreamingStore` constructor options argument instead of replacing the middleware. Omitted or `false` saga monitoring remains disabled. ```typescript import { applyMiddleware, createStore } from "redux"; import createSagaMiddleware from "redux-saga"; import { all, call } from "redux-saga/effects"; function reducer(state = { ready: false }, action: { type: string }) { return action.type === "READY" ? { ready: true } : state; } function* rootSaga() { yield all([call(backgroundSync)]); } const sagaMiddleware = createSagaMiddleware({ onError(error, { sagaStack }) { console.error("uncaught saga error", error, sagaStack); }, }); const store = createStore(reducer, applyMiddleware(sagaMiddleware)); const task = sagaMiddleware.run(rootSaga); function* backgroundSync() { yield call(Promise.resolve, undefined); } void task.toPromise(); ``` `middleware.run(saga, ...args)` must be called after the saga middleware is mountedon the store. It returns a `Task` descriptor and drives yielded plain Effectobjects until the generator returns, throws, or is cancelled. ## Core patterns ### 1. Waiting and watcher helpers Use `take(pattern)` for one action, `takeMaybe(pattern)` when the saga must receivethe `END` sentinel instead of auto-terminating, and watcher helpers for commonloops. Patterns can be `"*"`, strings, arrays, predicates, or action creators whose`toString()` returns an action type. ```typescript import { call, fork, put, take, takeEvery, takeLatest, takeLeading } from "redux-saga/effects"; function* loadUser(action: { type: string; userId: string }) { const user: User = yield call(api.loadUser, action.userId); yield put({ type: "USER_LOADED", user }); } export function* usersSaga() { yield takeEvery("USER_REQUESTED", loadUser); // concurrent workers yield takeLatest("SEARCH_CHANGED", runSearch); // cancel stale worker yield takeLeading("SUBMIT_ORDER", submitOrder); // ignore while running const action: { type: string } = yield take(["LOGOUT", "SESSION_EXPIRED"]); yield fork(cleanupSession, action); } ``` `takeEvery`, `takeLatest`, `takeLeading`, `throttle`, and `debounce` also accept a`Channel` in place of a pattern. This is native redux-saga behavior; do not createwrapper utilities unless they add cleanup, typing, or domain value beyond the API. ### 2. Blocking and non-blocking effects `call`, `apply`, and `cps` are blocking; `fork` and `spawn` start work without blocking the parent. `fork` is attached to the parent: parent completion waits for children, child errors bubble upward, and cancellation propagates downward. `spawn` is detached and does not share parent completion, error, or cancellation flow. In this repository, agents must use attached `fork`, not detached `spawn`, so child tasks remain cancellable and failures remain visible to the parent lifecycle. ```typescript import { call, cancel, cancelled, fork, join } from "redux-saga/effects"; function* worker() { try { yield call(api.sync); } finally { if (yield cancelled()) yield call(api.abortSync); } } function* supervisor() { const attachedTask: Task = yield fork(worker); const metricsTask: Task = yield fork(backgroundMetrics); yield cancel(metricsTask); // non-blocking cancellation request yield join(attachedTask); // blocking wait for attachedTask outcome } ``` Use `cancel(task)`, `cancel([...tasks])`, or `cancel()` for self-cancellation.Cancellation calls the generator's `return()`, jumps to `finally`, and cancels thecurrently blocked effect plus attached child tasks. ### 3. Store I/O, state reads, context, and timing Use `put(action)` for scheduled dispatch, `putResolve(action)` when dispatch returnsa Promise and the saga must wait, `put(channel, message)` for channel output, and`select(selector, ...args)` for state reads. `setContext(props)` merges saga context;`getContext(prop)` reads one context value. `delay(ms, value)` blocks for time. ```typescript import { call, delay, getContext, put, putResolve, retry, select, setContext } from "redux-saga/effects"; function* saveProfile(action: { type: string; id: string }) { const token: string = yield select((state: RootState) => state.session.token); yield setContext({ requestId: action.id }); const requestId: string = yield getContext("requestId"); const profile: Profile = yield retry(3, 1_000, api.loadProfile, token, requestId); yield put({ type: "PROFILE_LOADED", profile }); yield delay(250); yield putResolve({ type: "PROFILE_PERSISTED" }); } ``` `retry(maxTries, delayMs, fn, ...args)` is a blocking helper built from `call` and`delay`: it retries failures until success or attempts are exhausted, then rethrowsthe last error. ### 4. Channels, buffers, and cleanup Use `actionChannel(pattern, buffer?)` to queue matching store actions while a workeris blocked. Use `channel(buffer?)` for task-to-task messages and `eventChannel` tobridge external event sources; the `subscribe` function must return an unsubscribefunction. Close channels in `finally`, and use `flush(channel)` to recover bufferedmessages during cleanup. ```typescript import { buffers, channel, eventChannel, END } from "redux-saga"; import { actionChannel, call, flush, put, take } from "redux-saga/effects"; function socketChannel(socket: WebSocket) { return eventChannel<string>((emit) => { socket.onmessage = (event) => emit(String(event.data)); socket.onerror = () => emit(END); return () => socket.close(); }, buffers.sliding(10)); } function* serializeRequests() { const requests: Channel<RequestAction> = yield actionChannel("REQUEST", buffers.expanding(10)); try { while (true) { const action: RequestAction = yield take(requests); yield call(api.sendRequest, action.payload); } } finally { const leftovers: RequestAction[] = yield flush(requests); yield put({ type: "REQUESTS_FLUSHED", leftovers }); } } const mailbox = channel<string>(buffers.fixed(5)); ``` Buffer choices: `buffers.none()`, `fixed(limit)`, `expanding(initialSize)`,`dropping(limit)`, and `sliding(limit)`. The default `channel()` buffer queues upto 10 messages FIFO. ### 5. Concurrency combinators and helpers Use `race` when the first completion wins; losing effects are automaticallycancelled. Use `all` to run effects in parallel and wait for all successes, or throwwhen any effect rejects. ```typescript import { all, call, delay, put, race, take, takeLatest, takeLeading, throttle } from "redux-saga/effects"; function* fetchWithTimeout() { const { response, timeout } = yield race({ response: call(api.fetchReport), timeout: delay(5_000), }); if (timeout) yield put({ type: "REPORT_TIMEOUT" }); else yield put({ type: "REPORT_READY", response }); } function* refreshResultsAfterSettled(action: { type: string; query: string }) { yield delay(300); yield call(refreshResults, action.query); } function* refreshOncePerWindow(action: { type: string; id: string }) { try { yield call(refreshPanel, action.id); } finally { yield delay(300); } } function* rootSaga() { yield all([call(fetchWithTimeout), call(watchUpload)]); yield throttle(1_000, "TYPEAHEAD_CHANGED", fetchSuggestions); yield takeLatest("FILTER_CHANGED", refreshResultsAfterSettled); yield takeLeading("REFRESH_CLICKED", refreshOncePerWindow); yield take("SHUTDOWN"); } ``` `throttle(ms, patternOrChannel, saga, ...args)` uses a sliding buffer of one recentmessage while suppressing new starts during the window. Upstream redux-saga also exposes a native `debounce(ms, patternOrChannel, saga, ...args)` helper that waits until messages settle before forking the worker, but agents must not use it for `ag-redux-toolkit` implementation examples. Repository debounce must be written explicitly with `takeLatest` or `takeLeading` plus `delay` so cancellation semantics are visible in the worker. ## Interface quick reference | Interface | What agents need to know | | --- | --- | | Task | Returned by fork, spawn, middleware.run, and runSaga; supports isRunning(), isCancelled(), result(), error(), toPromise(), and cancel(). | | Channel | Message queue with take(callback), put(message), flush(callback), and close(); closed empty channels deliver END. | | Buffer | Strategy behind a channel; implements isEmpty(), put(message), and take(). | | SagaMonitor | Receives rootSagaStarted, effectTriggered, effectResolved, effectRejected, effectCancelled, and actionDispatched events for instrumentation. | ## Blocking / non-blocking cheat sheet | Effect | Blocking? | Notes | | --- | --- | --- | | take, takeMaybe, call, apply, cps, join, putResolve, cancelled, delay, retry, race | Yes | race blocks until one branch wins, then cancels losers. | | put, fork, spawn, cancel, actionChannel, flush, select, setContext, getContext | No | select resolves immediately against current state. | | put(channel, message) | Depends | It can block when an unbuffered put is consumed immediately by a taker. | | all([...]) / all({ ... }) | Mixed | Blocks until all child effects complete; child effect types determine actual waits. | | takeEvery, takeLatest, takeLeading, throttle, debounce | No | Helpers fork watcher tasks; their internals may use blocking effects. | ## External execution with `runSaga` `runSaga(options, saga, ...args)` starts a saga without Redux middleware. Provide a`channel` for `take`, a `dispatch(output)` function for `put`, and `getState()` for`select`. It returns the same `Task` interface as `middleware.run`. ```typescript import { runSaga, stdChannel } from "redux-saga"; import { put, take } from "redux-saga/effects"; function* auditSaga() { const action: { type: string } = yield take("AUDIT"); yield put({ type: "AUDITED", action }); } const dispatched: Array<{ type: string; action?: { type: string } }> = []; const input = stdChannel(); const task = runSaga( { channel: input, dispatch: (output) => dispatched.push(output), getState: () => ({}) }, auditSaga, ); input.put({ type: "AUDIT" }); await task.toPromise(); ``` ## Testing helpers - `cloneableGenerator(generatorFunc)` from `@redux-saga/testing-utils` createscloneable generator instances for branch testing without replaying setup yields. - `createMockTask()` from `@redux-saga/testing-utils` returns a mock `Task` fortesting `fork`, `join`, and `cancel` flows. - Prefer effect-level assertions for small generators and integration-style sagatests for cancellation, channel cleanup, and watcher concurrency. ```typescript import { cloneableGenerator, createMockTask } from "@redux-saga/testing-utils"; import { cancel, fork } from "redux-saga/effects"; function* worker() {} function* parent() { const task: Task = yield fork(worker); yield cancel(task); } const generator = cloneableGenerator(parent)(); expect(generator.next().value).toEqual(fork(worker)); const mockTask = createMockTask(); expect(generator.next(mockTask).value).toEqual(cancel(mockTask)); ``` ## Common mistakes ### ❌ Calling `middleware.run` before mounting middleware `middleware.run` is only valid after the saga middleware is connected to the Reduxstore. Mount middleware first, then run the root saga. Source: redux-saga APIReference → `middleware.run(saga, ...args)`. Priority: **HIGH**. ### ❌ Assuming `take` and `takeMaybe` handle `END` the same way `take(pattern)` and `take(channel)` auto-terminate when they receive `END` from thestdChannel or a closed channel. `takeMaybe` returns the `END` object so the saga canhandle the closed-input case itself. Source: redux-saga API Reference → `take` /`takeMaybe`. Priority: **MEDIUM**. ### ❌ Using `spawn` when parent failure/cancellation must affect the child `fork` creates an attached task; errors bubble to the parent and cancellation propagates through attached children. In this repository, do not introduce `spawn`; use `fork` so saga-manager and parent lifecycles can observe failures and cancel children. Source: redux-saga API Reference → `fork` / `spawn`. Priority: **HIGH**. ### ❌ Forgetting channel unsubscribe / close cleanup `eventChannel` subscribe functions must return an unsubscribe callback, and sagaconsumers should close channels in `finally` when they own the channel lifecycle.Source: redux-saga API Reference → `eventChannel` / `Channel`. Priority: **HIGH**. ### ❌ Recreating native channel helpers as wrappers without added value `takeEvery`, `takeLatest`, `takeLeading`, `throttle`, and `debounce` already acceptchannels. Add wrappers only for documented cleanup, typing, or domain-specificbehavior. Source: redux-saga API Reference → channel overloads for watcher helpers.Priority: **MEDIUM**. For this repository's action debouncing, do not add wrapper-action debounce utilities; watch the real action with `takeLatest` or `takeLeading` and use `delay` inside the worker. ## See also - `../sagas/SKILL.md` — repository-specific typed-redux-saga conventions. - `../channel-effects/SKILL.md` — package-provided channel consumer wrappers and when they add cleanup value. - `../testing/SKILL.md` — repository-specific saga test patterns and mocks.