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.

192 lines (147 loc) • 7.24 kB
--- name: svelte/selector-scheduling description: >- Public guidance for Store-owned selector emission coalescing and optional FPS tuning. Selector scheduler helpers are internal details and must not be imported from any public subpackage. Use Store-bound selectors directly; their readables are already scheduled by package internals. type: sub-skill requires: - svelte - svelte/selectors triggers: - throttled readable - rAF coalescing - selector scheduler --- # Selector emission scheduling — internal only > Selector scheduler helpers are implementation details. Do not import them from package subpaths or teach consumers to wrap selector readables manually. Public facade: `@augmentcode/ag-redux-toolkit/svelte-store` (`store.createSelector` and `Store` selector options). Selector implementation and scheduler internals are package-private; see `docs/SELECTORS.md` for behavior. ## Store-first rule - Create app selectors with the configured `Store` instance: `store.createSelector(...)`. - Tune Svelte-readable selector coalescing only through the final constructor options argument: `new Store(reducers, middleware, { throttledSelectorFrequency })`. - Treat this as Svelte Store family scheduling only. Do not use StreamingStore,Kefir stream throttling, or streaming selector lifecycle/setup guidance in thesame app. - Omit `throttledSelectorFrequency` for the default `64` FPS; explicit values must be finite numbers in the inclusive `1..256` range. Fractional values are supported. - Selector trace output is disabled by default; pass `{ traceSelectors: true }` in the final Store options object only for temporary diagnostics. - In components, call selector readables directly at component init: `const value$ = selectValue()`. - Let the package's selector internals schedule/coalesce readable emissions. - For one-shot reads, use `selectValue.select(store.state, ...args)`. - For sagas, use `yield* selectValue.effect(...args)`. - For explicit non-context binding, use `selectValue.withStore(store)(...args)` after `store.init()`. ## Do not - Do not import selector scheduler internals from app code. - Do not wrap selector readables in a second debounce, timer, `requestAnimationFrame`, or writable proxy just to reduce UI updates. - Do not rely on selector readables as audit/event streams; they represent the latest derived state and may coalesce intermediate writes. - Do not call selector readable mode from event handlers, callbacks, async functions, services, or tests; use `.select(store.state, ...)` or `.withStore(store)`. - Do not replace this Svelte-readable scheduling model with StreamingStore/Kefirselector setup in the same app. ## Examples ### 1. Define selectors through the configured Store ```ts import { store } from "$lib/store"; type Pointer = { x: number; y: number }; export const selectPointer = store.createSelector((state): Pointer => { return state.pointer.current; }); export const selectPointerLabel = store.createSelector((state) => { const pointer = selectPointer.select(state); return `${pointer.x},${pointer.y}`; }); ``` ### 2. Component init reads the already-scheduled selector readable directly ```ts import { onDestroy } from "svelte"; import { selectPointer, selectPointerLabel } from "./pointer-selectors"; declare function renderPointer(value: { x: number; y: number }): void; export const pointer = selectPointer(); export const pointerLabel = selectPointerLabel(); const unsubscribe = pointer.subscribe((value) => renderPointer(value)); onDestroy(unsubscribe); ``` ### 3. Event handlers use `.select(store.state)` for one-shot reads ```ts import { store } from "$lib/store"; import { selectPointer } from "./pointer-selectors"; import { copyPointer } from "./pointer-slice"; export function handleCopyPointer() { const pointer = selectPointer.select(store.state); store.dispatch(copyPointer(pointer)); } ``` ### 4. Bind to an explicit initialized Store with `.withStore` ```ts import type { Store } from "@augmentcode/ag-redux-toolkit/svelte-store"; import { selectPointer } from "./pointer-selectors"; export function createPointerReadable(store: Store) { return selectPointer.withStore(store)(); } ``` ### 5. Saga code uses `.effect()` rather than readable scheduling ```ts import { call, put, takeLatest } from "typed-redux-saga"; import { pointerMoved, pointerPersisted } from "./pointer-slice"; import { selectPointer } from "./pointer-selectors"; declare const api: { savePointer(pointer: { x: number; y: number }): Promise<void> }; export function* pointerSaga() { yield* takeLatest(pointerMoved, function* persistPointer() { const pointer = yield* selectPointer.effect(); yield* call(api.savePointer, pointer); yield* put(pointerPersisted()); }); } ``` ### 6. ❌ Bad: wrapping selector readables in another timer layer ```ts // BAD: this compiles but adds stale updates on top of Store-owned scheduling. import { writable, type Readable } from "svelte/store"; import { selectPointer } from "./pointer-selectors"; type Pointer = { x: number; y: number }; export function createManuallyDebouncedPointer(): Readable<Pointer> { const output = writable<Pointer>({ x: 0, y: 0 }); selectPointer().subscribe((value) => setTimeout(() => output.set(value), 100)); return output; } ``` ### 7. ❌ Bad: treating selector readables as event logs ```ts // BAD: selector readables represent latest state and may coalesce intermediate writes. import { selectPointer } from "./pointer-selectors"; type Pointer = { x: number; y: number }; export function recordEveryPointerMove(audit: Pointer[]) { const unsubscribe = selectPointer().subscribe((pointer) => audit.push(pointer)); return unsubscribe; } ``` ### 8. Prefer action or saga evidence when every event matters ```ts import { call, takeEvery } from "typed-redux-saga"; import { pointerMoved } from "./pointer-slice"; declare const auditLog: { write(event: string, payload: unknown): Promise<void> }; export function* pointerAuditSaga() { yield* takeEvery(pointerMoved, function* auditPointerMove(action) { yield* call(auditLog.write, "pointer-moved", action.payload[0]); }); } ``` ### Examples retained/added | # | Example | Kind | | --- | --- | --- | | 1 | Store-bound selector definitions | Good | | 2 | Component-init readable subscription and cleanup | Good | | 3 | One-shot handler read with .select(store.state) | Good | | 4 | Explicit Store binding with .withStore(store) | Good | | 5 | Saga state read with .effect() | Good | | 6 | Manual debounce/timer wrapper around selector readable | Bad | | 7 | Selector readable used as an event/audit stream | Bad | | 8 | Action-driven saga audit replacement | Good | ### Cases covered | Case | Examples | | --- | --- | | Store-owned selector scheduling and current public API | 1, 2 | | Component lifecycle and cleanup | 2 | | Handler/service one-shot reads | 3 | | Explicit Store compatibility binding | 4 | | Saga read mode that bypasses readable scheduling | 5 | | Realistic scheduling misuse not caught by missing imports | 6, 7, 8 | ## See also - `svelte/selectors` — building Store-bound selectors. - `docs/SELECTORS.md` — selector memoization and lifecycle rules.