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.

166 lines (127 loc) • 6.47 kB
--- name: svelte/selector-lifecycle description: >- The three selector call modes and Store-first dispatch rule — the #1 source of runtime crashes in ag-redux-toolkit. Covers selectFoo() at component init (Svelte readable via getContext), selectFoo.select(state) for one-shot reads in event handlers / callbacks / async, yield* selectFoo.effect() inside sagas, and selectFoo.select(state) when composing selectors. Documents Store.dispatch usage, the lifecycle_outside_component crash, and the wrong-shape trap when passing the selector object to yield* select(). type: sub-skill requires: - svelte - svelte/selectors triggers: - selector call mode - outside component crash - Store dispatch - select in handler --- # Selector Lifecycle — call-mode guardrails > Operational checklist for avoiding `lifecycle_outside_component`. Human reference and examples: `docs/SELECTORS.md` → Using Selectors and Selector Lifecycle Rules. Source: `../SKILL.md` §4, §7. ## Use when - Selecting values from components, event handlers, callbacks, tests, sagas, or other selectors. - Debugging `lifecycle_outside_component` crashes. - Moving selector reads across component initialization boundaries. Use this lifecycle only for apps that chose the Svelte Store family. Do not apply ReactStore/signal `.useValue(...)` or StreamingStore/Kefir selector invocation, observation, setup, or teardown rules in the same app/package/code path. ## Call-mode map | Context | Correct call | Why | | --- | --- | --- | | Component init/top-level `<script>` | `const value$ = selectFoo(args)` | Uses Svelte context and returns a readable. | | Template | Use the captured readable as `$value$` | Avoids creating new readables during render. | | Event handler/callback/async/test | `selectFoo.select(state, args)` | No Svelte context required. | | Saga | `yield* selectFoo.effect(args)` | Emits the package's typed saga select effect. | | Selector composition | `otherSelector.select(state, args)` | Reuses state already in scope. | | Non-context readable | `selectFoo.withStore(store)(args)` | Binds explicitly to a store. | ## Do - Capture selector readables during component initialization and dispatch through the configured Store instance. - Use `.select(store.state, ...)` with the existing initialized `Store` instance captured outside the handler for one-shot reads when no state argument is already available. - Use `.effect()` in sagas instead of passing selector objects to `select`. - Use `.select(state)` when composing selectors or testing them. ## Don't - Do not call `selectFoo()` after `await`, inside handlers, inside callbacks, in tests, or inside another selector. - Do not call `get(selectFoo())` outside component initialization. - Do not import standalone dispatch helpers; use `store.dispatch(action)` on the configured Store instance. - Do not pass the selector object itself to saga `select`; use `.effect()` or `.select` intentionally. - Do not replace Svelte readable lifecycle rules with React signal or streaming selector lifecycle rules in a Svelte app. ## Examples ### 1. Capture selector readables during component initialization ```ts import { store as appStore } from "$lib/store"; const item$ = selectItem(itemId); const canSave$ = selectCanSaveItem(itemId); function onSave() { const item = selectItem.select(appStore.state, itemId); if (item) appStore.dispatch(saveItem(item)); } ``` ### 2. Derive template-facing values from captured readables ```ts import { derived } from "svelte/store"; const item$ = selectItem(itemId); const itemTitle$ = derived(item$, (item) => item?.title ?? "Untitled"); ``` ### 3. Use .select after await or inside callbacks ```ts import { store as appStore } from "$lib/store"; async function onArchive(itemId: string) { await confirmArchiveDialog(itemId); const item = selectItem.select(appStore.state, itemId); if (item?.status !== "archived") appStore.dispatch(archiveItem(itemId)); } ``` ### 4. Use .effect inside sagas instead of passing selector objects to select ```ts import { put } from "typed-redux-saga"; function* saveCurrentItemWorker() { const itemId = yield* selectCurrentItemId.effect(); if (itemId) yield* put(saveItem(itemId)); } ``` ### 5. Compose selectors with .select(state) ```ts export const selectVisibleItems = store.createSelector((state) => { const items = selectItems.select(state); const filter = selectItemFilter.select(state); return items.filter((item) => item.status === filter.status); }); ``` ### 6. Bind explicitly with .withStore when no Svelte context is available ```ts import type { Store } from "@augmentcode/ag-redux-toolkit/svelte-store"; export function createItemReadable(store: Store, itemId: string) { return selectItem.withStore(store)(itemId); } ``` ### 7. ❌ Bad: creating readables after component initialization ```ts // BAD: selector readable calls after events/await need Svelte context at the wrong time. async function onSaveLater(itemId: string) { await queueMicrotaskPromise(); const item$ = selectItem(itemId); item$.subscribe((item) => store.dispatch(saveItem(item))); } async function onSaveLaterSafely(itemId: string) { await queueMicrotaskPromise(); const item = selectItem.select(store.state, itemId); if (item) store.dispatch(saveItem(item)); } ``` ## Pitfalls - `selectFoo()` depends on `getContext()`, so create selector readables during component initialization. Dispatch does not need a context helper; use the configured Store instance. - A selector readable created in a template expression can allocate repeatedly and lose memoization benefits. - `.select(state)` returns a value; `selectFoo()` returns a readable. Mixing them often produces wrong-shape bugs before it crashes. ## Verification cues - Component changes show selector readables captured at top-level initialization and Store dispatch used in handlers. - Tests use `.select(mockState, ...)`, not the readable call form. - Saga tests cover `.effect()` paths or named selector calls rather than inline `select((state) => ...)` lambdas. ## See also - `docs/SELECTORS.md` — examples for each selector call form. - `svelte/selectors/SKILL.md` — selector authoring and composition. - `svelte/component-integration/SKILL.md` — component store/dispatch wiring. - `core/selector-channels/SKILL.md` — selector reads from sagas. - `core/wait-for/SKILL.md` — saga waiting on selector predicates.