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.

265 lines (214 loc) • 8.18 kB
--- name: core/boolean-preference description: >- createBooleanPreference({ sliceName, field, setActionName, toggleActionName }) emits a setAction (payload [value: boolean]) and a zero-argument toggleAction plus a .register(builder) helper that chains both handlers onto a createReducer builder. The field parameter is constrained to keys whose value type is boolean. Use it instead of hand-writing setX / toggleX pairs. Public API: @augmentcode/ag-redux-toolkit/utils/store/boolean-preference; related guidance: ../SKILL.md §11. type: sub-skill library: ag-redux-toolkit requires: - core - core/reducers sources: - "@augmentcode/ag-redux-toolkit/utils/store/boolean-preference" - ../SKILL.md triggers: - boolean preference - toggle action - setAction toggleAction - register builder --- # Boolean Preference — `createBooleanPreference` > Helper for boolean preference fields. Emits a consistent set/toggle action > pair and wires both reducer cases via `.register(builder)`. Replaces > hand-rolled `setX` / `toggleX` boilerplate and keeps the two actions in > lock-step so tests don't have to cover drift. ## 1. API From `@augmentcode/ag-redux-toolkit/utils/store/boolean-preference`: ```typescript type BooleanFieldKey<S> = { [K in keyof S]-?: S[K] extends boolean ? K : never; }[keyof S] & string; type CreateBooleanPreferenceOptions< S, Field extends BooleanFieldKey<S> = BooleanFieldKey<S>, > = { sliceName: string; field: Field; setActionName: string; toggleActionName: string; }; export function createBooleanPreference< S, Field extends BooleanFieldKey<S> = BooleanFieldKey<S>, >(options: CreateBooleanPreferenceOptions<S, Field>): { setAction: StoreActionCreator<[value: boolean]>; toggleAction: StoreActionCreator<[]>; register(builder: BooleanPreferenceReducerBuilder<S>): BooleanPreferenceReducerBuilder<S>; }; ``` - `field` is constrained at the type level to keys whose value type is `boolean`. TypeScript refuses any field whose value isn't strictly `boolean`. - `setAction` has type `(value: boolean) => StoreAction<[boolean]>`. Dispatched payload is the tuple `[value]`. - `toggleAction` takes no args and flips the current value. - Both action **types** are namespaced: `` `${sliceName}/${setActionName}` `` and `` `${sliceName}/${toggleActionName}` ``. The generated handlers produce: ```typescript // setAction handler (state, { payload: [value] }) => ({ ...state, [field]: value }); // toggleAction handler (state) => ({ ...state, [field]: !state[field] }); ``` Neither handler short-circuits on identity — dispatching `setAction(true)` when the field is already `true` still produces a new `state` reference. ## 2. Setup — minimum working slice ```typescript // prefs-types.ts export type PrefsState = { spellcheckEnabled: boolean; darkMode: boolean; lastSavedAt: number; }; ``` ```typescript // prefs-slice.ts import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer"; import { createBooleanPreference } from "@augmentcode/ag-redux-toolkit/utils/store/boolean-preference"; import type { PrefsState } from "./prefs-types"; const initialState: PrefsState = { spellcheckEnabled: true, darkMode: false, lastSavedAt: 0, }; const spellcheck = createBooleanPreference<PrefsState>({ sliceName: "prefs", field: "spellcheckEnabled", setActionName: "setSpellcheck", toggleActionName: "toggleSpellcheck", }); const darkMode = createBooleanPreference<PrefsState>({ sliceName: "prefs", field: "darkMode", setActionName: "setDarkMode", toggleActionName: "toggleDarkMode", }); // Export the action creators under the names callers will use. export const setSpellcheck = spellcheck.setAction; export const toggleSpellcheck = spellcheck.toggleAction; export const setDarkMode = darkMode.setAction; export const toggleDarkMode = darkMode.toggleAction; // Chain .register() on the reducer builder — both cases are added. export const prefsReducer = darkMode.register( spellcheck.register( createReducer<PrefsState>(initialState) // ... other .with() cases, e.g. .with(savedAt, ...) ) ).build(); ``` Dispatch like any other action: ```typescript dispatch(setSpellcheck(false)); dispatch(toggleDarkMode()); ``` ## 3. Core patterns ### 3.1 Destructuring export If you only need the two actions, destructure inline: ```typescript const prefs = createBooleanPreference<PrefsState>({ sliceName: "prefs", field: "spellcheckEnabled", setActionName: "setSpellcheck", toggleActionName: "toggleSpellcheck", }); export const { setAction: setSpellcheck, toggleAction: toggleSpellcheck } = prefs; export const prefsReducer = prefs.register(createReducer<PrefsState>(initialState)).build(); ``` ### 3.2 Chaining multiple preferences Each `.register(builder)` returns the same builder with two cases added, so you can chain any number of preferences: ```typescript export const prefsReducer = a.register(b.register(c.register( createReducer<PrefsState>(initialState).with(resetAll, () => initialState) ))).build(); ``` `.register` preserves the `initialState` field on the returned builder so `createReducer` / tests can access it via `reducer.initialState`. ### 3.3 Persistence saga Pair with an app-local helper following `core/local-storage` to persist the flag: ```typescript function* persistSpellcheck() { yield* takeEvery([setSpellcheck, toggleSpellcheck], function* () { const current = yield* selectSpellcheck.effect(); yield* call(setLocalStorageItem, "prefs:spellcheck", String(current)); }); } ``` ## 4. Common Mistakes ### Writing `setX` and `toggleX` by hand **Mechanism:** hand-rolled pairs drift — `toggle` may end up using `!state.field` while `set` uses the payload, and tests have to cover both independently. The helper makes them consistent and namespaces the action types automatically. ```typescript // ❌ WRONG export const setSpellcheck = createAction<[boolean]>("prefs/setSpellcheck"); export const toggleSpellcheck = createAction("prefs/toggleSpellcheck"); // two hand-rolled reducer cases... // ✅ CORRECT const spellcheck = createBooleanPreference<PrefsState>({ sliceName: "prefs", field: "spellcheckEnabled", setActionName: "setSpellcheck", toggleActionName: "toggleSpellcheck", }); export const { setAction: setSpellcheck, toggleAction: toggleSpellcheck } = spellcheck; export const prefsReducer = spellcheck.register(createReducer<PrefsState>(initialState)); ``` *Source: `../SKILL.md §11`.* ### Forgetting to chain `.register` on the reducer builder **Mechanism:** the action creators exist but no reducer case handles them; dispatch becomes a silent no-op and the preference never changes. ```typescript // ❌ WRONG — no .register call export const prefsReducer = createReducer<PrefsState>(initialState) .with(otherAction, ...); // ✅ CORRECT export const prefsReducer = spellcheck.register( createReducer<PrefsState>(initialState).with(otherAction, ...) ); ``` *Source: `../SKILL.md §11`.* ### Pointing `field` at a non-boolean key **Mechanism:** TypeScript refuses this at compile time because `field` is constrained to `BooleanFieldKey<S>`, but agents sometimes widen the type with `as any` or omit the generic. The runtime handler still writes a boolean into a non-boolean field, corrupting state. ```typescript // ❌ WRONG — `lastSavedAt` is a number createBooleanPreference<PrefsState>({ sliceName: "prefs", field: "lastSavedAt" as any, setActionName: "setSavedAt", toggleActionName: "toggleSavedAt", }); // ✅ CORRECT — pick a real boolean field createBooleanPreference<PrefsState>({ sliceName: "prefs", field: "darkMode", setActionName: "setDarkMode", toggleActionName: "toggleDarkMode", }); ``` *Public API: `@augmentcode/ag-redux-toolkit/utils/store/boolean-preference` (`BooleanFieldKey<S>` constraint).* ## 5. See also - `core/reducers` — `createReducer` builder and the `same-reference on no-op` rule. - `core/actions` — `createAction<[Params]>` tuple payloads. - `core/local-storage` — persistence saga for preference fields.