@reforgium/statum 2.0.0 → 2.1.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/%40reforgium%2Fstatum.svg)](https://www.npmjs.com/package/@reforgium/statum)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Signals-first state stores and caching utilities for Angular (20+).**
+**Signals-first state stores and caching utilities for Angular (18+).**
 
 `@reforgium/statum` provides a set of **API-oriented stores**, **cache strategies**, and a  
 **serialization layer** for building predictable data flows in Angular applications.
@@ -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
 
 ---
 
@@ -33,9 +35,9 @@ npm install @reforgium/statum
 
 ## Package Structure
 
-- **Cache** — storage strategies for caching
-- **Stores** — reusable state containers over HttpClient
-- **Serializer** — configurable data transformation utility
+- **Cache** - storage strategies for caching
+- **Stores** - reusable state containers over HttpClient
+- **Serializer** - configurable data transformation utility
 
 ---
 
@@ -47,10 +49,10 @@ npm install @reforgium/statum
 
 Available strategies:
 
-- `persist` — browser localStorage
-- `session` — browser sessionStorage
-- `memory` — in-memory storage
-- `lru` — size-limited in-memory cache
+- `persist` - browser localStorage
+- `session` - browser sessionStorage
+- `memory` - in-memory storage
+- `lru` - size-limited in-memory cache
 
 ### StorageInterface
 
@@ -67,7 +69,7 @@ interface StorageInterface<T> {
 }
 ```
 
-Example:
+Example:
 
 ```ts
 import { cacheStrategy } from '@reforgium/statum';
@@ -89,7 +91,7 @@ Transport-level store over HttpClient with cache strategies, deduplication, abor
 
 ### When to use
 
-- CRUD and “resource” endpoints
+- CRUD and "resource" endpoints
 - Centralized debounce/throttle
 - Abort in-flight / delayed requests (latest-wins)
 - Dedupe identical calls to one HTTP request
@@ -97,24 +99,24 @@ Transport-level store over HttpClient with cache strategies, deduplication, abor
 
 ### Signals
 
-| Signal  | Type              | Description         |
-|---------|-------------------|---------------------|
-| value   | `Signal<T         | null>`              | Last successful value |
-| status  | `'idle'           | 'loading'           | 'success' | 'error' | 'stale'` | Resource status |
-| error   | `Signal<unknown   | null>`              | Last error |
-| loading | `Signal<boolean>` | Request in progress |
+| Signal  | Type                      | Description             |
+|---------|---------------------------|-------------------------|
+| value   | `Signal<T \| null>`       | Last successful value   |
+| status  | `Signal<ResourceStatus>`  | Resource status         |
+| error   | `Signal<unknown \| null>` | Last error              |
+| loading | `Signal<boolean>`         | Request in progress     |
 
 ### Methods
 
-| Method | Description |
-|------|-------------|
-| get | GET request |
-| post | POST request |
-| put | PUT request |
-| patch | PATCH request |
-| delete | DELETE request |
-| abort | Abort a specific request |
-| abortAll | Abort all requests |
+| Method   | Description              |
+|----------|--------------------------|
+| get      | GET request              |
+| post     | POST request             |
+| put      | PUT request              |
+| patch    | PATCH request            |
+| delete   | DELETE request           |
+| abort    | Abort a specific request |
+| abortAll | Abort all requests       |
 
 Example:
 
@@ -128,17 +130,58 @@ const userStore = new ResourceStore<User>(
   { baseUrl: '/api', ttlMs: 60_000 }
 );
 
-const user = await userStore.get(
-  { params: { id: '42' }, query: {} },
-  { dedupe: true }
-);
-```
-
----
-
-## PaginatedDataStore
-
-Lightweight store for server-side pagination with sorting, filtering and page cache.
+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.
 
 ### When to use
 
@@ -149,16 +192,16 @@ Lightweight store for server-side pagination with sorting, filtering and page ca
 
 ### State
 
-| Field / Signal | Type                      | Description                     |
-|----------------|---------------------------|---------------------------------|
-| items          | `WritableSignal<T[]>`     | Current page items              |
-| cached         | `WritableSignal<T[]>`     | Flattened cache of cached pages |
-| loading        | `WritableSignal<boolean>` | Loading indicator               |
-| page           | `number`                  | Current page (0-based)          |
-| pageSize       | `number`                  | Page size                       |
-| totalElements  | `number`                  | Total items on server           |
-| filters        | `Partial<F>`              | Active filters                  |
-| sort           | `string \| undefined`     | Sort as `"field,asc             |
+| Field / Signal | Type                      | Description                            |
+|----------------|---------------------------|----------------------------------------|
+| items          | `WritableSignal<T[]>`     | Current page items                     |
+| cached         | `WritableSignal<T[]>`     | Flattened cache of cached pages        |
+| loading        | `WritableSignal<boolean>` | Loading indicator                      |
+| page           | `number`                  | Current page (0-based)                 |
+| pageSize       | `number`                  | Page size                              |
+| totalElements  | `number`                  | Total items on server                  |
+| filters        | `Partial<F>`              | Active filters                         |
+| sort           | `string \| undefined`     | Sort as `"field,asc"` / `"field,desc"` |
 
 ### Methods
 
@@ -208,8 +251,8 @@ Helper for dictionaries/options (select/autocomplete) on top of PaginatedDataSto
 ### Key behavior
 
 - Two modes:
-  - `fixed: true` — first load fills local cache; search happens locally
-  - `fixed: false` — search goes to server (passes filter `name`)
+  - `fixed: true` - first load fills local cache; search happens locally
+  - `fixed: false` - search goes to server (passes filter `name`)
 - Local cache merges without duplicates and is size-limited
 
 ### Public API
@@ -233,17 +276,17 @@ Methods:
 
 Config:
 
-| Option        | Type                                          | Default    | Description                                 |
-|---------------|-----------------------------------------------|------------|---------------------------------------------|
-| labelKey      | `string`                                      | `'label'`  | Property name to use as option label        |
-| valueKey      | `string`                                      | `'value'`  | Property name to use as option value        |
-| fixed         | `boolean`                                     | `false`    | Use local search instead of server requests |
-| method        | `'GET' \| 'POST'`                             | `'GET'`    | HTTP method for requests                    |
-| cacheKey      | `string \| null`                              | `null`     | Storage key for persisting cache            |
-| debounceTime  | `number`                                      | `200`      | Debounce time for search requests           |
-| pageSize      | `number`                                      | `50`       | Page size for server requests               |
-| cacheLimit    | `number`                                      | `1000`     | Maximum items in local cache                |
-| cacheStrategy | `'persist' \| 'session' \| 'memory' \| 'lru'` | `'memory'` | Cache storage strategy                      |
+| Option         | Type                                 | Default     | Description                                 |
+|----------------|--------------------------------------|-------------|---------------------------------------------|
+| labelKey       | `string`                             | `'name'`    | Property name to use as option label        |
+| valueKey       | `string`                             | `'code'`    | Property name to use as option value        |
+| fixed          | `boolean`                            | `true`      | Use local search instead of server requests |
+| method         | `'GET' \| 'POST'`                    | `'POST'`    | HTTP method for requests                    |
+| debounceTime   | `number`                             | `0`         | Debounce time for search requests           |
+| maxOptionsSize | `number`                             | `undefined` | Maximum items exposed in `options`          |
+| cacheStrategy  | `'persist' \| 'session' \| 'memory'` | `'persist'` | Cache storage strategy                      |
+| keyPrefix      | `string`                             | `'re'`      | Prefix for storage keys                     |
+| presetFilters  | `Record<string, string>`             | `{}`        | Filters merged into each request            |
 
 Example:
 
@@ -259,16 +302,38 @@ 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
 
-Utility for serialization/deserialization between layers (UI ↔ API, objects ↔ query string).
+Utility for serialization/deserialization between layers (UI -> API, objects -> query string).
 
 Core API: