@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.
150 lines (114 loc) • 5.7 kB
Markdown
name: core/state-serialization
description: >-
Redux state must be structured-cloneable. Allowed: string, number, boolean,
null, undefined, plain objects, arrays of primitives. Forbidden: Date, Map,
Set, WeakMap, WeakSet, RegExp, Promise, Function, class instances, Error,
Symbol. Alternatives: Date → number (ms), Map → Record<string, T>, Set →
string[] or Record<string, true>, RegExp → string, Error → { message,
stack }.
type: sub-skill
requires:
- core
triggers:
- serializable state
- structured clone
- no date in state
# State Serialization
> Operational checklist for reducer state shape. Full rationale and examples: `docs/REDUCERS.md` → State Serialization Rules. Reducer API: `@augmentcode/ag-redux-toolkit/utils/store/create-reducer`; related guidance: `../SKILL.md` §12.
## Use when
- Adding or changing reducer state, initial state, persisted state, or action payloads that become state.
- Reviewing helpers that introduce dates, errors, maps/sets, class instances, functions, promises, or browser APIs.
## Do
- Keep Redux state JSON-shaped: primitives, arrays, and plain objects.
- Store timestamps as `number` milliseconds or ISO strings; generate them in action creators or sagas, not reducers.
- Store entity sets/maps as `Record<string, T>`, `string[]`, or `Collection<T, K>`.
- Store errors as plain data such as `{ message: string; stack?: string }`.
- Add or update serialization tests for new reducer state: stringify/parse should round-trip the state.
## Don't
- Do not store `Date`, `Map`, `Set`, `WeakMap`, `WeakSet`, `RegExp`, `Promise`, `Function`, class instances, `Error`, or `Symbol` values.
- Do not call `Date.now()`, `Math.random()`, or ID generators inside reducer handlers; pass generated values in the action payload.
- Do not hide non-serializable objects inside collections or nested state fields.
## Examples
### Plain JSON-shaped state
```ts
type Todo = { id: string; title: string; completed: boolean };
type TodosState = {
ids: string[];
byId: Record<string, Todo>;
loading: boolean;
selectedId: string | null;
};
```
### Store timestamps as numbers or ISO strings
```ts
import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action";
import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer";
const markSynced = createAction("todos/markSynced", (syncedAtMs: number, syncedAtIso: string) => ({ syncedAtMs, syncedAtIso }));
export const reducer = createReducer({ syncedAtMs: 0, syncedAtIso: "" }).with(markSynced, (state, { payload }) => ({
...state,
syncedAtMs: payload.syncedAtMs,
syncedAtIso: payload.syncedAtIso,
}));
```
### Serialize errors before storing them
```ts
type SerializableError = { message: string; stack?: string };
function toSerializableError(error: unknown): SerializableError {
if (error instanceof Error) return { message: error.message, stack: error.stack };
return { message: String(error) };
}
const failedState = { error: toSerializableError(new Error("network failed")) };
```
### Use records or collections instead of Map and Set
```ts
import { type Collection, createCollection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils";
type Todo = { id: string; title: string };
type TodosState = {
todos: Collection<Todo, "id">;
selectedById: Record<string, true>;
};
const initialState: TodosState = { todos: createCollection<Todo, "id">("id"), selectedById: {} };
```
### JSON round-trip regression test
```ts
import { describe, expect, it } from "vitest";
const todosReducer = {
initialState: { ids: [] as string[], byId: {} as Record<string, { id: string; title: string }> },
};
describe("todos state serialization", () => {
it("round-trips through JSON", () => {
const state = todosReducer.initialState;
expect(JSON.parse(JSON.stringify(state))).toEqual(state);
});
});
```
### ❌ Bad: non-serializable state and reducer-created values
```ts
import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action";
import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer";
// BAD: Date, Map, Set, Promise, class instances, and Error do not belong in Redux state.
type Todo = { id: string; title: string };
type TodosState = { updatedAt: Date; byId: Map<string, Todo>; selectedIds: Set<string>; error?: Error };
const initialState: TodosState = { updatedAt: new Date(0), byId: new Map(), selectedIds: new Set() };
const markTouched = createAction("todos/markTouched");
export const reducer = createReducer<TodosState>(initialState).with(markTouched, (state) => ({
...state,
updatedAt: new Date(),
error: new Error("changed"),
}));
```
## Implementation cues
- If a value needs behavior, store its data in Redux and run behavior in a saga/service.
- If a value is derived from state, keep it out of state and expose it through selectors.
- If a collection-like field grows beyond a simple primitive list, prefer `Collection<T, K>` and the collection helpers.
## Verification cues
- Reducer tests cover initial state and changed paths with `JSON.stringify`/`JSON.parse` round-trips.
- Search new state types for forbidden constructors and browser objects before handoff.
- Run the repository's skill/example validation when documentation examples changed.
## See also
- `docs/REDUCERS.md` — human reference for serialization rules and examples.
- `core/reducers/SKILL.md` — reducer purity and same-reference no-op behavior.
- `core/collections/SKILL.md` — serializable normalized entity storage.
- `core/state-integrity/SKILL.md` — derived values and canonical ownership.