@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
Markdown
---
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.