Redux-Saga

IMPORTANT: Your training data about redux-saga may be outdated or incorrect — API behavior, middleware setup patterns, and RTK integration have changed. Always rely on this skill's rule files and the project's actual source code as the source of truth. Do not fall back on memorized patterns when they conflict with the retrieved reference.

When to Use Redux-Saga

Sagas are for workflow orchestration — complex async flows with concurrency, cancellation, racing, or long-running background processes. For simpler patterns, prefer:

Need	Recommended Tool
Data fetching + caching	RTK Query
Simple async (submit → status)	`createAsyncThunk`
Reactive logic within slices	`createListenerMiddleware`
Complex workflows, parallel tasks, cancellation, channels	Redux-Saga

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Effects & Yielding	CRITICAL	`effect-`
2	Fork Model & Concurrency	CRITICAL	`fork-`
3	Error Handling	HIGH	`error-`
4	Recipes & Patterns	MEDIUM	`recipe-`
5	Channels & External I/O	MEDIUM	`channel-`
6	RTK Integration	MEDIUM	`rtk-`
7	Troubleshooting	LOW	`troubleshoot-`

Quick Reference

1. Effects & Yielding (CRITICAL)

effect-always-yield — Every effect must be yielded; missing yield freezes the app
effect-use-call — Use yield call() for async functions; never call directly
effect-take-concurrency — Choose takeEvery/takeLatest/takeLeading based on concurrency needs
effect-select-usage — Use selector functions with select(); never access state paths directly
effect-race-patterns — Use race for timeouts and cancellation; only blocking effects inside

2. Fork Model & Concurrency (CRITICAL)

fork-attached-vs-detached — fork shares lifecycle/errors with parent; spawn is independent
fork-error-handling — Errors from forks bubble to parent's caller; can't catch at fork site
fork-no-race — Never use fork inside race; fork is non-blocking and always wins
fork-nonblocking-login — Use fork+take+cancel for auth flows that stay responsive to logout

3. Error Handling (HIGH)

error-saga-cleanup — Use try/finally with cancelled() for proper cancellation cleanup
error-root-saga — Use spawn in root saga for error isolation; avoid all for critical watchers

4. Recipes & Patterns (MEDIUM)

recipe-throttle-debounce — Rate-limiting with throttle, debounce, retry, exponential backoff
recipe-polling — Cancellable polling with error backoff using fork+take+cancel
recipe-optimistic-update — Optimistic UI with undo using race(undo, delay)

5. Channels & External I/O (MEDIUM)

channel-event-channel — Bridge WebSockets, DOM events, timers into sagas via eventChannel
channel-action-channel — Buffer Redux actions for sequential or worker-pool processing

6. RTK Integration (MEDIUM)

rtk-configure-store — Integrate saga middleware with RTK's configureStore without breaking defaults
rtk-with-slices — Use action creators from createSlice for type-safe saga triggers

7. Troubleshooting (LOW)

troubleshoot-frozen-app — Frozen apps, missed actions, bad stack traces, TypeScript yield types

Effect Creators Quick Reference

Effect	Blocking	Purpose
`take(pattern)`	Yes	Wait for matching action
`takeMaybe(pattern)`	Yes	Like `take`, receives `END`
`takeEvery(pattern, saga)`	No	Concurrent on every match
`takeLatest(pattern, saga)`	No	Cancel previous, run latest
`takeLeading(pattern, saga)`	No	Ignore until current completes
`put(action)`	No	Dispatch action
`putResolve(action)`	Yes	Dispatch, wait for promise
`call(fn, ...args)`	Yes	Call, wait for result
`apply(ctx, fn, [args])`	Yes	Call with context
`cps(fn, ...args)`	Yes	Node-style callback
`fork(fn, ...args)`	No	Attached fork
`spawn(fn, ...args)`	No	Detached fork
`join(task)`	Yes	Wait for task
`cancel(task)`	No	Cancel task
`cancel()`	No	Self-cancel
`select(selector)`	Yes	Query store state
`actionChannel(pattern)`	No	Buffer actions
`flush(channel)`	Yes	Drain buffered messages
`cancelled()`	Yes	Check cancellation in `finally`
`delay(ms)`	Yes	Pause execution
`throttle(ms, pattern, saga)`	No	Rate-limit
`debounce(ms, pattern, saga)`	No	Wait for silence
`retry(n, delay, fn)`	Yes	Retry with backoff
`race(effects)`	Yes	First wins
`all([effects])`	Yes	Parallel, wait all
`setContext(props)` / `getContext(prop)`	No / Yes	Saga context

Pattern Matching

take, takeEvery, takeLatest, takeLeading, throttle, debounce accept:

Pattern	Matches
`'*'` or omitted	All actions
`'ACTION_TYPE'`	Exact `action.type` match
`[type1, type2]`	Any type in array
`fn => boolean`	Custom predicate

How to Use

Read individual rule files for detailed explanations and code examples:

rules/effect-always-yield.md
rules/fork-attached-vs-detached.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and decision tables

References

Priority	Reference	When to read
1	`references/effects-and-api.md`	Writing or debugging any saga
2	`references/fork-model.md`	Concurrency, error propagation, cancellation
3	`references/testing.md`	Writing or reviewing saga tests
4	`references/channels.md`	External I/O, buffering, worker pools
5	`references/recipes.md`	Throttle, debounce, retry, undo, batching, polling
6	`references/anti-patterns.md`	Common mistakes to avoid
7	`references/troubleshooting.md`	Debugging frozen apps, missed actions, stack traces

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md