@reforgium/statum 3.0.1 → 3.1.1

package/CHANGELOG.md

@@ -0,0 +1,218 @@
+## [3.1.1]: 2026-04-04
+
+### Refactor:
+- Moved `Serializer` core into `@reforgium/internal`; `statum` now keeps serializer presets and public wrappers while reusing the shared codec engine underneath.
+- Moved low-level storage implementations and `storageStrategy(...)` into `@reforgium/internal`; `statum` cache exports now act as compatibility wrappers over the shared foundation layer.
+
+### Fix:
+- Package build and workspace resolution were aligned with hidden `@reforgium/internal` usage.
+- `PagedQueryStore` transport generic ordering was corrected for package build stability.
+
+### Docs:
+- `README` now reflects `storageStrategy(...)` naming and clarifies that serializer/storage core are shared through `@reforgium/internal`.
+
+---
+
+## [3.1.0]: 2026-04-01
+
+### Feat:
+- `ResourceStore`: added `observe` option on per-call config; set `observe: 'response'` to pass the full `HttpResponse<T>` to `parseResponse` instead of just the body
+- `ResourceStore`: added request-body pass-through for `FormData`, `Blob`, and `ArrayBuffer`
+- `ResourceStore`: added optional retry jitter (`+-25%`) on top of constant/exponential backoff
+
+### Refactor:
+- `PagedQueryStore`: removed `@deprecated` annotations from direct state setters (`page`, `pageSize`, `filters`, `query`, `totalElements`); setters remain available for low-level integration scenarios
+
+### Fix:
+- `ResourceStore`: aligned query generics with actual transport behavior; query args now support booleans and arrays without reusing payload constraints
+- `ResourceStore`: GET cache lookups now refresh LRU order, while `cache-only` misses no longer create empty cache entries
+- `ResourceStore`: abort and abortAll now cancel underlying `HttpClient` requests via `AbortController` and correctly recognize browser `AbortError`
+- `ResourceStore`: request state promotion and loading cleanup were stabilized for abort and retry flows, including non-promoted entries
+- `PagedQueryStore`: `presetQuery.page` is now optional and defaults to `0`
+- `PagedQueryStore`: `parseRequest` typing now accepts concrete filter dictionaries without conflicting with `AnyDict` call sites
+- `Serializer`: deep object serialization now skips circular references instead of throwing
+
+### Test:
+- `ResourceStore`: added `observe` coverage for cache-first hit, HTTP error propagation, and PUT/PATCH/DELETE methods
+- `ResourceStore`: added coverage for retry backoff/jitter, payload pass-through, abort edge cases, forced eviction, and hot-key LRU behavior
+- `DictStore`, `DictLocalStore`, and `EntityStore`: added regression coverage for uncovered edge scenarios
+- `Serializer`: added regression coverage for direct and indirect circular references plus repeated shared-object serialization
+
+### Docs:
+- `README`: documented `observe: 'response'` behavior and clarified direct setter usage in `PagedQueryStore`
+
+### Chore:
+- package assets now include `CHANGELOG.md` and `LICENSE`
+
+---
+
+## [3.0.1]: 2026-03-31
+
+### Feat:
+- `ResourceStore`: added `observe` option on per-call config - set `observe: 'response'` to pass the full `HttpResponse<T>` to `parseResponse` instead of just the body; useful for reading response headers or status codes
+
+### Refactor:
+- `PagedQueryStore`: removed `@deprecated` annotations from direct state setters (`page`, `pageSize`, `filters`, `query`, `totalElements`); setters remain available for low-level integration scenarios (e.g., external data-grid source contracts)
+
+### Test:
+- `ResourceStore`: added `observe` coverage for cache-first hit, HTTP error propagation, and PUT/PATCH/DELETE methods
+
+---
+
+## [3.0.0]: 2026-03-17
+
+### Feat:
+- `PagedQueryStore`: added first-class sorting state and methods (`setSort`, `updateSort`, `updateSorts`) with standard repeated query serialization (`sort=a,asc&sort=b,desc`)
+- `PagedQueryStore`: added reactive metadata signals (`pageState`, `pageSizeState`, `totalElementsState`, `filtersState`, `queryState`, `sortState`, `routeParamsState`)
+- `PagedQueryStore`: added reactive `error` signal
+- `PagedQueryStore`: added configurable request concurrency (`latest-wins` by default, optional `parallel`)
+- `PagedQueryStore`: added `baseUrl` config option and `defaultBaseUrl` provider default for routing requests through a shared API prefix
+- `PagedQueryStore`: added `disableCacheLimit` config flag to disable LRU eviction and keep all loaded pages in memory
+- `PagedQueryStoreProviderConfig`: added `defaultDisableCacheLimit` global default
+- `DictStore`: added cache freshness controls (`ttlMs`, `revalidate`) and provider defaults (`defaultTtlMs`, `defaultRevalidate`)
+- `DictStore`: added `clearCache()`
+- `Serializer`: added per-field array query serialization override via `mapFields.<key>.concatType`
+
+### Refactor:
+- `PagedQueryStore`: route params are now exposed only via `routeParamsState`; direct `routeParams` getter was removed
+- `PagedQueryStore`: direct `sort` / `routeParams` mutation setters were removed; remaining direct state setters are now deprecated
+- `ResourceStore`: GET setup path no longer uses the extra local rethrow branch while preserving dedupe/cache behavior
+
+### Fix:
+- `PagedQueryStore`: `latest-wins` request bursts now keep `loading` stable until the newest request finishes
+- `PagedQueryStore`: stale async `parseResponse` results are now ignored after a newer request starts, transport is reinitialized, or the store is destroyed
+- `PagedQueryStore.updateConfig(...)` / `copy(...)`: transport is now reinitialized so updated request settings apply immediately
+- `ResourceStore`: query arrays are now serialized as comma-separated values (`a=1,2,3`) instead of collapsing to a single last value
+- `PagedQueryStore`: cache limit resolution is now consistent across constructor/config apply/`updateConfig`, including cache-size updates at runtime
+- `ResourceStore`: empty-string routes are now treated as valid and `baseUrl + ''` no longer produces a trailing slash
+- `DictStore`: stale local cache can now stay visible while background refresh runs, with timestamped storage metadata
+- `LruCache`: limit setter ordering/typing was normalized to keep runtime behavior predictable
+- `Serializer`: query parse/build now respects per-field array concat modes
+
+### Test:
+- added expanded `PagedQueryStore` regression coverage for sorting, cache limits, concurrency, config updates, and source-mode integration
+- added `ResourceStore` regression coverage for query-array serialization and empty-string routes
+- added `DictStore` regression coverage for TTL/revalidate/clear-cache flows
+- added perf/stress suites and report benchmarks for main stores
+- stabilized test setup / Vitest library configuration for the v3 suite
+
+### Docs:
+- `README`: updated positioning, API stability policy, behavioral guarantees, recipes, and `PagedQueryStore` / `data-grid` integration guidance
+- `MIGRATION.md`: added v3 stability note and expanded migration guidance
+- `PERF.md`: added checked-in benchmark/report baseline for main stores
+
+---
+
+## [3.0.0-rc.1]: 2026-02-18
+
+### Feat:
+- `PagedQueryStore`: normalized public API to object-style contracts (`fetch`, `refetchWith`, `updatePage`, `updatePageSize`, `updateByOffset`, `setRouteParams`, `updateConfig`, `copy`)
+- `PagedQueryStore`: `fetch({ filters, query, routeParams })` performs clean first-page request with cache reset
+- `ResourceStore`: added reusable option presets via `RESOURCE_PROFILES` and `createResourceProfile(...)`
+- `Statum`: added `provideStatum(...)` provider helper for DI configuration
+
+### Refactor:
+- `PagedQueryStore`: removed built-in sorting state/transport mapping from store internals (sorting stays at consumer side)
+- `PagedQueryStore`: removed legacy APIs `updateFilters(...)`, `updateQuery(...)`, `setRoute(...)`
+- `DictStore`: migrated internal helper calls to new `PagedQueryStore.fetch(...)` contract
+
+### Fix:
+- `ResourceStore`: `abort(...)` / `abortAll(...)` now clear dedupe inflight references immediately
+- `Serializer` tests: aligned `multi` query-array expectation with current query builder behavior
+
+### Docs:
+- `README`: updated `PagedQueryStore` v3 API and cache behavior matrix
+- `MIGRATION.md`: added v3 old-to-new mapping with concrete replacement examples
+
+---
+
+## [2.1.0]: 2026-02-14
+
+### Feat:
+- `EntityStore`: added normalized entity store (`byId` + `ids`) with `setAll`, `upsert`, `remove`, `patch`, and computed `items`
+- `ResourceStore`: added unified retry policy (`attempts`, `delayMs`, `backoff`, `shouldRetry`) on store and per-call levels
+- `ResourceStore`: added trace hook (`onTrace`) for cache/request lifecycle (`cache-hit/miss/fallback/write`, `request-start/success/error/retry`, `abort`)
+- `Serializer`: added presets export (`serializer.presets`) for quicker setup of common mapping configurations
+- `Stores`: added `resource.scheduler` public test coverage and scheduler stability improvements
+- `Stores`: added integration tests for composed flows (`ResourceStore` + `PaginatedDataStore` + `EntityStore`)
+- `Stores`: added perf/stress test suite for main stores
+
+### Fix:
+- `ResourceStore + KeyedScheduler`: stabilized cancel/reject behavior for abort/debounce scenarios in tests
+- `EntityStore`: fixed generic type narrowing an edge case (`TS2677`) by removing invalid predicate narrowing in `removeMany`
+- `ResourceStore`: expanded models/exports and aligned runtime behavior for retry + tracing hooks
+- `PaginatedDataStore`: refined config/cache behavior and updated tests around cache/refresh flows
+- `DictStore`: refined store behavior and updated coverage for edge scenarios
+- `CacheStrategy` + storages (`local/session/lru`): safety and behavior fixes with updated tests
+- `Serializer`: parsing/normalization fixes and stronger test coverage for edge cases
+
+### Docs:
+- `README`: added composition patterns and updated usage examples for `EntityStore` and `ResourceStore` retry/trace
+
+---
+
+## [2.0.1]: 2026-02-06
+
+### Fix:
+- `ResourceStore`: stable request keys now include payload; use `responseType` in HttpClient requests; avoid unhandled rejections
+- `PaginatedDataStore`: initialize LRU cache size from resolved config; keep cache limit in sync after config changes; clarify `setRouteParams` reset behavior
+- `DictStore`: debounce respects configured `debounceTime`; local filter handles non-string values safely
+- `DictLocalStore`: respects global default `maxOptionsSize`
+- `Serializer`: honor `mapString.parse` without precedence bugs; deep object deserialize; nullable handling preserves falsy values
+
+### Chore:
+- `LruCache`: added `entries()` helper
+- `README`: updated defaults and fixed broken formatting/encoding
+
+---
+
+## [2.0.0]: 2026-01-22
+
+### Feat:
+- `PaginatedDataStore`: added route params update method
+- `DictStore`: added debounce for search
+
+### Fix:
+- `ResourceStore`: improved internal key uniqueness
+- `ResourceStore`: fixed `loading` handling for concurrent requests
+- `LocalStorage`/`SessionStorage`: prefix-based safety for clear operations
+
+---
+
+## [1.0.2]: 2026-01-09
+
+### Chore:
+- improved docs
+
+---
+
+## [1.0.1]: 2026-01-09
+
+### Fix:
+- `DictStore`: fixed search effect handling
+- `PaginatedDataStore`: reordered filter caching
+
+### Feat:
+- `PaginatedDataStore`: made `parseResponse` async
+
+---
+
+## [1.0.0]: 2025-12-24
+
+### Feat:
+- base data grid functionality
+- virtual scrolling for large datasets
+- single-column sorting
+- pagination and infinite scroll
+- customizable cell and header templates
+- pin rows to top and bottom
+- sticky columns left and right
+- text alignment configuration per column
+- min/max column widths
+- single and multiple row selection
+- index column support
+- empty/loading state customization
+- flexible data typing system
+
+
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rtommievich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@
 
 **Signals-first query and data stores for Angular (18+).**
 
