redux-saga

Redux-Saga

重要： redux-saga に関する学習データは、古くなっているか、誤っている可能性があります。API の動作、ミドルウェアの設定パターン、RTK との統合方法は変更されています。常に、このスキルのルールファイルとプロジェクトの実際のソースコードを信頼できる情報源として参照してください。取得したリファレンスと矛盾する場合、記憶したパターンに頼らないでください。

Redux-Saga を使用する場面

Saga は、ワークフローのオーケストレーション、つまり並行処理、キャンセル、競合、または長時間実行されるバックグラウンドプロセスを伴う複雑な非同期フローに適しています。より単純なパターンには、次を使用してください。

必要なこと	推奨ツール
データ取得とキャッシュ	RTK Query
単純な非同期処理（送信 → 状態）	createAsyncThunk
スライス内のリアクティブなロジック	createListenerMiddleware
複雑なワークフロー、並列タスク、キャンセル、チャネル	Redux-Saga

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	エフェクトと Yield	CRITICAL	effect-
2	Fork モデルと並行処理	CRITICAL	fork-
3	エラー処理	HIGH	error-
4	レシピとパターン	MEDIUM	recipe-
5	チャネルと外部 I/O	MEDIUM	channel-
6	RTK との統合	MEDIUM	rtk-
7	トラブルシューティング	LOW	troubleshoot-

クイックリファレンス

1. エフェクトと Yield（CRITICAL）

• effect-always-yield — すべてのエフェクトで yield が必要です。yield がないとアプリがフリーズします
• effect-use-call — 非同期関数には yield call() を使用し、直接呼び出さないでください
• effect-take-concurrency — 並行処理の要件に応じて takeEvery／takeLatest／takeLeading を選択してください
• effect-select-usage — select() ではセレクター関数を使用し、状態のパスに直接アクセスしないでください
• effect-race-patterns — タイムアウトとキャンセルには race を使用し、その内部にはブロッキングエフェクトのみを指定してください

2. Fork モデルと並行処理（CRITICAL）

• fork-attached-vs-detached — fork は親とライフサイクルおよびエラーを共有します。spawn は独立しています
• fork-error-handling — fork で発生したエラーは親の呼び出し元に伝播するため、fork の箇所では捕捉できません
• fork-no-race — race 内で fork を使用しないでください。fork はノンブロッキングで、必ず勝ちます
• fork-nonblocking-login — ログアウト時も応答性を保つ認証フローには、fork＋take＋cancel を使用してください

3. エラー処理（HIGH）

• error-saga-cleanup — 適切なキャンセル時のクリーンアップには、cancelled() と try/finally を使用してください
• error-root-saga — エラーを分離するにはルート Saga で spawn を使用し、重要なウォッチャーには all を避けてください

4. レシピとパターン（MEDIUM）

• recipe-throttle-debounce — throttle、debounce、retry、指数バックオフによるレート制限
• recipe-polling — fork＋take＋cancel とエラー時のバックオフによる、キャンセル可能なポーリング
• recipe-optimistic-update — race(undo, delay) を使った、取り消し可能な楽観的 UI 更新

5. チャネルと外部 I/O（MEDIUM）

• channel-event-channel — eventChannel を介して WebSocket、DOM イベント、タイマーを Saga に接続します
• channel-action-channel — Redux アクションをバッファリングし、順次処理またはワーカープールで処理します

6. RTK との統合（MEDIUM）

• rtk-configure-store — デフォルト設定を壊さずに、Saga ミドルウェアを RTK の configureStore と統合します
• rtk-with-slices — 型安全な Saga のトリガーには、createSlice のアクションクリエーターを使用します

7. トラブルシューティング（LOW）

• troubleshoot-frozen-app — アプリのフリーズ、アクションの取りこぼし、不適切なスタックトレース、TypeScript の yield 型

Effect Creator クイックリファレンス

Effect	ブロッキング	目的
take(pattern)	はい	一致するアクションを待機します
takeMaybe(pattern)	はい	take と同様ですが、END を受け取ります
takeEvery(pattern, saga)	いいえ	一致するたびに並行実行します
takeLatest(pattern, saga)	いいえ	前の処理をキャンセルし、最新の処理を実行します
takeLeading(pattern, saga)	いいえ	現在の処理が完了するまで無視します
put(action)	いいえ	アクションをディスパッチします
putResolve(action)	はい	アクションをディスパッチし、Promise を待機します
call(fn, ...args)	はい	関数を呼び出し、結果を待機します
apply(ctx, fn, [args])	はい	コンテキストを指定して呼び出します
cps(fn, ...args)	はい	Node スタイルのコールバック
fork(fn, ...args)	いいえ	親にアタッチされた fork
spawn(fn, ...args)	いいえ	切り離された fork
join(task)	はい	タスクを待機します
cancel(task)	いいえ	タスクをキャンセルします
cancel()	いいえ	自身をキャンセルします
select(selector)	いいえ	ストアの状態を照会します
actionChannel(pattern)	いいえ	アクションをバッファリングします
flush(channel)	いいえ	バッファリングされたメッセージを取り出します
cancelled()	はい	finally 内でキャンセルされたか確認します
delay(ms)	はい	実行を一時停止します
throttle(ms, pattern, saga)	いいえ	実行頻度を制限します
debounce(ms, pattern, saga)	いいえ	入力が止まるまで待機します
retry(n, delay, fn)	はい	バックオフしながら再試行します
race(effects)	はい	最初に完了したものを採用します
all([effects])	子のいずれかがブロッキングする場合	並列実行し、すべてを待機します
setContext(props) / getContext(prop)	いいえ / はい	Saga コンテキスト

パターンマッチング

take、takeEvery、takeLatest、takeLeading、throttle、debounce は、次の値を受け取ります。

パターン	一致条件
'*'	すべてのアクション
'ACTION_TYPE'	action.type が完全一致
[type1, type2]	配列内のいずれかの型
fn => boolean	カスタム述語

引数を完全に省略できるのは take／takeMaybe のみです。take() はすべてのアクションに一致します。 takeEvery、takeLatest、takeLeading、throttle、debounce ではパターンが必須パラメーターです。すべてを捕捉するウォッチャーには '*' を使用してください。

multicastChannel から受け取る場合もパターンが必要です。take(chan) ではなく、take(chan, '*') を使用してください。

使い方

詳しい説明とコード例については、各ルールファイルを参照してください。

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

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加のコンテキストと判断表

参考資料

優先度	参考資料	参照するタイミング
1	references/effects-and-api.md	Saga の作成またはデバッグ全般
2	references/fork-model.md	並行処理、エラー伝播、キャンセル
3	references/testing.md	Saga テストの作成またはレビュー
4	references/channels.md	外部 I/O、バッファリング、ワーカープール
5	references/recipes.md	スロットリング、デバウンス、再試行、取り消し、バッチ処理、ポーリング
6	references/anti-patterns.md	避けるべきよくある間違い
7	references/troubleshooting.md	フリーズしたアプリ、見逃されたアクション、スタックトレースのデバッグ

完全版ドキュメント

すべてのルールを展開した完全なガイド：AGENTS.md