redux-saga

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)	No	Query store state
actionChannel(pattern)	No	Buffer actions
flush(channel)	No	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])	If any child blocks	Parallel, wait all
setContext(props) / getContext(prop)	No / Yes	Saga context

Pattern Matching

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

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

Only take/takeMaybe may omit the argument entirely — take() matches all actions. For takeEvery, takeLatest, takeLeading, throttle, and debounce the pattern is a required parameter; use '*' for a catch-all watcher.

Taking from a multicastChannel also requires a pattern: take(chan, '*'), not take(chan).

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