@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.
298 lines (208 loc) • 13.4 kB
Markdown
# Selectors Guide
> **How to create and use selectors with proxy-based memoization.**
---
## Table of Contents
1. [What are Selectors?](#what-are-selectors)
2. [Creating Selectors](#creating-selectors)
3. [Using Selectors](#using-selectors)
4. [Proxy-Based Memoization](#proxy-based-memoization)
5. [Collection Selectors](#collection-selectors)
6. [Selector Lifecycle Rules](#selector-lifecycle-rules)
7. [Best Practices](#best-practices)
8. [Anti-Patterns](#anti-patterns)
---
## What are Selectors?
Selectors are pure functions that extract and derive data from the Redux store. In production app code, create app-local selectors from the configured `Store` instance with `store.createSelector(...)`. The Store-bound helper delegates to the lower-level selector utility while typing the callback `state` as `StoreInstanceState<typeof store>` (`StoreState<typeof store>` remains supported). That concrete state resolves reducer domains to app state types (for example, `counter: CounterState` and `todos: TodosState`) instead of exposing reducer call signatures or helper members. Selectors provide:
- **Automatic memoization** — Proxy-based tracking of accessed state paths; only recomputes when those paths change.
- **Multiple usage modes** — Svelte reactive stores, React signals/component reads, Kefir streams, saga effects, and direct state reads.
- **Type safety** — Full TypeScript inference for arguments and return types.
- **Composability** — Selectors can call other selectors via `.select()`.
---
## Creating Selectors
Use the configured app Store as the public selector creation API for production app-local selectors. `Store` is the canonical Svelte-readable class available from `@augmentcode/ag-redux-toolkit/svelte-store`, `ReactStore` from `@augmentcode/ag-redux-toolkit/react-store` returns Preact React signals from selector calls and adds React `.useValue(...)`, and `StreamingStore` from `@augmentcode/ag-redux-toolkit/streaming-store` returns Kefir streams from selector calls. If shared code needs reusable selector logic, pass a configured Store into that helper and call `store.createSelector(...)` at the app integration boundary.
```typescript
import { Store } from "@augmentcode/ag-redux-toolkit/svelte-store";
import type { StoreInstanceState } from "@augmentcode/ag-redux-toolkit/types";
import { todosReducer } from "./todos-slice";
export const store = new Store({ todos: todosReducer });
export type AppState = StoreInstanceState<typeof store>;
```
`StoreInstanceState<typeof store>` is the same shape available inside `store.createSelector` callbacks: each reducer domain is inferred as its state object, not as the reducer function or reducer helper object used to configure the Store.
Svelte-readable, React signal, and StreamingStore selector emissions default to `64` FPS. To tune coalescing, pass Store options as the final constructor argument. The value must be finite and within the inclusive `1..256` FPS range; fractional values such as `48.5` are accepted, and invalid values throw instead of clamping.
```typescript
export const store = new Store(
{ todos: todosReducer },
undefined,
{ throttledSelectorFrequency: 48.5 }
);
```
### Simple Selector (No Arguments)
```typescript
import { store } from "$lib/store";
export const selectItemCount = store.createSelector((state) => {
return state.todos.collection.ids.length;
});
```
### Selector with Arguments
```typescript
export const selectTodoById = store.createSelector((state, todoId: string) => {
return state.todos.collection.map[todoId];
});
```
### Composing Selectors
Call `.select()` on other selectors to reuse computations:
```typescript
export const selectCompletedTodos = store.createSelector((state) => {
const todos = selectAllTodos.select(state);
return todos.filter((t) => t.completed);
});
export const selectCompletedCount = store.createSelector((state) => {
return selectCompletedTodos.select(state).length;
});
```
---
## Using Selectors
Selectors provide multiple methods for different contexts. `Store.createSelector` uses the package's Svelte-readable selector model; `ReactStore.createSelector` uses the React signal selector model and returns Preact React signals from direct calls; `StreamingStore.createSelector` uses the streaming selector model and returns Kefir streams from direct calls. Choose the Store class instead of constructor injection for selector behavior.
### 1. In Svelte Components (Reactive)
The default call returns a Svelte readable store:
```typescript
// At component init (top-level <script>)
const count = selectItemCount();
const todo = selectTodoById(todoId);
// Use with $store syntax in template
// {$count} items, editing {$todo?.title}
```
### 2. In React components and signal-aware code
`ReactStore` direct selector calls return `ReadonlySignal<R>` values and are the preferred React consumer integration path when components, custom hooks, or helper APIs can accept signals. Use `.useValue(...args)` only when a hook/plain value is required and adapting the consumer to accept signals is impractical.
```tsx
import { ReactStore } from "@augmentcode/ag-redux-toolkit/react-store";
export const reactStore = new ReactStore({ todos: todosReducer });
export const selectTodoById = reactStore.createSelector((state, todoId: string) => {
return state.todos.collection.map[todoId];
});
const todoSignal = selectTodoById("todo-1");
console.log(todoSignal.value);
function TodoTitle({ id }: { id: string }) {
const todo = selectTodoById(id);
return <span>{todo.value?.title}</span>;
}
```
Direct signal calls and `.useValue(...args)` are throttled by the owning `ReactStore`'s `throttledSelectorFrequency`. Selector arguments may be plain values or `ReadonlySignal` values; signal arguments are read reactively by the computed selector. Keep `.useValue(...args)` for third-party components, legacy hook boundaries, or other places that must receive plain `R`.
### 3. In Sagas (`.effect()`)
```typescript
function* mySaga() {
const count = yield* selectItemCount.effect();
const todo = yield* selectTodoById.effect(todoId);
}
```
`.effect(...args)` is saga-only for every Store variant. It creates a typed-redux-saga select effect over the selector callback; it is not a React hook, Svelte readable, Kefir observable, signal subscription, or throttled render path.
### 4. Direct State Access (`.select()`)
For tests, event handlers, or composing selectors:
```typescript
import { store as appStore } from "$lib/store";
// In tests
const state = appStore.state;
const count = selectItemCount.select(state);
// In event handlers (where getContext is unavailable), use an initialized
// Store instance captured from module/component context.
function handleClick() {
const value = selectItemCount.select(appStore.state);
}
```
### 5. Bound to a Store (`.withStore()`)
```typescript
const boundSelector = selectTodoById.withStore(store);
const todo = boundSelector(todoId); // Returns the direct-call type for that Store family
```
For `Store`, the bound result is a Svelte `Readable<R>`. For `ReactStore`, the bound result is a `ReadonlySignal<R>` and may bind either a `ReactStore`/signal-state source or a state signal. For `StreamingStore`, the bound result is a Kefir `Observable<R, any>`.
### 6. Streaming Store selectors
```typescript
import { StreamingStore } from "@augmentcode/ag-redux-toolkit/streaming-store";
export const streamStore = new StreamingStore({ todos: todosReducer });
export const selectTodoCountStream = streamStore.createSelector((state) => state.todos.collection.ids.length);
const todoCount$ = selectTodoCountStream(); // Returns Kefir Observable<number, any>
```
Streaming selectors emit their first available value promptly. Subsequent rapid Store state updates or observable selector argument updates are coalesced at the Store's configured `throttledSelectorFrequency`, and only the latest pending selector result emits at the scheduled moment.
---
## Proxy-Based Memoization
`store.createSelector` uses **proxy-based state tracking** for intelligent caching through package internals:
1. **Tracks accessed paths** — When a selector runs, a Proxy records which state fields were accessed.
2. **Selective re-execution** — On subsequent calls, only re-runs if an accessed path's reference changed.
3. **Argument tracking** — Also re-runs when arguments change (shallow equality).
4. **Collection optimization** — Stops proxying at Collection boundaries since Collections are immutable and always change reference when modified.
```typescript
// This selector only re-runs when:
// - state.todos.collection changes (reference equality)
// - OR the todoId argument changes (shallow equality)
export const selectTodoById = store.createSelector((state, todoId: string) => {
return state.todos.collection.map[todoId];
});
```
### Store-Owned Update Scheduling
Selector emissions are scheduled and coalesced by the Store/selector internals so rapid Redux writes do not force unnecessary UI or stream consumer work. Svelte-readable `Store` selectors, React signal `ReactStore` selectors, and Kefir-based `StreamingStore` selectors use the configured `throttledSelectorFrequency` from the Store constructor options, defaulting to `64` FPS. Selector trace output is a separate default-off diagnostic; pass `{ traceSelectors: true }` in the same final Store options object only while diagnosing selector scheduling, and omit it or pass `false` for normal silent behavior. There is no public lock/unlock action API; model batching through ordinary action design, saga orchestration, and selectors that derive the final UI value.
---
## Collection Selectors
For working with Collections, keep collection access behind Store-bound selectors and use the public collection utilities inside those selector callbacks:
```typescript
import { getItem, getItems, type Collection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils";
import { store } from "$lib/store";
// Get the collection itself
export const selectTodosCollection = store.createSelector(
(state): Collection<Todo, "id"> => state.todos.collection
);
// Get a single item by ID (optimized O(1) lookup)
export const selectTodo = store.createSelector((state, id: string) => {
return getItem(selectTodosCollection.select(state), id);
});
// Get all items as an ordered array
export const selectAllTodos = store.createSelector((state) => {
return getItems(selectTodosCollection.select(state));
});
```
---
## Selector Lifecycle Rules
| Context | Correct Usage | Why |
|---------|---------------|-----|
| Component init (top-level `<script>`) | `const val = selectFoo()` | Returns Svelte readable. Uses `getContext()` — only valid at init. |
| React component/custom hook | `const valueSignal = selectFoo(...args)` | Preferred path; returns `ReadonlySignal<R>` for direct signal `.value` or signal-aware rendering. |
| Hook/plain-value fallback | `const value = selectFoo.useValue(...args)` | Use only when a React component/custom hook must receive plain `R` and accepting a signal is impractical. |
| Event handlers, callbacks | `selectFoo.select(appStore.state)` | Direct read from an initialized `Store` instance captured outside the handler. No Svelte context needed. |
| Sagas | `yield* selectFoo.effect()` | Uses redux-saga's `select` effect. |
| Composing selectors | `selectFoo.select(state)` | Direct read within another selector. |
**⚠️ CRITICAL for Svelte `Store`:** Never call `selectFoo()` (the readable form) inside event handlers, callbacks, or async functions — it calls `getContext()` which only works during component initialization. For React `ReactStore`, prefer direct selector signals in components/custom hooks and reserve `.useValue(...args)` for necessary plain-value fallbacks; non-component one-shot code should use `.select(state, ...args)`.
---
## Best Practices
1. **Always create named selectors** — Define selectors in `*-selectors.ts` files, never inline.
2. **Compose selectors** — Reuse existing selectors via `.select()` instead of re-reading state paths.
3. **Use descriptive names** — `selectCurrentConversationId`, not `getCurrentId`.
4. **Return same reference when possible** — If no filtering/mapping is needed, return the state value directly.
5. **Never mutate in selectors** — Use `[...array].sort()` instead of `array.sort()`.
6. **No side effects** — No console.log, no analytics, no mutations.
---
## Anti-Patterns
### ❌ Inline Selectors in Sagas
```typescript
// BAD
const value = yield* select((state) => state.todos.items);
// GOOD
const value = yield* selectAllTodos.effect();
```
### ❌ Creating Selectors Inside Components
```typescript
// BAD — creates new selector on every render
const selector = store.createSelector((state) => state.todos.count);
// GOOD — defined at module level
export const selectTodoCount = store.createSelector((state) => state.todos.count);
```
### ❌ Calling Readable Form Outside Component Init
```typescript
import { store as appStore } from "$lib/store";
// BAD — crashes with lifecycle_outside_component
function handleClick() {
const val = get(selectFoo());
}
// GOOD — use .select() with an initialized Store instance captured outside the handler
function handleClick() {
const val = selectFoo.select(appStore.state);
}
```