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.

226 lines (156 loc) • 6.57 kB
# Collections Guide > **Normalized data structures for managing entities by ID with O(1) lookups.** --- ## Table of Contents 1. [What is a Collection?](#what-is-a-collection) 2. [Creating Collections](#creating-collections) 3. [CRUD Operations](#crud-operations) 4. [Reference Counting](#reference-counting) 5. [Querying Collections](#querying-collections) 6. [When to Use Collections](#when-to-use-collections) 7. [Best Practices](#best-practices) --- ## What is a Collection? A **Collection** is a normalized data structure that stores entities by ID. It provides O(1) lookups while maintaining insertion order. ```typescript type Collection<ITEM extends object, K extends string & keyof ITEM> = { idField: K; // Name of the ID field ids: Array<ITEM[K]>; // Ordered list of IDs map: Record<ITEM[K] & string, ITEM>; // ID → Item lookup refsCount: Record<ITEM[K], number>; // Reference counting }; ``` All Collection operations are **immutable** — they return new Collection objects, never mutate the original. **Public imports:** Use the explicit utility leaf `@augmentcode/ag-redux-toolkit/utils/collections/collection-utils`. --- ## Creating Collections ```typescript import { createCollection } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; type Todo = { id: string; title: string; completed: boolean }; // Empty collection const todos = createCollection<Todo, "id">("id"); // Collection with initial items const todos = createCollection<Todo, "id">("id", [ { id: "1", title: "Buy milk", completed: false }, { id: "2", title: "Write docs", completed: true }, ]); ``` ## CRUD Operations All operations return a **new** Collection. The original is never modified. ### Adding Items ```typescript import { addItem, addItems, addItemAt, upsertItem } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; // Add a single item (no-op if ID already exists) const updated = addItem(collection, { id: "3", title: "New todo", completed: false }); // Add multiple items at once const updated = addItems(collection, [item1, item2, item3]); // Add at a specific index const updated = addItemAt(collection, 0, newItem); // Insert at beginning // Add or update (upsert) const updated = upsertItem(collection, item); // Adds if new, merges if exists ``` ### Updating Items ```typescript import { updateItem, replaceItem } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; // Merge partial updates into an existing item const updated = updateItem(collection, { id: "1", completed: true }); // Original item fields are preserved; only specified fields are overwritten // Replace an item entirely (can change the ID) const updated = replaceItem(collection, "old-id", newItem); ``` `updateItem` uses shallow equality — if the merged result equals the original, the same collection reference is returned (no unnecessary re-renders). ### Removing Items ```typescript import { removeItem } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; // Remove by ID const updated = removeItem(collection, "1"); // Removes from ids, map, and refsCount ``` --- ## Reference Counting Collections include a `refsCount` map for tracking how many places reference an item. This is useful when multiple features share entities and you want to clean up only when no one references an item anymore. ```typescript import { addItemAndCountRef, increaseRefsCount, decreaseRefsCount, getRefsCount, } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; // Add an item and set its ref count to 1 const updated = addItemAndCountRef(collection, newItem); // Increment ref count for an existing item const updated = increaseRefsCount(collection, itemId); // Decrement ref count — removes the item when count reaches 0 const updated = decreaseRefsCount(collection, itemId); // Query the current ref count const count = getRefsCount(collection, itemId); ``` ### How `decreaseRefsCount` Works When the reference count drops to 0 (or below), the item is **automatically removed** from the collection (both `ids` and `map`). This enables automatic cleanup patterns: ```typescript // In a reducer: .with(removeContextItem, (state, { payload: [itemId] }) => ({ ...state, collection: decreaseRefsCount(state.collection, itemId), })) ``` --- ## Querying Collections ```typescript import { getItem, getItems, findItem, filterItems, filterCollection, } from "@augmentcode/ag-redux-toolkit/utils/collections/collection-utils"; // Get a single item by ID — O(1) const item = getItem(collection, "1"); // Get all items as an ordered array const items = getItems(collection); // Find first item matching a predicate const found = findItem(collection, (item) => item.completed); // Filter items (returns array) const completed = filterItems(collection, (item): item is Todo => item.completed); // Filter collection (returns new Collection, preserves structure) const completedCollection = filterCollection(collection, (item): item is Todo => item.completed); ``` --- ## When to Use Collections ### ✅ Use Collections When - Entities have a unique ID field - You need fast lookup by ID (O(1) vs O(n) array scan) - You need to maintain insertion order - Multiple parts of the app reference the same entities - You want reference counting for cleanup ### ❌ Use Plain Objects/Arrays When - Data is a simple list without unique IDs - Data is small and never looked up by ID - Data is write-once, read-sequentially --- ## Best Practices 1. **Always use `getItem()` instead of `.find()`** — O(1) vs O(n): ```typescript // ✅ GOOD const item = getItem(collection, id); // ❌ BAD const item = getItems(collection).find((i) => i.id === id); ``` 2. **Use separate maps for derived state** — Don't add flags to items: ```typescript // ✅ GOOD: Separate maps type State = { items: Collection<Item, "id">; pinnedItems: Record<string, boolean>; }; // ❌ BAD: Flags on items type ItemWithFlags = Item & { isPinned: boolean }; ``` 3. **Access items through selectors** — Don't import collection utils in components: ```typescript // In selectors file export const selectTodo = store.createSelector((state, id: string) => { return getItem(selectTodosCollection.select(state), id); }); ``` 4. **Use `upsertItem` when you don't know if the item exists** — It handles both add and update cases.