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.

164 lines (127 loc) • 5.59 kB
# waitFor Saga Utility Guide > Wait for a selector to reach an expected value before continuing. ## Table of Contents 1. [Overview](#overview) 2. [Function Signature](#function-signature) 3. [How It Works](#how-it-works) 4. [Usage Examples](#usage-examples) 5. [Rules and Best Practices](#rules-and-best-practices) 6. [Related Utilities](#related-utilities) ## Overview `waitFor` is a saga utility that pauses execution until a selector's value matches an expected condition. It's useful for coordinating async operations that depend on state changes — for example, waiting for data to finish loading before proceeding. **Import:** `import { waitFor } from "@augmentcode/ag-redux-toolkit/saga"` (the public `@augmentcode/ag-redux-toolkit/saga` subpackage; the internal implementation lives in `src/slices/store-utility/sagas/waitFor.ts` and must not be imported directly) ## Function Signature ```typescript function* waitFor<ARGS extends any[], R>( selector: StoreSelector<R, ARGS>, args: ARGS, isExpectedValue: (value: R, prevVal: R | undefined | null) => boolean, timeoutMs?: number ): Generator<any, boolean, any> ``` ### Parameters | Parameter | Type | Description | | --- | --- | --- | | selector | StoreSelector<R, ARGS> | A named selector; for production app-local selectors, create it with `store.createSelector(...)` | | args | ARGS | Arguments to pass to the selector (use [] for no-arg selectors) | | isExpectedValue | (value: R, prevVal: R | undefined | null) => boolean | Predicate that returns true when the condition is met | | timeoutMs | number (optional) | Maximum wait time in milliseconds | ### Return Value - Returns `true` when the expected condition is met - Returns `false` if `timeoutMs` is provided and the timeout elapses first - Without `timeoutMs`, waits indefinitely until the condition is met ## How It Works 1. **Immediate check** — Reads the selector's current value. If it already matches, returns `true` immediately. 2. **Channel subscription** — If the value doesn't match, creates a channel to listen for state changes via `createChannelFromSelector`. 3. **Value monitoring** — Each time the selector emits a new value, checks the predicate. 4. **Timeout race** — If `timeoutMs` is provided, races between value match and a `delay(timeoutMs)`. 5. **Cleanup** — Always closes the channel in a `finally` block to prevent memory leaks. ``` waitFor(selector, args, predicate, timeout?) │ ├─ Read current value via selector.effect() │ └─ If predicate(value) → return true (immediate) │ ├─ Create channel from selector │ ├─ If timeout provided: │ └─ race({ value: checkChannel, timeout: delay(ms) }) │ ├─ value wins → return true │ └─ timeout wins → return false │ └─ If no timeout: └─ Wait on channel until predicate matches → return true ``` ## Usage Examples ### Basic: Wait for a Boolean Flag ```typescript import { waitFor } from "@augmentcode/ag-redux-toolkit/saga"; function* mySaga() { // Wait for loading to complete yield* waitFor( selectIsLoading, [], (isLoading) => isLoading === false ); // Continue after loading is done yield* put(doNextStep()); } ``` ### With Selector Arguments ```typescript function* processItem(itemId: string) { // Wait for a specific item's status yield* waitFor( selectItemStatus, [itemId], (status) => status === "ready" ); yield* put(startProcessing(itemId)); } ``` ### Using Previous Value The predicate receives both the current and previous value, enabling change detection: ```typescript function* detectChange() { // Wait for value to change from its current state yield* waitFor( selectStatus, [], (value, prevVal) => { return prevVal !== undefined && value !== prevVal; } ); yield* put(statusChanged()); } ``` ### Complex Condition ```typescript function* waitForCompletion(taskId: string) { yield* waitFor( selectTaskPhase, [taskId], (phase) => phase === "completed" || phase === "error" ); } ``` ## Rules and Best Practices ### ✅ DO 1. **Always use named selectors** — Pass named selectors; for production app-local selectors, create them with `store.createSelector(...)`, never inline lambdas. 2. **Keep **`isExpectedValue`** pure** — No side effects, no API calls, no mutations. 3. **Add timeouts for production code** — Prevent indefinite waits. 4. **Handle the timeout case** — When using `timeoutMs`, always check the return value. 5. **Use empty array for no-arg selectors** — `waitFor(selectFoo, [], predicate)`. ### ❌ DON'T 1. **Don't use inline selectors** — `waitFor((state) => state.foo, ...)` is not supported. 2. **Don't perform side effects in the predicate** — Keep `isExpectedValue` pure. 3. **Don't wait indefinitely in production** — Always consider a reasonable timeout. 4. **Don't use for polling** — Use `takeLatestFromSelector` or channels for continuous monitoring. 5. **Don't ignore the return value when using timeouts** — A `false` return means the condition was not met. ## Related Utilities | Utility | Purpose | | --- | --- | | createChannelFromSelector | Create a channel from a selector for custom patterns | | takeLatestFromSelector | Watch selector changes continuously (cancel previous) | | takeEveryFromSelector | Watch selector changes continuously (handle all) | | delay | Simple time-based delays without state monitoring | → See [SAGAS.md](./SAGAS.md) for channel and selector effect patterns.