-`@reforgium/statum` provides **API-oriented stores**, **cache strategies**, and a  
+`@reforgium/statum` provides **API-oriented stores**, **cache strategies**, and a
 **serialization layer** for Angular applications that talk to HTTP backends.
 
 Designed for **request orchestration, pagination, dictionaries, and entity state**.
@@ -94,6 +94,9 @@ The safest long-term entry points are:
 - **Stores** - reusable state containers over HttpClient
 - **Serializer** - configurable data transformation utility
 
+Low-level serializer and storage primitives are shared through hidden `@reforgium/internal`.
+`statum` remains the user-facing package; you do not need to install or reason about `@reforgium/internal` directly in normal usage.
+
 ## Behavioral Guarantees
 
 The core stores are designed around explicit, testable runtime guarantees.
@@ -151,9 +154,9 @@ Those numbers are machine-specific and should be treated as a local envelope, no
 
 ## Cache
 
-### cacheStrategy
+### storageStrategy
 
-`cacheStrategy<T>(kind)` is a factory that returns a cache storage implementing `StorageInterface<T>`
+`storageStrategy<T>(kind)` is a factory that returns a cache storage implementing `StorageInterface<T>`
 
 Available strategies:
 
@@ -180,11 +183,11 @@ interface StorageInterface<T> {
 Example:
 
 ```ts
-import { cacheStrategy } from '@reforgium/statum';
+import { storageStrategy } from '@reforgium/statum';
 
 type User = { id: number; name: string };
 
-const storage = cacheStrategy<User>('persist');
+const storage = storageStrategy<User>('persist');
 
 storage.set('user:1', { id: 1, name: 'John' });
 
@@ -226,6 +229,28 @@ Transport-level store over HttpClient with cache strategies, deduplication, abor
 | abort    | Abort a specific request |
 | abortAll | Abort all requests       |
 
+### observe
+
+By default, `parseResponse` (and the resolved Promise value) receive the **response body**.
+Pass `observe: 'response'` to receive the full `HttpResponse` instead — useful for reading response headers or status codes inside `parseResponse`.
+
+```ts
+const result = await store.get(
+  { params: { id: '1' }, query: {} },
+  {
+    observe: 'response',
+    parseResponse: (res) => ({
+      data: res.body,
+      etag: res.headers.get('ETag'),
+    }),
+  },
+);
+```
+
+`onResponse` (store-level hook) always fires with the full `HttpResponse` regardless of `observe`, and is intended for side-effects only (logging, header extraction).
+
+> Cache hits bypass the network entirely. When `observe: 'response'` is used with `strategy: 'cache-first'` or `'cache-only'` and a cached value exists, `parseResponse` is not called — the cached result is returned as-is.
+
 Example:
 
 ```ts
@@ -397,7 +422,7 @@ 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(...)`.
+`sort` and `routeParams` should be changed only through `setSort(...)` and `setRouteParams(...)`. Direct state mutation setters for `page`, `pageSize`, `filters`, `query`, and `totalElements` are available for low-level integration scenarios (such as external data-grid source contracts) but prefer the explicit store methods for typical use.
 
 ### PagedQueryStore + DataGrid source mode
 
@@ -629,6 +654,8 @@ Use this when list fetching and local item mutations need different lifecycles.
 
 Utility for serialization/deserialization between layers (UI -> API, objects -> query string).
 
+`statum` keeps the user-facing serializer API and presets, while the low-level codec engine is shared from hidden `@reforgium/internal`.
+
 Core API:
 
 | Method      | Description                                    |