@reforgium/statum 2.0.1 → 2.1.0

package/README.md

@@ -12,14 +12,16 @@ Designed for **application state**, not abstract reducers.
 
 ---
 
-## Features
-
-- Signals-first API (`signal()` everywhere)
-- API-driven stores (resource / paginated / dictionaries)
-- Built-in cache strategies (TTL, prefix grouping)
-- Deterministic request lifecycle: loading / error / data
-- Optional transport-level: dedupe, debounce/throttle, abort
-- Explicit serialization / deserialization boundary
+## Features
+
+- 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
 
 ---
 
@@ -67,7 +69,7 @@ interface StorageInterface<T> {
 }
 ```
 
-Example:
+Example:
 
 ```ts
 import { cacheStrategy } from '@reforgium/statum';
@@ -128,15 +130,56 @@ const userStore = new ResourceStore<User>(
   { baseUrl: '/api', ttlMs: 60_000 }
 );
 
-const user = await userStore.get(
-  { params: { id: '42' }, query: {} },
-  { dedupe: true }
-);
-```
-
----
-
-## PaginatedDataStore
+const user = await userStore.get(
+  { params: { id: '42' }, query: {} },
+  { dedupe: true }
+);
+```
+
+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
 
 Lightweight store for server-side pagination with sorting, filtering, and page cache.
 
@@ -259,12 +302,34 @@ const dict = new DictStore<Country>('api/dictionaries/countries', 'countries', {
 });
 
 dict.search('');      // initial fill
-dict.search('kir');   // local search over cache
-```
-
----
-
-## Serializer
+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