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.

258 lines (202 loc) • 8.26 kB
--- name: core/domain-scoped-state description: >- State keyed by a domain id (workspace, project, tenant). State shape is { byDomainId: Record<string, T> }. createDomainScopedHelpers(emptyState) returns getDomainState, setDomainState, and clearDomainState — immutable helpers that read with an emptyState fallback, write per-domain entries, and drop domains (returning the same reference when the id was absent). Public API: @augmentcode/ag-redux-toolkit/utils/store/domain-scoped; related guidance: ../SKILL.md §10. type: sub-skill library: ag-redux-toolkit requires: - core - core/reducers sources: - "@augmentcode/ag-redux-toolkit/utils/store/domain-scoped" - ../SKILL.md triggers: - domain-scoped state - scoped helpers - byDomainId shape - workspace state --- # Domain-Scoped State — `createDomainScopedHelpers` > State keyed by a domain id (e.g. workspace id, project id, tenant id). All > three returned helpers are immutable: reads fall through to `emptyState`, > writes produce a new state with a new `byDomainId`, and `clearDomainState` > returns the same reference when the id was already absent. ## 1. Shape From `@augmentcode/ag-redux-toolkit/utils/store/domain-scoped`: ```typescript type DomainScopedState<T> = { byDomainId: Record<string, T>; }; export function createDomainScopedHelpers<T>(emptyState: T) { const getDomainState = <S extends DomainScopedState<T>>( state: S, domainId: string ): T => state.byDomainId[domainId] ?? emptyState; const setDomainState = <S extends DomainScopedState<T>>( state: S, domainId: string, domainState: T ): S => ({ ...state, byDomainId: { ...state.byDomainId, [domainId]: domainState }, }); const clearDomainState = <S extends DomainScopedState<T>>( state: S, domainId: string ): S => { if (!(domainId in state.byDomainId)) return state; const { [domainId]: _removed, ...byDomainId } = state.byDomainId; return { ...state, byDomainId }; }; return { getDomainState, setDomainState, clearDomainState }; } ``` Key guarantees: - `getDomainState` returns `emptyState` (not `undefined`) for unknown ids. - `setDomainState` always produces a new `state` and a new `byDomainId`. - `clearDomainState` returns the **same** `state` reference when the id was absent, so selectors do not re-emit on no-op clears. - The state type is constrained so `state.byDomainId` is typed as `Record<string, T>`. ## 2. Setup — minimum working slice ```typescript // workspace-items-types.ts import type { Collection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; export type WorkspaceItemsState = { items: Collection<Item, "id">; loadedAt: number; }; export type State = { byDomainId: Record<string, WorkspaceItemsState>; }; ``` ```typescript // workspace-items-slice.ts import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer"; import { createCollection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; import { createDomainScopedHelpers } from "@augmentcode/ag-redux-toolkit/utils/store/domain-scoped"; import type { State, WorkspaceItemsState, Item } from "./workspace-items-types"; const emptyState: WorkspaceItemsState = { items: createCollection<Item, "id">("id"), loadedAt: 0, }; const { getDomainState, setDomainState, clearDomainState } = createDomainScopedHelpers(emptyState); const initialState: State = { byDomainId: {} }; export const setItems = createAction<[id: string, items: Item[]]>("workspaceItems/setItems"); export const clearDomain = createAction<[id: string]>("workspaceItems/clearDomain"); export const workspaceItemsReducer = createReducer<State>(initialState) .with(setItems, (state, { payload: [id, items] }) => setDomainState(state, id, { ...getDomainState(state, id), items: createCollection<Item, "id">("id", items), loadedAt: Date.now ? 0 : 0, // (store a timestamp you dispatch in, not Date.now here) }) ) .with(clearDomain, (state, { payload: [id] }) => clearDomainState(state, id)) .build(); ``` Notes: - Pass the domain id as the **first** tuple element so saga code can key subscriptions by it. - Use `getDomainState(state, id)` inside reducer handlers to read the current per-domain slice safely (falls back to `emptyState` for unknown ids). - `clearDomainState` is the right tool for logout / workspace-change cleanup. ## 3. Core patterns ### 3.1 Reading the current-domain slice in a selector ```typescript // workspace-items-selectors.ts import { store } from "$lib/store/store"; import { getItems } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; import { selectCurrentWorkspaceId } from "../workspaces/workspaces-selectors"; export const selectWorkspaceItems = store.createSelector((state) => { const id = selectCurrentWorkspaceId.select(state); return id ? state.workspaceItems.byDomainId[id]?.items : undefined; }); // Array form for templates export const selectWorkspaceItemList = store.createSelector((state) => { const items = selectWorkspaceItems.select(state); return items ? getItems(items) : []; }); ``` ### 3.2 Updating inside an existing per-domain slice Combine `getDomainState` + spread + `setDomainState`: ```typescript .with(addItem, (state, { payload: [id, item] }) => { const current = getDomainState(state, id); return setDomainState(state, id, { ...current, items: addItemCollection(current.items, item), }); }) ``` ### 3.3 Clearing a domain on logout / workspace-change ```typescript .with(leftWorkspace, (state, { payload: [id] }) => clearDomainState(state, id) ); ``` Because `clearDomainState` returns the same reference if the id was absent, selectors keyed on unrelated domains won't re-emit. ## 4. Common Mistakes ### Hand-rolling domain-keyed state with nested setters **Mechanism:** custom nested updates forget the `emptyState` fallback; reading an unknown domain id returns `undefined` instead of the empty state and downstream code crashes on property access. ```typescript // ❌ WRONG .with(setItems, (state, { payload: [id, items] }) => ({ ...state, byId: { ...state.byId, [id]: { ...state.byId[id], items } }, })) // ✅ CORRECT .with(setItems, (state, { payload: [id, items] }) => setDomainState(state, id, { ...getDomainState(state, id), items }) ) ``` *Source: `../SKILL.md §10`.* ### Storing a non-serializable `emptyState` **Mechanism:** `emptyState` is read for every new domain id; any `Date`, `Map`, `Set`, or class instance inside will break the serializable state contract once it's written back into the state tree. ```typescript // ❌ WRONG const emptyState = { items: new Map(), createdAt: new Date() }; // ✅ CORRECT const emptyState = { items: createCollection<Item, "id">("id"), createdAt: 0, }; ``` *Source: `../SKILL.md §10, §12`. See also `core/state-serialization`.* ### Using a different key than `byDomainId` **Mechanism:** the helpers are typed against `DomainScopedState<T>`, i.e. `{ byDomainId: Record<string, T> }`. Renaming to `byId` or `byWorkspaceId` type-errors on the helpers and forces consumers back to hand-rolled setters. ```typescript // ❌ WRONG type State = { byWorkspaceId: Record<string, WorkspaceItemsState> }; // ✅ CORRECT type State = { byDomainId: Record<string, WorkspaceItemsState> }; ``` *Public API: `@augmentcode/ag-redux-toolkit/utils/store/domain-scoped` (`DomainScopedState<T>` shape).* ## 5. When to use - State must be partitioned by a stable id (workspace / project / tenant / session). - You want automatic cleanup on domain removal (`clearDomainState`). - You want reads to gracefully fall back to a known empty shape. If every consumer shares a single domain (no multi-tenant / multi-workspace concept), a plain slice is simpler — reach for `createDomainScopedHelpers` only when the domain id is part of the key. ## 6. See also - `core/reducers` — pure-update rules, `createReducer` builder. - `core/state-serialization` — why `emptyState` must be structured-cloneable. - `core/collections` — the usual shape of per-domain data.