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.

106 lines (88 loc) • 4.72 kB
--- name: react/selectors description: >- Author ReactStore selectors whose direct calls return Preact React ReadonlySignal values and are the preferred React consumer integration path. Covers signal selector arguments, Store-bound creation, .useValue(...args) as a fallback for hook/plain-value boundaries, .withStore(signalSource), pure .select(state) composition/testing, and saga-only .effect() usage without importing React selector internals. type: sub-skill requires: - react - core/state-integrity sources: - "@augmentcode/ag-redux-toolkit/react-store" - augmentcode/ag-redux-toolkit:docs/SELECTORS.md triggers: - React selector - selector .useValue - signal selector - ReadonlySignal selector - ReactStore selector --- # React selectors — signal-first call model Use this skill when `store.createSelector(...)` belongs to a `ReactStore` and direct selector calls should produce Preact React `ReadonlySignal<R>` results. Direct selector calls are the preferred React consumer integration path when callers can pass, read, or render signals through the Preact React signal integration. Use `.useValue(...args)` only when a hook/plain value is required and adapting the consumer to accept a signal is impractical. ## Authoring rules - Create selectors through the configured `ReactStore` instance. - Keep selector callbacks pure and derived-only; reducers must not store selectoroutputs. - Compose selectors with `.select(state, ...args)` inside another selector. - Do not import from `ag-redux-toolkit` React selector internal deep paths. ```tsx import { ReactStore } from "@augmentcode/ag-redux-toolkit/react-store"; import type { ReadonlySignal } from "@preact/signals-react"; export const reactStore = new ReactStore({ todos: todosReducer }); export const selectTodo = reactStore.createSelector((state, id: string) => { return state.todos.collection.map[id]; }); type Todo = { title: string } | undefined; function TodoTitle({ todo }: { todo: ReadonlySignal<Todo> }) { return <span>{todo.value?.title}</span>; } function TodoRow({ id }: { id: string }) { const todo = selectTodo(id); return <TodoTitle todo={todo} />; } ``` ## Call forms | Context | Use | Result | | --- | --- | --- | | Preferred React/signal-aware consumer | selectFoo(...argsOrSignals) | ReadonlySignal<R> | | Hook/plain-value fallback | selectFoo.useValue(...argsOrSignals) | Plain value R | | Alternate signal state | selectFoo.withStore(signalSource)(...args) | ReadonlySignal<R> | | Tests/handlers/composition | selectFoo.select(state, ...args) | Plain value R | | Sagas | yield* selectFoo.effect(...args) | typed-redux-saga select effect | Selector arguments may be plain values or Preact React signals. Prefer direct signal outputs for React consumers that can accept signals; they and `.useValue(...args)` are throttled by the owning `ReactStore`'s `throttledSelectorFrequency` option, defaulting to `64` FPS. `.useValue(...args)` remains valid only for third-party APIs, legacy component boundaries, or custom hooks that must return a plain value. Selector trace output is disabled by default; pass `{ traceSelectors: true }` in the final Store options object only for temporary diagnostics. `.effect(...args)` is saga-only; it is not a React hook, signal subscription, or throttled render path. Selector-channel helpers that consume `.effect(...)`-compatible selectors run insagas and subscribe through the Redux store object's `getState()` / `subscribe()`context path, not through React signals or a Svelte readable wrapper. ## Don't - Do not call `.useValue(...args)` outside React components or custom hooks. - Do not choose `.useValue(...args)` as the default React render path when a component or helper can be adapted to accept a `ReadonlySignal<R>`. - Do not use Svelte `$selector` syntax, Svelte readable lifecycle rules, or Kefir observable selector arguments in the same React app. - Do not call another selector's direct signal form inside a selector callback; use `.select(state)` to keep composition pure and synchronous. - Do not use standalone React selector utilities as public package imports. ## Verification cues - React component examples prefer direct selector calls and pass/read `ReadonlySignal` values when signal integration supports it. - `.useValue(...args)` examples are framed as hook/plain-value fallback reads, not the default consumer path. - Unit tests for pure selector logic use `.select(mockState, ...args)`. ## See also - `react/store/SKILL.md` — Store class and import choice. - `docs/SELECTORS.md` — human reference and examples for all call forms. - `core/state-integrity/SKILL.md` — canonical derived-value ownership.