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.

171 lines (130 loc) • 7.47 kB
--- name: core/collections description: >- Normalized entity storage via Collection<T, K>: createCollection plus addItem, addItems, addItemAt, upsertItem, updateItem, replaceItem, removeItem, filterCollection, getItem, getItems, findItem, filterItems, and reference counting (increaseRefsCount, decreaseRefsCount, getRefsCount, addItemAndCountRef). All operations are immutable and return a new Collection (or the same reference on a no-op). Public API: @augmentcode/ag-redux-toolkit/utils/collections/collection-utils; docs: docs/COLLECTIONS.md. type: sub-skill library: ag-redux-toolkit requires: - core - core/reducers sources: - augmentcode/ag-redux-toolkit:docs/COLLECTIONS.md - "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils" triggers: - create collection - addItem collection - upsert item - reference counting --- # Collections — `Collection<T, K>` > Operational guidance for normalized entity state. Full API reference and examples: `docs/COLLECTIONS.md`. Public API: `@augmentcode/ag-redux-toolkit/utils/collections/collection-utils`. ## Use when - State contains entities with a unique string id and needs O(1) lookup plus stable ordering. - Reducers need immutable add/update/remove/upsert operations. - Multiple features reference shared entities and need reference-count cleanup. ## Shape and imports - A collection is `{ idField, ids, map, refsCount }`; `ids` preserves order and `map` stores id → item. - Import helpers from `@augmentcode/ag-redux-toolkit/utils/collections/collection-utils`. - Use selectors, not components, to read collection contents. ## Do - Initialize with `createCollection<T, K>(idField, items?)`. - Use helpers (`addItem`, `addItems`, `upsertItem`, `updateItem`, `replaceItem`, `removeItem`, `filterCollection`) instead of mutating `.ids`, `.map`, or `.refsCount`. - Preserve parent reducer reference equality when a helper returns the same collection reference. - Use `getItem` for O(1) reads and `getItems` for ordered materialization. - Use `store.createSelector(...)` plus `getItem`/`getItems` for selector-facing reads. ## Reference counting cues - Use `addItemAndCountRef` / `upsertItemAndCountRef` when adding shared entities and incrementing ownership together. - Use `increaseRefsCount` and `decreaseRefsCount` for manual ownership changes. - `decreaseRefsCount` removes the item from `ids`, `map`, and `refsCount` when the count reaches `<= 0`. - `getRefsCount` returns `1` for an existing item with no explicit count and `0` for a missing item. ## Don't - Do not store entities as `Item[]` when id lookup is needed. - Do not store `Map`/`Set` in Redux state; use collections or plain records. - Do not add derived flags to item records when a separate relationship map or selector can represent the view. - Do not call `getItems(collection).find(...)` for id lookup; use `getItem(collection, id)`. - Do not import collection utilities directly into components; expose app reads through selectors. ## Examples ### Serializable initial collection state ```ts import { type Collection, createCollection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; type Todo = { id: string; title: string; completed: boolean }; type TodosState = { todos: Collection<Todo, "id"> }; export const initialState: TodosState = { todos: createCollection<Todo, "id">("id"), }; ``` ### Add, update, upsert, and remove in reducers ```ts import { addItem, createCollection, removeItem, updateItem, upsertItem } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; type Todo = { id: string; title: string; completed: boolean }; const state = { todos: createCollection<Todo, "id">("id") }; const todos = addItem(state.todos, { id: "todo-1", title: "Draft", completed: false }); const renamed = updateItem(todos, { id: "todo-1", title: "Ship docs" }); const synced = upsertItem(renamed, { id: "todo-2", title: "Review", completed: false }); const withoutDraft = removeItem(synced, "todo-1"); const nextState = withoutDraft === state.todos ? state : { ...state, todos: withoutDraft }; ``` ### Reference-count shared entities ```ts import { addItemAndCountRef, createCollection, decreaseRefsCount, getRefsCount } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; type Todo = { id: string; title: string; completed: boolean }; const state = { todos: createCollection<Todo, "id">("id") }; const withOwner = addItemAndCountRef(state.todos, { id: "todo-1", title: "Draft", completed: false }); const ownerCount = getRefsCount(withOwner, "todo-1"); const afterRelease = decreaseRefsCount(withOwner, "todo-1"); ownerCount satisfies number; afterRelease.ids satisfies string[]; ``` ### Collection selectors expose item and ordered-list reads ```ts import { Store } from "@augmentcode/ag-redux-toolkit/svelte-store"; import { type Collection, createCollection, getItem, getItems } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer"; type Todo = { id: string; title: string; completed: boolean }; type TodosState = { todos: Collection<Todo, "id"> }; const initialState: TodosState = { todos: createCollection<Todo, "id">("id") }; const todosReducer = createReducer(initialState); const store = new Store({ todos: todosReducer }); export const selectTodo = store.createSelector((state, id: string) => getItem(state.todos.todos, id)); export const selectTodos = store.createSelector((state) => getItems(state.todos.todos)); ``` ### Plain arrays are fine for tiny ordered facts without id lookup ```ts type BreadcrumbState = { labels: string[]; }; const breadcrumbs: BreadcrumbState = { labels: ["Projects", "Settings"], }; ``` ### ❌ Bad: mutating internals corrupts normalized identity ```ts import { type Collection, createCollection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; import { createAction } from "@augmentcode/ag-redux-toolkit/utils/store/create-action"; import { createReducer } from "@augmentcode/ag-redux-toolkit/utils/store/create-reducer"; type Todo = { id: string; title: string; completed: boolean }; type TodosState = { todos: Collection<Todo, "id"> }; const initialState: TodosState = { todos: createCollection<Todo, "id">("id") }; const renameTodo = createAction("todos/rename", (id: string, title: string) => ({ id, title })); // BAD: direct ids/map writes can create duplicates or dangling ids and bypass helper no-op behavior. export const todosReducer = createReducer(initialState).with(renameTodo, (state, { payload }) => { state.todos.map[payload.id] = { ...state.todos.map[payload.id], title: payload.title }; state.todos.ids.push(payload.id); return state; }); ``` ## Verification cues - Reducer tests cover add/update/remove/upsert branches and no-op same-reference behavior. - Selector tests cover item lookup and list materialization using `.select(mockState, ...)`. - Manual review checks that detailed helper examples remain in `docs/COLLECTIONS.md`; this skill keeps only implementation cues. ## See also - `docs/COLLECTIONS.md` — human reference for helper signatures and examples. - `core/reducers/SKILL.md` — pure immutable reducer updates. - `svelte/selectors/SKILL.md` — collection selector helpers. - `core/state-serialization/SKILL.md` — collections as serializable alternatives to `Map`/`Set`.