@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.
171 lines (135 loc) • 6.61 kB
Markdown
---
name: core/wait-for
description: >-
Concise agent rules for waitFor(selector, argsTuple, predicate, timeoutMs?).
Use when a saga must pause until a named selector reaches a predicate. It
checks the current value first, subscribes through createChannelFromSelector,
returns true on match and false on timeout, and closes the channel in finally.
type: sub-skill
requires:
- core
- svelte/selectors
- core/sagas
triggers:
- waitFor selector
- suspend saga
- wait predicate
- timeout wait
---
# waitFor — agent implementation rules
Use this skill for one-shot saga waits on selector state. Keep conceptual/API prose and examples in `docs/WAITFOR.md`; this skill should stay concise and operational.
## Canonical references
- Human guide: `docs/WAITFOR.md`
- Public API: `waitFor` from `@augmentcode/ag-redux-toolkit/saga`.
- Channel helpers: `@augmentcode/ag-redux-toolkit/utils/sagas/selector-channel-effects` or aggregate `@augmentcode/ag-redux-toolkit/saga`.
- Related skills: `core/sagas`, `svelte/selectors`, `core/selector-channels`, `core/testing`
## Use when
- A saga must wait for a selector value before continuing.
- The condition is one-shot: proceed after the predicate matches or timeout handling runs.
- The selector already exists as a named selector, authored with `store.createSelector(...)` for app-local selectors when a configured Store exists.
## Do
- Call as `waitFor(selector, argsTuple, predicate, timeoutMs?)`.
- Pass `[]` for no-arg selectors and `[arg1, arg2]` for selector arguments.
- Keep the predicate pure: no dispatches, API calls, mutations, timers, or state reads.
- Add a timeout for production waits unless an indefinite wait is explicitly safe.
- Check the boolean return when a timeout is supplied.
- Guard previous-value comparisons because the immediate check passes `undefined` as `prevVal`, and the first selector-channel emission can pass `null`.
## Don't
- Do not pass inline selectors or closures; create/reuse a named selector.
- Do not swap the args tuple and predicate.
- Do not ignore `false` from timed waits.
- Do not use `waitFor` for polling or continuous reactions; use `takeLatestFromSelector`, `takeEveryFromSelector`, or a selector channel instead.
- Do not duplicate the implementation's channel/race logic in app code.
## Implementation cues
- Import from `@augmentcode/ag-redux-toolkit/saga` unless an existing app-local barrel already re-exports it.
- For boolean readiness, predicate on the desired final value rather than assuming truthiness.
- For status transitions, include the terminal states in the predicate and branch after `waitFor` if different terminal outcomes matter.
- For timeout paths, dispatch or return an explicit timeout outcome before continuing with state-dependent work.
- If a saga needs every future selector change, route to `core/selector-channels` instead.
## Examples
### 1. Wait for a no-arg boolean selector and handle timeout
```ts
import { put } from "typed-redux-saga";
import { waitFor } from "@augmentcode/ag-redux-toolkit/saga";
function* loadWhenReady() {
const ready = yield* waitFor(selectIsReady, [], (value) => value === true, 5_000);
if (!ready) {
yield* put(loadTimedOut());
return;
}
yield* put(loadData());
}
```
### 2. Pass selector arguments as the required args tuple
```ts
import { waitFor } from "@augmentcode/ag-redux-toolkit/saga";
function* processItem(itemId: string) {
const ready = yield* waitFor(selectItemStatus, [itemId], (status) => status === "ready", 10_000);
if (ready) yield* startItemProcessing(itemId);
}
```
### 3. Guard previous-value comparisons on the immediate check
```ts
import { waitFor } from "@augmentcode/ag-redux-toolkit/saga";
function* waitForReconnect() {
const reconnected = yield* waitFor(
selectConnectionStatus,
[],
(value, prevVal) => prevVal === "connecting" && value === "connected",
15_000
);
return reconnected;
}
```
### 4. Branch after terminal-state waits
```ts
import { put } from "typed-redux-saga";
import { waitFor } from "@augmentcode/ag-redux-toolkit/saga";
function* waitForUpload(uploadId: string) {
const finished = yield* waitFor(selectUploadPhase, [uploadId], (phase) => phase === "done" || phase === "failed", 60_000);
if (!finished) return yield* put(uploadTimedOut(uploadId));
const phase = yield* selectUploadPhase.effect(uploadId);
if (phase === "failed") yield* put(uploadFailed(uploadId));
}
```
### 5. Use waitFor inside an action worker before state-dependent work
```ts
import { call, put } from "typed-redux-saga";
import { waitFor } from "@augmentcode/ag-redux-toolkit/saga";
function* publishAfterAuthWorker(action: ReturnType<typeof publishDocument>) {
const authenticated = yield* waitFor(selectAuthReady, [], Boolean, 5_000);
if (!authenticated) return yield* put(publishRejected(action.payload[0], "auth-timeout"));
yield* call(api.publishDocument, action.payload[0]);
}
```
### 6. ❌ Bad: ignoring false and treating prevVal as present on the first check
```ts
// BAD: timeout false is ignored, and prevVal can be undefined or null before a real transition.
function* publishAfterAnyStatusChange(documentId: string) {
yield* waitFor(selectDocumentStatus, [documentId], (value, prevVal) => value !== prevVal, 5_000);
yield* call(api.publishDocument, documentId);
}
function* publishAfterRealStatusChange(documentId: string) {
const changed = yield* waitFor(
selectDocumentStatus,
[documentId],
(value, prevVal) => prevVal !== undefined && prevVal !== null && value !== prevVal,
5_000
);
if (changed) yield* call(api.publishDocument, documentId);
}
```
## Verification cues
- Test immediate-match, later-match, and timeout paths when changing `waitFor` usage.
- In saga tests, provide selector `.effect(...)` values and channel/timer effects through existing test helpers.
- Run the smallest relevant saga tests when docs/skills examples change.
## Common mistakes to prevent
- `waitFor(selectReady, predicate)` — missing `[]` args tuple.
- Acting after a timed wait without checking the returned boolean.
- Predicate change detection that treats initial `prevVal === undefined` or first-emission `prevVal === null` as a real transition.
- Replacing one-shot waits with hand-rolled selector channels.
## See also
- `docs/WAITFOR.md` — full signature, behavior walkthrough, and examples.
- `docs/SAGAS.md` — selector-channel and saga orchestration context.
- `core/selector-channels` — continuous selector watchers.
- `svelte/selector-lifecycle` — selector call modes.