@reforgium/statum 1.0.0

package/README.md

@@ -0,0 +1,328 @@
+# @reforgium/statum
+
+[![npm version](https://badge.fury.io/js/%40recrafted%2Finternal.svg)](https://www.npmjs.com/package/@reforgium/internal)
+[![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+).**
+
+`@reforgium/statum` provides a set of **API-oriented stores**, **cache strategies**, and a  
+**serialization layer** for building predictable data flows in Angular applications.
+
+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
+
+---
+
+## Installation
+
+```bash
+npm install @reforgium/statum
+```
+
+---
+
+## Package Structure
+
+- **Cache** — storage strategies for caching
+- **Stores** — reusable state containers over HttpClient
+- **Serializer** — configurable data transformation utility
+
+---
+
+## Cache
+
+### cacheStrategy
+
+`cacheStrategy<T>(kind)` is a factory that returns a cache storage implementing `StorageInterface<T>`
+
+Available strategies:
+
+- `persist` — browser localStorage
+- `session` — browser sessionStorage
+- `memory` — in-memory storage
+- `lru` — size-limited in-memory cache
+
+### StorageInterface
+
+All cache strategies implement the same contract.
+
+```ts
+interface StorageInterface<T> {
+  get(key: string): T | null;
+  set(key: string, value: T): void;
+  remove(key: string): void;
+  clear(): void;
+  get length(): number;
+}
+```
+
+Example:
+
+```ts
+import { cacheStrategy } from '@reforgium/statum';
+
+type User = { id: number; name: string };
+
+const storage = cacheStrategy<User>('persist');
+
+storage.set('user:1', { id: 1, name: 'John' });
+
+const user = storage.get('user:1'); // User | null
+```
+
+---
+
+## ResourceStore
+
+Transport-level store over HttpClient with cache strategies, deduplication, abort, and rate-limiting.
+
+### When to use
+
+- CRUD and “resource” endpoints
+- Centralized debounce/throttle
+- Abort in-flight / delayed requests (latest-wins)
+- Dedupe identical calls to one HTTP request
+- Use as a transport engine for other stores (`promote: false`)
+
+### 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 |
+
+### 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 |
+
+Example:
+
+```ts
+import { ResourceStore } from '@reforgium/statum';
+
+type User = { id: number; name: string };
+
+const userStore = new ResourceStore<User>(
+  { GET: '/users/:id' },
+  { 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.
+
+### When to use
+
+- Server-side pagination
+- Noisy filters (debounce)
+- Tables/grids (PrimeNG `onLazyLoad` and similar)
+- Small local page cache with eviction
+
+### 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|desc"` |
+
+### Methods
+
+| Method         | Description                                       |
+|----------------|---------------------------------------------------|
+| refresh        | Repeat request with current params                |
+| updatePage     | Change page (can use cache)                       |
+| updatePageSize | Change page size (can use cache)                  |
+| updateFilters  | Merge filters, reset cache, go to page 0          |
+| setFilters     | Replace filters, reset cache + sort, go to page 0 |
+| updateQuery    | Map table events to `page`/`sort`                 |
+| updateRoute    | Change endpoint, reset meta/cache                 |
+| updateConfig   | Patch config and apply presets                    |
+| copy           | Copy config/meta from another store               |
+| destroy        | Manual destroying of caches and abort requests    |
+
+Example:
+
+```ts
+import { PaginatedDataStore } from '@reforgium/statum';
+
+type User = { id: number; name: string };
+
+const store = new PaginatedDataStore<User, { search?: string }>('api/users', {
+  method: 'GET',
+  debounceTime: 200,
+});
+
+store.updateFilters({ search: 'neo' });
+store.updatePage(1);
+```
+
+---
+
+## DictStore
+
+Helper for dictionaries/options (select/autocomplete) on top of PaginatedDataStore.
+
+### When to use
+
+- Select options / autocomplete hints
+- Local search over previously loaded values (fixed mode)
+- Cache across sessions in localStorage
+- Need `{ label, value }` mapping
+
+### Key behavior
+
+- Two modes:
+  - `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
+
+Signals / fields:
+
+| Field / Signal | Type                                                   | Description           |
+|----------------|--------------------------------------------------------|-----------------------|
+| items          | `Signal<T[]>`                                          | Current visible items |
+| options        | `Signal<{ label: string; value: string \| number }[]>` | Options for selects   |
+| searchText     | `Signal<string>`                                       | Current search text   |
+| filters        | `Signal<Record<string, any>>`                          | Current filters       |
+
+Methods:
+
+| Method       | Description                                                                                |
+|--------------|--------------------------------------------------------------------------------------------|
+| search       | Set search text and trigger load (fixed=false) or local filter (fixed=true)                |
+| findLabel    | Resolve label by value from local cache (no network)                                       |
+| restoreCache | Restore cache from the selected storage (`persist`/`session`/`lru`/`memory`). (no network) |
+
+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                      |
+
+Example:
+
+```ts
+import { DictStore } from '@reforgium/statum';
+
+type Country = { code: string; name: string };
+
+const dict = new DictStore<Country>('api/dictionaries/countries', 'countries', {
+  labelKey: 'name',
+  valueKey: 'code',
+  fixed: true,
+});
+
+dict.search('');      // initial fill
+dict.search('kir');   // local search over cache
+```
+
+---
+
+## Serializer
+
+### Serializer
+
+Utility for serialization/deserialization between layers (UI ↔ API, objects ↔ query string).
+
+Core API:
+
+| Method | Description |
+|---|---|
+| serialize | Prepare data for transport |
+| deserialize | Parse incoming data / query string |
+| toQuery | Build query string |
+| withConfig | Clone serializer with partial config overrides |
+
+Config:
+
+| Option      | Type                                                                                                                                                                                                                        | Default     | Description                    |
+|-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|--------------------------------|
+| mapString   | `{ trim?: boolean }` & ParseFormatConfig<string>                                                                                                                                                                            | `{}`        | String transformation options  |
+| mapNumber   | `{ fromString?: boolean }` & ParseFormatConfig<number>                                                                                                                                                                      | `{}`        | Number parsing options         |
+| mapBoolean  | `{ true?: string; false?: string }` & ParseFormatConfig<boolean>                                                                                                                                                            | `{}`        | Boolean parsing options        |
+| mapDate     | `{ dateFormat?: string }` & ParseFormatConfig<Date>                                                                                                                                                                         | `{}`        | Date parsing options           |
+| mapPeriod   | `{ transformMode?: { mode: 'split'; dateFromKeyPostfix: string; dateToKeyPostfix: string } \| { mode: 'join'; concat: string }; dateFormat?: string }` & ParseFormatConfig<[Date \| null, Date \| null]>                    | `{}`        | Period handling options        |
+| mapNullable | `{ remove?: boolean; replaceWith?: string; includeEmptyString?: boolean }` & ParseFormatConfig<null \| undefined>                                                                                                           | `{}`        | Null/undefined handling        |
+| mapArray    | `{ concatType: 'comma' \| 'multi' \| 'json'; removeNullable?: boolean }` & `{ format?: (val: any[]) => any }`                                                                                                               | `{}`        | Array parsing options          |
+| mapObject   | `{ deep: boolean }` & `{ format?: (val: Record<string, any>) => any }`                                                                                                                                                      | `{}`        | Object transformation options  |
+| mapFields   | `Record<string, { type: 'string'\|'number'\|'boolean'\|'array'\|'object'\|'date'\|'period'\|'nullable' } \| { parse: (val: any, data: Record<string, any>) => any; format: (val: any, data: Record<string, any>) => any }>` | `undefined` | Field-specific transformations |
+
+Example:
+
+```ts
+import { Serializer } from '@reforgium/statum';
+
+const serializer = new Serializer({
+  mapString: { trim: true },
+  mapNullable: { remove: true },
+});
+
+const body = serializer.serialize({ name: '  Vasya  ', active: null });
+// => { name: 'Vasya' }
+```
+
+---
+
+## Source Structure
+
+- Cache: `src/cache`
+- Stores: `src/stores`
+- Serializer: `src/serializer`
+
+---
+
+## Compatibility
+
+- Angular: 18+
+- Signals: required
+- Zone.js: optional
+
+---
+
+## License
+
+MIT