@reforgium/statum 2.0.1 → 2.1.1

package/README.md

@@ -16,9 +16,11 @@ Designed for **application state**, not abstract reducers.
 
 - Signals-first API (`signal()` everywhere)
 - API-driven stores (resource / paginated / dictionaries)
+- Normalized entity store (`EntityStore`)
 - Built-in cache strategies (TTL, prefix grouping)
 - Deterministic request lifecycle: loading / error / data
 - Optional transport-level: dedupe, debounce/throttle, abort
+- Unified retry and trace hooks in `ResourceStore`
 - Explicit serialization / deserialization boundary
 
 ---
@@ -134,6 +136,47 @@ const user = await userStore.get(
 );
 ```
 
+Retry + trace example:
+
+```ts
+import { ResourceStore } from '@reforgium/statum';
+
+const store = new ResourceStore<{ id: number; name: string }>(
+  { GET: '/users/:id' },
+  {
+    baseUrl: '/api',
+    retry: { attempts: 2, delayMs: 150, backoff: 'exponential' },
+    onTrace: (event) => console.debug('[resource-trace]', event),
+  }
+);
+
+await store.get(
+  { params: { id: '42' } },
+  { retry: { attempts: 1 } } // per-call override
+);
+```
+
+---
+
+## EntityStore
+
+Normalized entities store (`byId` + `ids`) for fast updates and stable list composition.
+
+Example:
+
+```ts
+import { EntityStore } from '@reforgium/statum';
+
+type User = { id: number; name: string };
+
+const entities = new EntityStore<User, 'id'>({ idKey: 'id' });
+
+entities.setAll([{ id: 1, name: 'Neo' }]);
+entities.upsertOne({ id: 2, name: 'Trinity' });
+entities.patchOne(2, { name: 'Trin' });
+entities.removeOne(1);
+```
+
 ---
 
 ## PaginatedDataStore
@@ -264,6 +307,28 @@ dict.search('kir');   // local search over cache
 
 ---
 
+## Composition Patterns
+
+### PaginatedDataStore + EntityStore
+
+```ts
+import { effect } from '@angular/core';
+import { EntityStore, PaginatedDataStore } from '@reforgium/statum';
+
+type User = { id: number; name: string };
+
+const pages = new PaginatedDataStore<User, { search?: string }>('/api/users');
+const entities = new EntityStore<User, 'id'>({ idKey: 'id' });
+
+effect(() => {
+  entities.upsertMany(pages.items());
+});
+```
+
+This keeps page-loading logic in `PaginatedDataStore` and normalized lookup/update logic in `EntityStore`.
+
+---
+
 ## Serializer
 
 ### Serializer