@reforgium/statum 3.0.0-rc.1 → 3.0.0

package/README.md

@@ -3,12 +3,13 @@
 [![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 (18+).**
+**Signals-first query and data stores 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.
+`@reforgium/statum` provides **API-oriented stores**, **cache strategies**, and a  
+**serialization layer** for Angular applications that talk to HTTP backends.
 
-Designed for **application state**, not abstract reducers.
+Designed for **request orchestration, pagination, dictionaries, and entity state**.
+It is not a reduced framework and does not try to replace NgRx-style global event modeling.
 
 ---
 
@@ -23,31 +24,69 @@ Designed for **application state**, not abstract reducers.
 - Unified retry and trace hooks in `ResourceStore`
 - Explicit serialization / deserialization boundary
 
+## Best Fit
+
+Use `statum` when you need:
+
+- HTTP-first application state for CRUD-heavy Angular apps
+- Predictable request behavior (dedupe, abort, retry, latest-wins)
+- Reusable pagination and dictionary flows for tables and forms
+- Lightweight entity normalization without a full reducer architecture
+
+`statum` is usually a good fit between:
+
+- plain `HttpClient` services that have started to accumulate state logic
+- full application state frameworks where global reducers/effects are too expensive for the problem
+
+`statum` is usually not the right fit when:
+
+- you need cross-page event sourcing, time-travel tooling, or centralized action logs
+- your app is mostly local UI state with little backend orchestration
+- you want a framework-agnostic data layer
+
 ---
 
-## Installation
-
-```bash
-npm install @reforgium/statum
-```
-
-## Configuration
-
-```ts
-import { provideStatum } from '@reforgium/statum';
-
-providers: [
-  provideStatum({
-    pagedQuery: {
-      defaultMethod: 'GET',
-      defaultHasCache: true,
-      defaultCacheSize: 10,
-    },
-  }),
-];
-```
-
----
+## Installation
+
+```bash
+npm install @reforgium/statum
+```
+
+## Configuration
+
+```ts
+import { provideStatum } from '@reforgium/statum';
+
+providers: [
+  provideStatum({
+    pagedQuery: {
+      defaultBaseUrl: '/api',
+      defaultMethod: 'GET',
+      defaultHasCache: true,
+      defaultCacheSize: 10,
+    },
+  }),
+];
+```
+
+## API Stability
+
+`statum` v3 narrows its public API around explicit store methods and object-style contracts.
+
+Stability policy for the documented public surface:
+
+- Existing documented methods are treated as stable within `3.x`
+- Signature expansions should stay additive and backward-compatible
+- Behavioral changes should be reflected in `CHANGELOG.md` and, when needed, `MIGRATION.md`
+- Removed or renamed APIs should go through a documented migration path first
+
+The safest long-term entry points are:
+
+- package exports from `@reforgium/statum`
+- documented store methods in this README
+- provider helpers such as `provideStatum(...)`
+
+---
 
 ## Package Structure
 
@@ -55,6 +94,59 @@ providers: [
 - **Stores** - reusable state containers over HttpClient
 - **Serializer** - configurable data transformation utility
 
+## Behavioral Guarantees
+
+The core stores are designed around explicit, testable runtime guarantees.
+
+`ResourceStore` guarantees:
+
+- Identical in-flight requests can be deduplicated into one transport call
+- `abort(...)` / `abortAll(...)` cancel active or scheduled requests and clear inflight dedupe references
+- Retry policy can be set globally and overridden per request
+- Trace hooks receive cache/request lifecycle events for observability
+
+`PagedQueryStore` guarantees:
+
+- `fetch(...)` always starts from page `0` and clears page cache first
+- `updatePage(...)` can read from cache unless `ignoreCache` is enabled
+- `updatePageSize(...)` resets cache before loading the first page with the new size
+- `updateByOffset(...)` maps table offsets into normalized `page + size` requests
+- `latest-wins` keeps `loading` stable during abort/restart request bursts and ignores stale async parse results
+- `parallel` allows overlapping page requests when the source intentionally supports concurrent fetches
+
+`DictStore` guarantees:
+
+- `fixed: true` performs local search over the loaded cache after initial fill
+- `fixed: false` delegates search to the server with debounce support
+- Visible `options` stay normalized to `{ label, value }`
+
+Performance notes:
+
+- `ResourceStore`, `PagedQueryStore`, and `DictStore` include stress/perf coverage in the test suite
+- The goal of these tests is behavioral regression detection and upper-bound sanity checks, not synthetic benchmark marketing
+- For production evaluation, prefer measuring with your own API latency, payload size, and change detection profile
+- Run `npm run bench:statum` for a current local timing snapshot
+- Run `npm run bench:statum:browser` and open `/test-routing/statum-bench` for browser-side render measurements
+- See `PERF.md` for the latest checked-in baseline captured in this repository
+
+Reproducible examples are covered in tests:
+
+- `dedupe identical requests` - many callers hitting the same `ResourceStore.get(...)` with `dedupe: true` still produce one transport request
+- `cache hit/miss semantics` - `cache-only` fails on a cold key, then `cache-first` serves the warmed key without network
+- `latest-wins abort behavior` - `PagedQueryStore.updatePage(...)` bursts cancel older in-flight requests and only the newest page is applied
+- `pagination cache eviction` - when the page cache is full, revisiting an evicted page performs a fresh request
+- `warm cache replay` - replaying the hot cache window stays network-free across the full cached range
+
+These examples are intentionally implemented as specs, not ad-hoc benchmark scripts, so they can be rerun in CI and used as regression checks.
+
+The checked-in benchmark baseline in `PERF.md` also shows a practical scaling claim for `ResourceStore`:
+
+- identical request fan-in collapses from `N` transport calls to `1` when `dedupe: true`
+- in the current local snapshot, a `10,000` caller burst is roughly an order of magnitude faster with dedupe enabled
+- the same `10,000` caller burst reduces memory pressure from tens of MB to low single-digit MB in the deduped path
+
+Those numbers are machine-specific and should be treated as a local envelope, not a universal SLA.
+
 ---
 
 ## Cache
@@ -152,7 +244,7 @@ const user = await userStore.get(
 );
 ```
 
-Retry + trace example:
+Retry + trace example:
 
 ```ts
 import { ResourceStore } from '@reforgium/statum';
@@ -166,22 +258,22 @@ const store = new ResourceStore<{ id: number; name: string }>(
   }
 );
 
-await store.get(
-  { params: { id: '42' } },
-  { retry: { attempts: 1 } } // per-call override
-);
-```
-
-Profiles example:
-
-```ts
-import { createResourceProfile, ResourceStore } from '@reforgium/statum';
-
-const usersStore = new ResourceStore<{ id: number; name: string }>(
-  { GET: '/users' },
-  createResourceProfile('table', { baseUrl: '/api' })
-);
-```
+await store.get(
+  { params: { id: '42' } },
+  { retry: { attempts: 1 } } // per-call override
+);
+```
+
+Profiles example:
+
+```ts
+import { createResourceProfile, ResourceStore } from '@reforgium/statum';
+
+const usersStore = new ResourceStore<{ id: number; name: string }>(
+  { GET: '/users' },
+  createResourceProfile('table', { baseUrl: '/api' })
+);
+```
 
 ---
 
@@ -206,9 +298,9 @@ entities.removeOne(1);
 
 ---
 
-## PagedQueryStore
-
-Lightweight store for server-side pagination with filtering, dynamic query params, and page cache.
+## PagedQueryStore
+
+Lightweight store for server-side pagination with filtering, dynamic query params, and page cache.
 
 ### When to use
 
@@ -224,35 +316,65 @@ Lightweight store for server-side pagination with filtering, dynamic query param
 | items          | `WritableSignal<T[]>`     | Current page items                     |
 | cached         | `WritableSignal<T[]>`     | Flattened cache of cached pages        |
 | loading        | `WritableSignal<boolean>` | Loading indicator                      |
+| error          | `WritableSignal<unknown \| null>` | Last request error             |
+| version        | `WritableSignal<number>`  | Increments when the dataset is reset   |
 | page           | `number`                  | Current page (0-based)                 |
 | pageSize       | `number`                  | Page size                              |
 | totalElements  | `number`                  | Total items on server                  |
-| filters        | `Partial<F>`              | Active filters                         |
-| query          | `Record<string, unknown>` | Active query params                    |
+| filters        | `Partial<F>`              | Active filters                         |
+| query          | `Record<string, unknown>` | Active query params                    |
+| sort           | `ReadonlyArray<{ sort: string; order: 'asc' \| 'desc' }>` | Active sort state |
+
+Reactive metadata signals are also available:
+
+- `pageState`
+- `pageSizeState`
+- `totalElementsState`
+- `filtersState`
+- `queryState`
+- `sortState`
+- `routeParamsState`
 
 ### Methods
 
-| Method         | Description                                                               |
-|----------------|---------------------------------------------------------------------------|
-| fetch          | Clean first-page request: `fetch({ filters, query, routeParams })`       |
-| refetchWith        | Repeat request, optional merge overrides: `refetchWith({ filters, query })`  |
-| updatePage     | Change page: `updatePage(page, { ignoreCache })`                         |
-| updatePageSize | Change page size and reset cache: `updatePageSize(size)`                 |
-| updateByOffset | Table-event mapper: `updateByOffset({ page/first/rows }, { query })`    |
-| setRouteParams | Update route params: `setRouteParams(params, { reset, abort })`         |
-| updateConfig   | Patch config: `updateConfig(config)`                                     |
-| copy           | Copy config/meta: `copy(store)`                                          |
-| destroy        | Manual destroying of caches and abort requests                           |
-
-### Cache behavior
-
-| Method         | Cache read | Cache reset | Notes |
-|----------------|------------|-------------|-------|
-| fetch          | no         | yes         | Always starts clean from page `0` |
-| refetchWith        | no         | no          | Uses active page/filters/query, merges overrides |
-| updatePage     | yes        | no          | Can bypass with `ignoreCache: true` |
-| updatePageSize | no         | yes         | Prevents mixed caches for different page sizes |
-| updateByOffset | yes        | no          | Internally maps to `page + size` |
+| Method         | Description                                                                             |
+|----------------|-----------------------------------------------------------------------------------------|
+| fetch          | Clean first-page request: `fetch({ filters, query, routeParams })`                      |
+| refetchWith    | Repeat request, optional merge overrides: `refetchWith({ filters, query })`             |
+| updatePage     | Change page: `updatePage(page, { ignoreCache })` or `updatePage({ page, ignoreCache })` |
+| updatePageSize | Change page size and reset cache: `updatePageSize(size)`                                |
+| setSort        | Update sort state without triggering a request                                           |
+| updateSort     | Apply single-sort state and load from the first page                                     |
+| updateSorts    | Apply multi-sort state and load from the first page                                      |
+| updateByOffset | Table-event mapper: `updateByOffset({ page/first/rows }, { query })`                    |
+| setRouteParams | Update route params: `setRouteParams(params, { reset, abort })`                         |
+| updateConfig   | Patch config: `updateConfig(config)`                                                    |
+| copy           | Copy config/meta: `copy(store)`                                                         |
+| destroy        | Manual destroying of caches and abort requests                                          |
+
+`version` is useful for consumers that keep their own local page buffer. For example, `@reforgium/data-grid` can use `[source]="store"` and clear its internal infinity buffer when `fetch()`, `updatePageSize()`, or `setRouteParams(..., { reset: true })` replace the dataset.
+
+Sorting is built into `PagedQueryStore` and serialized in the common backend-friendly form:
+
+```txt
+sort=name,asc
+sort=name,asc&sort=createdAt,desc
+```
+
+Concurrency can be configured per store:
+
+- `latest-wins` - abort older in-flight requests before the next page request starts
+- `parallel` - allow overlapping requests and keep `loading()` true until all active requests finish
+
+### Cache behavior
+
+| Method         | Cache read | Cache reset | Notes                                            |
+|----------------|------------|-------------|--------------------------------------------------|
+| fetch          | no         | yes         | Always starts clean from page `0`                |
+| refetchWith    | no         | no          | Uses active page/filters/query, merges overrides |
+| updatePage     | yes        | no          | Can bypass with `ignoreCache: true`              |
+| updatePageSize | no         | yes         | Prevents mixed caches for different page sizes   |
+| updateByOffset | yes        | no          | Internally maps to `page + size`                 |
 
 Example:
 
@@ -261,15 +383,51 @@ import { PagedQueryStore } from '@reforgium/statum';
 
 type User = { id: number; name: string };
 
-const store = new PagedQueryStore<User, { search?: string }>('api/users', {
-  method: 'GET',
-  debounceTime: 200,
-});
-
-store.fetch({ filters: { search: 'neo' }, query: { tenant: 'kg' } });
-store.updateByOffset({ first: 20, rows: 20 });
+const store = new PagedQueryStore<User, { search?: string }>('api/users', {
+  baseUrl: '/api',
+  method: 'GET',
+  debounceTime: 200,
+  concurrency: 'latest-wins',
+});
+
+store.fetch({ filters: { search: 'neo' }, query: { tenant: 'kg' } });
+store.updateByOffset({ first: 20, rows: 20 });
+store.updateSort({ sort: 'name', order: 'asc' });
 ```
 
+`cached()` remains a bounded hot-cache view. It is useful for cache-aware revisit/export/search helpers, but it is not the right datasource for infinity scrolling once cache eviction matters. For `data-grid` infinity mode, prefer passing the whole store as a `GridPagedDataSource` (`[source]="store"`) and let the grid keep its own page buffer.
+
+Direct state mutation setters for `page`, `pageSize`, `filters`, `query`, and `totalElements` still exist for backward compatibility, but they are deprecated in favor of explicit store methods. `sort` and `routeParams` should be changed only through `setSort(...)` and `setRouteParams(...)`.
+
+### PagedQueryStore + DataGrid source mode
+
+`PagedQueryStore` can be passed directly into `@reforgium/data-grid` `source` mode:
+
+```html
+<re-data-grid
+  mode="infinity"
+  [columns]="columns"
+  [source]="usersStore"
+/>
+```
+
+This works because the store already exposes the expected source contract:
+
+- `items`
+- `loading`
+- `error`
+- `page`
+- `pageSize`
+- `totalElements`
+- `sort`
+- `version`
+- `updatePage(...)`
+- `updatePageSize(...)`
+- `updateSort(...)`
+- `updateSorts(...)`
+
+Keep `data-grid` source prefetch in `sequential` mode when the store uses `latest-wins`. Switch to `parallel` only if the store is configured with `concurrency: 'parallel'` and the backend flow supports overlapping page requests.
+
 ---
 
 ## DictStore
@@ -364,6 +522,107 @@ This keeps page-loading logic in `PagedQueryStore` and normalized lookup/update
 
 ---
 
+## Recipes
+
+### Debounced Remote Table
+
+Use `PagedQueryStore` as a reusable server-table state layer for filters, lazy paging, and cache-aware navigation.
+
+```ts
+import { PagedQueryStore } from '@reforgium/statum';
+
+type User = { id: number; name: string; role: string };
+type UserFilters = { search?: string; role?: string };
+
+const users = new PagedQueryStore<User, UserFilters>('/api/users', {
+  baseUrl: '/gateway',
+  method: 'GET',
+  debounceTime: 250,
+  hasCache: true,
+  cacheSize: 5,
+});
+
+await users.fetch({
+  filters: { search: 'neo', role: 'admin' },
+  query: { tenant: 'main' },
+});
+
+await users.updateByOffset({ first: 20, rows: 20 });
+```
+
+Use this when the component should stay thin and pagination/filter state should live outside the template layer.
+
+### Latest-Wins Details Loader
+
+Use `ResourceStore` when route changes or rapid user clicks can trigger overlapping requests.
+
+```ts
+import { ResourceStore } from '@reforgium/statum';
+
+type UserDetails = { id: number; name: string; email: string };
+
+const details = new ResourceStore<UserDetails>(
+  { GET: '/api/users/:id' },
+  { ttlMs: 30_000 }
+);
+
+async function openUser(id: number) {
+  details.abortAll();
+
+  return details.get(
+    { params: { id } },
+    { dedupe: true }
+  );
+}
+```
+
+Use this when the newest selection should win and stale responses should not keep competing for UI state.
+
+### Autocomplete With Cached Dictionary
+
+Use `DictStore` to separate option loading, debounce, and local filtering from the component.
+
+```ts
+import { DictStore } from '@reforgium/statum';
+
+type Country = { code: string; name: string };
+
+const countries = new DictStore<Country>('/api/dictionaries/countries', 'countries', {
+  fixed: true,
+  labelKey: 'name',
+  valueKey: 'code',
+});
+
+await countries.search('');
+countries.search('kir');
+```
+
+Use `fixed: true` when the dataset is small enough to keep locally and you want immediate repeated searches without extra network calls.
+
+### Normalize Paged Data For Detail Mutations
+
+Use `PagedQueryStore` for loading and `EntityStore` for stable updates after edits.
+
+```ts
+import { effect } from '@angular/core';
+import { EntityStore, PagedQueryStore } from '@reforgium/statum';
+
+type User = { id: number; name: string };
+
+const pages = new PagedQueryStore<User>('/api/users');
+const entities = new EntityStore<User, 'id'>({ idKey: 'id' });
+
+effect(() => {
+  entities.upsertMany(pages.items());
+});
+
+entities.patchOne(1, { name: 'Updated' });
+```
+
+Use this when list fetching and local item mutations need different lifecycles.
+
+---
+
 ## Serializer
 
 ### Serializer
@@ -409,12 +668,12 @@ const body = serializer.serialize({ name: '  Vasya  ', active: null });
 
 ---
 
-## Source Structure
-
-- Cache: `src/cache`
-- Stores: `src/stores`
-- Serializer: `src/serializer`
-- Migration: `MIGRATION.md`
+## Source Structure
+
+- Cache: `src/cache`
+- Stores: `src/stores`
+- Serializer: `src/serializer`
+- Migration: `MIGRATION.md`
 
 ---