@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.
193 lines (137 loc) • 10.4 kB
Markdown
# ag-redux-toolkit

> Redux + Saga state management with Svelte-readable, React-signal, and Kefir-observable selectors.
## What it is
`ag-redux-toolkit` is a custom package for moving shared state, async workflows, and derived data into explicit, testable Redux + Saga building blocks. It is not the official Redux Toolkit and does not use RTK APIs such as `createSlice`, `configureStore`, or `createAsyncThunk`. It ships three Store variants: `Store` (Svelte readables), `ReactStore` (Preact React signals), and `StreamingStore` (Kefir observables).
## When to use it
- Keep shared application state in one Redux store instead of ad hoc component or script state.
- Put API calls, subscriptions, timers, persistence, and other side effects in sagas instead of components.
- Read derived state through selectors matched to the caller: Svelte readables, Preact React signals, or Kefir streams, plus `.select(state, ...args)` for synchronous reads and `.effect(...args)` for sagas.
- Skip needless recomputation: proxy-based tracking records the exact state paths each selector reads, so unrelated state changes do not invalidate derived values.
- Coalesce selector emissions near frame rate so a store changing every 1ms does not force consumer work every 1ms.
- Model entity-heavy state with normalized collection helpers.
## Installation
```bash
npm install @augmentcode/ag-redux-toolkit redux redux-saga typed-redux-saga fast-equals
```
`svelte@^5` is a peer dependency because the Svelte-readable entrypoint ships in the package; Svelte apps and frameworks normally provide it. `ReactStore` consumers should use it from React apps that can load `@preact/signals-react`. For saga tests, `redux-saga-test-plan` is an optional dev dependency (`npm install -D redux-saga-test-plan`).
## Quick start
All variants take app-owned reducer maps in the constructor, initialize once before use, and start each app saga explicitly with `store.runSaga(sagaFn)`.
### Svelte
Selectors return Svelte `Readable` values; register the init disposer with `onDestroy` and start sagas from `onMount`.
```svelte
<script lang="ts">
import { onDestroy, onMount } from 'svelte';
import { Store } from '@augmentcode/ag-redux-toolkit/svelte-store';
import { counterReducer } from './slices/counter/counter-slice';
import { counterSaga } from './slices/counter/sagas/counter-saga';
const store = new Store(
{ counter: counterReducer },
undefined,
{ throttledSelectorFrequency: 64, sagaMonitor: true }
);
const dispose = store.init();
onDestroy(dispose);
onMount(() => store.runSaga(counterSaga));
</script>
```
### React
Direct selector calls return Preact `ReadonlySignal` values; React components and hooks read plain values with `.useValue(...args)`, throttled the same as direct signal output.
```tsx
import { ReactStore } from '@augmentcode/ag-redux-toolkit/react-store';
import { counterReducer } from './slices/counter/counter-slice';
import { counterSaga } from './slices/counter/sagas/counter-saga';
const reactStore = new ReactStore(
{ counter: counterReducer },
undefined,
{ throttledSelectorFrequency: 64 }
);
const dispose = reactStore.init();
const cancelCounterSaga = reactStore.runSaga(counterSaga);
const selectCount = reactStore.createSelector((state) => state.counter.count);
const countSignal = selectCount();
console.log(countSignal.value);
function CounterLabel() {
const count = selectCount.useValue();
return <span>{count}</span>;
}
cancelCounterSaga();
dispose();
```
### Streaming
For Node, server, worker, CLI, test, and other non-Svelte consumers; direct selector calls return Kefir observables.
```ts
import { StreamingStore } from '@augmentcode/ag-redux-toolkit/streaming-store';
import { counterReducer } from './slices/counter/counter-slice';
import { counterSaga } from './slices/counter/sagas/counter-saga';
const streamStore = new StreamingStore(
{ counter: counterReducer },
undefined,
{ throttledSelectorFrequency: 64 }
);
const dispose = streamStore.init();
const cancelCounterSaga = streamStore.runSaga(counterSaga);
const selectCount = streamStore.createSelector((state) => state.counter.count);
const countSubscription = selectCount().observe((count) => {
console.log(count);
});
countSubscription.unsubscribe();
cancelCounterSaga();
dispose();
```
## Choosing a Store variant
| Variant | Import path | Direct selector returns | Component reads | Non-component reads |
| --- | --- | --- | --- | --- |
| Store | @augmentcode/ag-redux-toolkit/svelte-store | Svelte Readable | $selector / subscribe(...) | .select(state, ...args) |
| ReactStore | @augmentcode/ag-redux-toolkit/react-store | Preact ReadonlySignal | .useValue(...args) | signal .value or .select(state, ...args) |
| StreamingStore | @augmentcode/ag-redux-toolkit/streaming-store | Kefir Observable | — | .observe(...) or .select(state, ...args) |
All three constructors share the signature `new <Class>(reducersMap?, middleware?, options?)`; pass `undefined` for middleware when you only need options. `.useValue(...args)` is React-only; `.effect(...args)` creates a typed-redux-saga select effect for use inside sagas only.
## Public import paths
Use the public subpackage entrypoints in application code. There is no package root barrel and no `@augmentcode/ag-redux-toolkit/utils` barrel; import from the explicit subpath that owns the API.
| Subpackage | Use for |
| --- | --- |
| @augmentcode/ag-redux-toolkit/svelte-store | Canonical Svelte-readable Store class. |
| @augmentcode/ag-redux-toolkit/streaming-store | StreamingStore; its createSelector(...) results return Kefir observables. |
| @augmentcode/ag-redux-toolkit/react-store | ReactStore; its selectors return Preact React signals and expose .useValue(...args). |
| @augmentcode/ag-redux-toolkit/saga | Saga authoring helpers, selector-channel effects, retry/timeout utilities, and streaming helpers. |
| @augmentcode/ag-redux-toolkit/types | Public TypeScript types. |
| @augmentcode/ag-redux-toolkit/components-svelte/use-init-store, /use-run-saga | Optional Svelte lifecycle helper leaf imports; there is no components-svelte barrel. |
| @augmentcode/ag-redux-toolkit/utils/collections/collection-utils | Collection utility leaf import. |
| @augmentcode/ag-redux-toolkit/utils/store/create-action, /create-reducer, /boolean-preference, /domain-scoped | The only package-level store utility leaf imports. |
| @augmentcode/ag-redux-toolkit/utils/sagas/<leaf> | Approved saga utility leaves: debounce-saga, retry-with-timeout, wrap-async-generator, selector-channel-effects. |
## Store options
- `throttledSelectorFrequency` — selector emission coalescing FPS for all three variants; defaults to `64`, accepts any finite value in the inclusive `1..256` range.
- `sagaMonitor: true` — enables Store-owned redux-saga monitoring; disabled by default, diagnostics only.
- `traceSelectors: true` — enables selector trace output; disabled by default, diagnostics only.
Names prefixed `@internal_` (such as the `@internal_storeUtility` reducer) and the internal saga manager are package-owned; do not register `@internal_` reducers, start internal sagas, or read those state domains from app code.
## Lifecycle
`store.init(initialState?)` prepares the Redux store, starts the internal saga manager, and returns a disposer (in Svelte, register it with `onDestroy`); it does not auto-start app sagas. `store.runSaga(sagaFn)` starts one saga and returns a cancel function. `store.dispose()` tears down the initialized context and stops saga tasks owned by it. Infer the app state type from the configured store with `StoreInstanceState<typeof store>` from `@augmentcode/ag-redux-toolkit/types` (`StoreState<typeof store>` remains supported).
## CLI and skills
Run the package bin with `npx ag-redux-toolkit help` (or `./node_modules/.bin/ag-redux-toolkit help`) to list commands. Skill installs — `install-skills:react`, `install-skills:svelte`, `install-skills:streaming`, or `install-skills` (alias of `install-skills:all`) — write the selected bundle into `.agents/skills/ag-redux-toolkit/` and record an `installed-skills.yml` manifest there. Run `cleanup-skills` before uninstalling; it removes only manifest-listed files plus the manifest itself. See [docs/INSTALLATION.md](./docs/INSTALLATION.md) for full install, refresh, cleanup, and uninstall behavior.
## ESLint
Import exactly one composed domain root config from `@augmentcode/ag-redux-toolkit/eslint-plugins` per app path: `core` (any JS/TS package), `store` (state/saga packages without UI), `svelte`, `react`, or `streaming`. The former `full`/`recommended` roots and the `@augmentcode/ag-redux-toolkit/eslint-architecture` specifiers are removed. The `validate-architecture` CLI command is also removed; consuming apps get architecture checking through these ESLint root configs.
## Learn more
`docs/` is the human-facing source of truth; `skills/` is concise agent-facing execution guidance that links back to the docs.
- `docs/ARCHITECTURE.md` — store setup, data flow, selector tracking, and saga lifecycle.
- `docs/INSTALLATION.md` — manual Skills installation, cleanup/uninstall behavior, and maintainer validation.
- `docs/SELECTORS.md` — selector creation, memoization, component reads, non-component reads, and saga usage.
- `docs/SAGAS.md` — typed saga patterns for async workflows.
- `docs/COLLECTIONS.md` — normalized entity state helpers.
- `docs/TESTING.md` — reducer, selector, and saga testing strategies.
- `skills/SKILL.md` — root router for choosing Core, Svelte, React, or Streaming skill families.
- `skills/core/` — framework-independent Redux and redux-saga agent guidance.
- `skills/svelte/` — Svelte-specific agent execution guidance, including `skills/svelte/migration/`.
- `skills/react/` — ReactStore and Preact signal selector guidance.
- `skills/streaming/` — StreamingStore and Kefir/observable selector guidance.
- `skills/setup/` — canonical greenfield setup workflow.
## Maintainer validation
From a clean checkout of this repository, run `pnpm install --frozen-lockfile` (`pnpm-lock.yaml` is the only tracked lockfile), then:
```bash
npm run validate:architecture
npm test
npm run build
npm run validate:release
```
See [docs/INSTALLATION.md](./docs/INSTALLATION.md) for what each gate checks and the expected passing output.
## License
MIT