@reforgium/statum 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,203 @@
+## [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

@@ -226,6 +226,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 +419,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
 

package/fesm2022/reforgium-statum.mjs

@@ -90,8 +90,11 @@ class Serializer {
      * @param obj source object
      * @returns a flat dictionary with string/primitive values
      */
-    serialize(obj) {
+    serialize(obj, _seen = new WeakSet()) {
         const result = {};
+        if (obj != null && typeof obj === 'object') {
+            _seen.add(obj);
+        }
         for (const [key, value] of Object.entries(obj ?? {})) {
             const fields = this.config.mapFields?.[key];
             if (fields && 'format' in fields) {
@@ -117,7 +120,10 @@ class Serializer {
                     continue;
                 }
             }
-            result[key] = this.serializeElement(value, key);
+            result[key] = this.serializeElement(value, key, _seen);
+        }
+        if (obj != null && typeof obj === 'object') {
+            _seen.delete(obj);
         }
         return result;
     }
@@ -206,7 +212,7 @@ class Serializer {
     withConfig(config) {
         return new Serializer(this.mergeConfig(this.config, config));
     }
-    serializeElement(value, key) {
+    serializeElement(value, key, _seen = new WeakSet()) {
         const fields = this.config.mapFields?.[key || ''];
         if (fields && 'format' in fields) {
             return;
@@ -248,11 +254,14 @@ class Serializer {
             }
         }
         if (fields?.type === 'array' || Array.isArray(value)) {
-            return value.map((it) => this.serializeElement(it));
+            return value.map((it) => this.serializeElement(it, undefined, _seen));
         }
         if (fields?.type === 'object' || isObject(value)) {
+            if (this.config.mapObject.deep && !this.config.mapObject.format && value != null && _seen.has(value)) {
+                return undefined;
+            }
             return (this.config.mapObject.format?.(value) ??
-                (this.config.mapObject.deep ? this.serialize(value) : JSON.stringify(value)));
+                (this.config.mapObject.deep ? this.serialize(value, _seen) : JSON.stringify(value)));
         }
     }
     deserializeElement(value, key) {
@@ -638,6 +647,7 @@ class AbortError extends Error {
  */
 function isAbort(e) {
     return (e instanceof AbortError ||
+        (e instanceof DOMException && e.name === 'AbortError') ||
         (typeof e === 'object' && e != null && e?.name === 'AbortError' && e?.message === 'aborted'));
 }
 function joinUrl(base, path) {
@@ -906,15 +916,20 @@ class ResourceStore {
         catch (error) {
             return Promise.reject(error);
         }
-        const entry = this.ensureEntry(key);
         const strategy = cfg.strategy ?? 'network-first';
         const ttlMs = cfg.ttlMs ?? this.opts.ttlMs ?? 0;
-        const fresh = entry.updatedAt != null && Date.now() - entry.updatedAt < ttlMs;
-        if (cfg.dedupe && entry.inflight) {
+        let entry = this.entries.get(key);
+        if (entry) {
+            // Keep hot keys at the end to approximate LRU order on cache reads too.
+            this.entries.delete(key);
+            this.entries.set(key, entry);
+        }
+        const fresh = entry?.updatedAt != null && Date.now() - entry.updatedAt < ttlMs;
+        if (cfg.dedupe && entry?.inflight) {
             return entry.inflight;
         }
         if (strategy === 'cache-only') {
-            if (fresh && entry.data != null) {
+            if (fresh && entry?.data != null) {
                 this.trace({ type: 'cache-hit', method: 'GET', key, strategy });
                 this.promoteCurrent(entry, cfg.promote);
                 return Promise.resolve(entry.data);
@@ -922,29 +937,44 @@ class ResourceStore {
             this.trace({ type: 'cache-miss', method: 'GET', key, strategy });
             return Promise.reject(new CacheMissError(key));
         }
-        if (strategy === 'cache-first' && fresh && !cfg.revalidate && entry.data != null) {
+        if (strategy === 'cache-first' && fresh && !cfg.revalidate && entry?.data != null) {
             this.trace({ type: 'cache-hit', method: 'GET', key, strategy });
             this.promoteCurrent(entry, cfg.promote);
             return Promise.resolve(entry.data);
         }
+        entry ??= this.ensureEntry(key);
         const delay = cfg.delay ?? this.opts.delay ?? 0;
         const mode = cfg.delayMode ?? this.opts.delayMode ?? 'debounce';
         const isSWR = strategy === 'cache-first' && entry.data != null;
         entry.status = isSWR ? 'stale' : 'loading';
+        if (!isSWR) {
+            entry.error = null;
+        }
         this.promoteCurrent(entry, cfg.promote);
         const retry = this.resolveRetryConfig(cfg.retry);
         const taskWithRetry = this.runWithRetry((attempt) => {
             this.trace({ type: 'request-start', method: 'GET', key, attempt });
-            return this.scheduler.schedule(key, mode, delay, this.exec$({
-                req$: this.http.get(url, { params: query, responseType: responseType }),
+            entry.controller = new AbortController();
+            const options = {
+                params: query,
+                responseType: responseType,
+                observe: 'response',
+                signal: entry.controller.signal,
+            };
+            const scheduled = this.scheduler.schedule(key, mode, delay, this.exec$({
+                req$: this.http.get(url, options),
                 entry,
                 promote: cfg.promote,
                 parseFn: cfg.parseResponse,
+                observe: cfg.observe,
             }));
+            void scheduled.catch(() => undefined);
+            return scheduled;
         }, retry, {
             method: 'GET',
             key,
         });
+        void taskWithRetry.catch(() => undefined);
         const resolvedTask = taskWithRetry
             .catch((error) => {
             if (isAbort(error)) {
@@ -1036,9 +1066,12 @@ class ResourceStore {
         const entry = this.entries.get(key);
         this.trace({ type: 'abort', method, key });
         if (entry) {
+            entry.controller?.abort(reason instanceof Error ? reason : new AbortError(typeof reason === 'string' ? reason : undefined));
+            entry.controller = undefined;
             entry.inflight = undefined;
             if (entry.status === 'loading' || entry.status === 'stale') {
                 entry.status = 'idle';
+                this.promoteCurrent(entry, entry.promoted);
             }
         }
         this.scheduler.cancel?.(key, reason);
@@ -1050,10 +1083,14 @@ class ResourceStore {
      */
     abortAll(reason) {
         this.trace({ type: 'abort', method: 'GET', key: '*' });
+        const abortReason = reason instanceof Error ? reason : new AbortError(typeof reason === 'string' ? reason : undefined);
         this.entries.forEach((entry) => {
+            entry.controller?.abort(abortReason);
+            entry.controller = undefined;
             entry.inflight = undefined;
             if (entry.status === 'loading' || entry.status === 'stale') {
                 entry.status = 'idle';
+                this.promoteCurrent(entry, entry.promoted);
             }
         });
         this.scheduler.cancelAll?.(reason);
@@ -1076,13 +1113,18 @@ class ResourceStore {
         while (this.entries.size >= this.maxEntries) {
             let keyToDelete = null;
             for (const [key, value] of this.entries.entries()) {
-                if (!value.inflight) {
+                if (!value.inflight && !value.controller) {
                     keyToDelete = key;
                     break;
                 }
             }
             if (keyToDelete === null) {
+                // All entries have active requests — forced eviction. Dedupe for the evicted
+                // key will break: the in-flight request will finish but its result won't be cached.
                 keyToDelete = this.entries.keys().next().value ?? null;
+                if (keyToDelete !== null) {
+                    this.trace({ type: 'abort', method: 'GET', key: keyToDelete });
+                }
             }
             if (keyToDelete === null) {
                 break;
@@ -1114,25 +1156,35 @@ class ResourceStore {
         const mode = config.delayMode ?? this.opts.delayMode ?? 'debounce';
         const retry = this.resolveRetryConfig(config.retry);
         entry.status = 'loading';
+        entry.error = null;
         this.promoteCurrent(entry, config.promote);
-        let req$;
-        if (method === 'DELETE') {
-            req$ = this.http.delete(url, {
-                body: payload,
-                params: query,
-                responseType: responseType,
-            });
-        }
-        else {
-            // @ts-ignore
-            req$ = this.mutationMethods[method](url, payload, {
-                params: query,
-                responseType: responseType,
-            });
-        }
         const task = this.runWithRetry((attempt) => {
             this.trace({ type: 'request-start', method, key, attempt });
-            return this.scheduler.schedule(key, mode, delay, this.exec$({ req$, entry, promote: config.promote, parseFn: config.parseResponse }));
+            entry.controller = new AbortController();
+            const signal = entry.controller.signal;
+            let req$;
+            if (method === 'DELETE') {
+                // @ts-ignore
+                req$ = this.http.delete(url, {
+                    body: payload,
+                    params: query,
+                    responseType: responseType,
+                    observe: 'response',
+                    signal,
+                });
+            }
+            else {
+                // @ts-ignore
+                req$ = this.mutationMethods[method](url, payload, {
+                    params: query,
+                    responseType: responseType,
+                    observe: 'response',
+                    signal,
+                });
+            }
+            const scheduled = this.scheduler.schedule(key, mode, delay, this.exec$({ req$, entry, promote: config.promote, parseFn: config.parseResponse, observe: config.observe }));
+            void scheduled.catch(() => undefined);
+            return scheduled;
         }, retry, { method, key })
             .then((data) => {
             this.trace({ type: 'cache-write', method, key });
@@ -1181,6 +1233,9 @@ class ResourceStore {
         });
     }
     preparePayload(payload) {
+        if (payload instanceof FormData || payload instanceof Blob || payload instanceof ArrayBuffer) {
+            return payload;
+        }
         const presetPayload = this.opts.presetPayload;
         if (!presetPayload && !payload) {
             return {};
@@ -1214,6 +1269,7 @@ class ResourceStore {
             attempts: Math.max(0, source.attempts ?? 0),
             delayMs: Math.max(0, source.delayMs ?? 0),
             backoff: source.backoff ?? 'constant',
+            jitter: source.jitter ?? false,
             shouldRetry: source.shouldRetry ?? this.defaultShouldRetry,
         };
     }
@@ -1228,29 +1284,41 @@ class ResourceStore {
         }
         return status === 0 || status >= 500;
     }
-    async runWithRetry(exec, retry, context) {
-        let attempt = 1;
-        while (true) {
-            try {
-                return await exec(attempt);
+    runWithRetry(exec, retry, context) {
+        const runAttempt = (attempt) => exec(attempt).catch((error) => {
+            const canRetry = attempt <= retry.attempts && retry.shouldRetry(error, attempt);
+            if (!canRetry) {
+                throw error;
             }
-            catch (error) {
-                const canRetry = attempt <= retry.attempts && retry.shouldRetry(error, attempt);
-                if (!canRetry) {
-                    throw error;
-                }
-                const delayMs = retry.backoff === 'exponential' ? retry.delayMs * 2 ** (attempt - 1) : retry.delayMs;
-                this.trace({ type: 'request-retry', method: context.method, key: context.key, attempt, error });
-                attempt++;
-                if (delayMs > 0) {
-                    await new Promise((resolve) => setTimeout(resolve, delayMs));
-                }
+            const baseDelay = retry.backoff === 'exponential' ? retry.delayMs * 2 ** (attempt - 1) : retry.delayMs;
+            const jitterOffset = retry.jitter ? (Math.random() * 0.5 - 0.25) * baseDelay : 0;
+            const delayMs = Math.max(0, Math.round(baseDelay + jitterOffset));
+            this.trace({ type: 'request-retry', method: context.method, key: context.key, attempt, error });
+            if (delayMs > 0) {
+                return new Promise((resolve, reject) => {
+                    setTimeout(() => {
+                        void runAttempt(attempt + 1).then(resolve, reject);
+                    }, delayMs);
+                });
             }
-        }
+            return runAttempt(attempt + 1);
+        });
+        return runAttempt(1);
     }
-    exec$ = ({ req$, entry, promote = true, parseFn }) => () => {
+    exec$ = ({ req$, entry, promote = true, parseFn, observe }) => () => {
         promote && this.#activeRequests.update((n) => n + 1);
-        return req$.pipe(map((data) => (parseFn ? parseFn(data) : data)), tap({
+        return req$.pipe(map((httpResponse) => {
+            try {
+                this.opts.onResponse?.(httpResponse);
+            }
+            catch {
+                /* noop */
+            }
+            const payload = observe === 'response'
+                ? httpResponse
+                : httpResponse.body;
+            return parseFn ? parseFn(payload) : payload;
+        }), tap({
             next: (data) => {
                 entry.data = data;
                 entry.status = 'success';
@@ -1265,6 +1333,7 @@ class ResourceStore {
             },
         }), finalize(() => {
             promote && this.#activeRequests.update((n) => Math.max(0, n - 1));
+            entry.controller = undefined;
             this.promoteCurrent(entry, promote);
         }));
     };
@@ -1272,6 +1341,7 @@ class ResourceStore {
         if (!promote) {
             return;
         }
+        entry.promoted = true;
         this.#value.set(entry.data ?? null);
         this.#status.set(entry.status);
         this.#error.set(entry.error);
@@ -1399,37 +1469,18 @@ class PagedQueryStore {
     get sort() {
         return this.#sort();
     }
-    /**
-     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set filters(value) {
         this.#filters.set(value);
     }
-    /**
-     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set query(value) {
         this.#query.set(value);
     }
-    /**
-     * @deprecated Prefer `updatePage(...)`, `fetch(...)`, or `refetchWith(...)`.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set page(value) {
         this.#page.set(value);
     }
-    /**
-     * @deprecated Prefer `updatePageSize(...)`.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set pageSize(value) {
         this.#pageSize.set(value);
     }
-    /**
-     * @deprecated Managed by transport responses. Direct assignment should be treated as legacy.
-     */
     set totalElements(value) {
         this.#totalElements.set(value);
     }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.0",
+  "version": "3.1.0",
   "name": "@reforgium/statum",
   "description": "Signals-first query and data stores for Angular",
   "author": "rtommievich",

package/types/reforgium-statum.d.ts

@@ -1,6 +1,7 @@
 import { AnyType, AnyDict, RestMethods, QueryParams, PageableRequest, PageableResponse } from '@reforgium/internal';
 import * as _angular_core from '@angular/core';
 import { Signal, WritableSignal, EnvironmentProviders, InjectionToken } from '@angular/core';
+import { HttpResponse } from '@angular/common/http';
 import * as _reforgium_statum from '@reforgium/statum';
 
 /**
@@ -182,7 +183,7 @@ declare class Serializer<EntityType extends DataType> {
      * @param obj source object
      * @returns a flat dictionary with string/primitive values
      */
-    serialize(obj: EntityType): SerializedType;
+    serialize(obj: EntityType, _seen?: WeakSet<object>): SerializedType;
     /**
      * Parse serialized data into a domain object.
      *
@@ -283,13 +284,17 @@ declare const storageStrategy: <Key = string, Type extends AnyType = AnyDict>(st
 /**
  * Object for request body (payload).
  * Commonly used with POST/PUT/PATCH/DELETE.
+  * `FormData`, `Blob`, and `ArrayBuffer` are passed through as-is without serialization.
  */
-type PayloadData = AnyDict;
+type PayloadData = AnyDict | FormData | Blob | ArrayBuffer;
 /**
- * Simple parameters dictionary (string/number).
- * Suitable for path params and query.
+ * Simple path parameters dictionary (string/number).
  */
 type SimpleDict = Record<string, string | number>;
+/**
+ * Query parameters dictionary with scalar and array support.
+ */
+type QueryDict = Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>;
 /**
  * Resource status in `ResourceStore`:
  * - `idle`    — not loaded yet
@@ -310,6 +315,11 @@ type RetryConfig = {
     attempts?: number;
     delayMs?: number;
     backoff?: RetryBackoff;
+    /**
+     * Add ±25% random jitter to the retry delay to avoid synchronized retries
+     * across multiple clients hitting the same endpoint simultaneously.
+     */
+    jitter?: boolean;
     shouldRetry?: (error: unknown, attempt: number) => boolean;
 };
 /**
@@ -347,6 +357,12 @@ type ResourceStoreOptions = {
     retry?: RetryConfig;
     /** Trace hook for request/cache lifecycle events. */
     onTrace?: (event: ResourceTraceEvent) => void;
+    /**
+     * Side-effect hook called with the full `HttpResponse` for every completed request.
+     * Useful for reading response headers (e.g. `X-Total-Count`, `Link`, correlation IDs).
+     * Errors thrown here are silently swallowed.
+     */
+    onResponse?: (response: HttpResponse<unknown>) => void;
     serializer?: Partial<SerializerConfig>;
 };
 /**
@@ -355,7 +371,7 @@ type ResourceStoreOptions = {
  * - `query`   — query string parameters
  * - `payload` — request body (for mutations)
  */
-type CallArgs<Params extends SimpleDict = SimpleDict, Query extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData> = {
+type CallArgs<Params extends SimpleDict = SimpleDict, Query extends QueryDict = QueryDict, Payload extends PayloadData = PayloadData> = {
     params?: Params;
     query?: Query;
     payload?: Payload;
@@ -385,6 +401,12 @@ type CallConfig<Response, Type> = {
      * - 'arraybuffer' - response as an ArrayBuffer
      */
     responseType?: 'json' | 'text' | 'blob' | 'arraybuffer';
+    /**
+     * Controls what is passed to `parseResponse`:
+     * - `'body'` (default) — receives the response body (`Response`)
+     * - `'response'` — receives the full `HttpResponse<Response>` (headers, status, body)
+     */
+    observe?: 'body' | 'response';
     /**
      * Custom response parser.
      * Allows converting server `Response` to the domain type `Type`.
@@ -481,7 +503,7 @@ declare class ResourceStore<Data> {
      * @param cfg  Call settings (strategy, ttlMs, revalidate, parseResponse, delay, delayMode, dedupe, promote)
      * @returns Deserialized `Data`
      */
-    get<Param extends SimpleDict = SimpleDict, Query extends PayloadData = PayloadData, Response extends AnyType = Data>(args: CallArgs<Param, Query, never>, cfg?: GetCallConfig<Response, Data>): Promise<Data>;
+    get<Param extends SimpleDict = SimpleDict, Query extends QueryDict = QueryDict, Response extends AnyType = Data>(args: CallArgs<Param, Query, never>, cfg?: GetCallConfig<Response, Data>): Promise<Data>;
     /**
      * POST request.
      *
@@ -489,7 +511,7 @@ declare class ResourceStore<Data> {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    post<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends PayloadData = PayloadData, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Payload>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    post<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends QueryDict = QueryDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Payload>, cfg?: CallConfig<Response, Response>): Promise<Response>;
     /**
      * PUT request (full resource update).
      *
@@ -497,7 +519,7 @@ declare class ResourceStore<Data> {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    put<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends SimpleDict = SimpleDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Partial<Payload>>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    put<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends QueryDict = QueryDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Partial<Payload>>, cfg?: CallConfig<Response, Response>): Promise<Response>;
     /**
      * PATCH request (partial update).
      *
@@ -505,7 +527,7 @@ declare class ResourceStore<Data> {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    patch<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends SimpleDict = SimpleDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Partial<Payload>>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    patch<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends QueryDict = QueryDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Partial<Payload>>, cfg?: CallConfig<Response, Response>): Promise<Response>;
     /**
      * DELETE request.
      *
@@ -513,7 +535,7 @@ declare class ResourceStore<Data> {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    delete<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends SimpleDict = SimpleDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Payload>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    delete<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends QueryDict = QueryDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Payload>, cfg?: CallConfig<Response, Response>): Promise<Response>;
     /**
      * Cancel scheduled/running requests for a specific call.
      *
@@ -521,7 +543,7 @@ declare class ResourceStore<Data> {
      * @param args   Arguments used to build the URL (params, query)
      * @param reason Cancellation reason (optional)
      */
-    abort<Param extends SimpleDict = SimpleDict, Query extends PayloadData = PayloadData>(method: RestMethods, args: CallArgs<Param, Query>, reason?: string | Error): void;
+    abort<Param extends SimpleDict = SimpleDict, Query extends QueryDict = QueryDict>(method: RestMethods, args: CallArgs<Param, Query>, reason?: string | Error): void;
     /**
      * Cancel all scheduled/running requests for this store.
      *
@@ -645,13 +667,16 @@ type SetRouteParamsOptions = {
     abort?: boolean;
 };
 
+type BivariantCallback<Args, Return> = {
+    bivarianceHack(data: Args): Return;
+}['bivarianceHack'];
 /**
  * Configuration for the paginated data store.
  *
  * Controls request method, page cache, debounce delay, concurrency policy, and
  * request/response transformations.
  */
-type PagedQueryStoreConfig<ItemsType extends object, FilterType = unknown> = {
+type PagedQueryStoreConfig<ItemsType extends object, FilterType extends AnyDict = AnyDict> = {
     /** Optional base URL prepended to the route before the request is sent. */
     baseUrl?: string;
     /** Transport HTTP method: `GET`/`POST`/`PATCH`/`PUT`/`DELETE`. Defaults to global config or `POST`. */
@@ -666,9 +691,9 @@ type PagedQueryStoreConfig<ItemsType extends object, FilterType = unknown> = {
     debounceTime?: number;
     /** Concurrency policy for overlapping requests. Defaults to `latest-wins`. */
     concurrency?: PagedQueryConcurrency;
-    /** Initial pagination params. `page` is required. */
+    /** Initial pagination params. Omitted `page` defaults to `0`. */
     presetQuery?: {
-        page: number;
+        page?: number;
         pageSize?: number;
     };
     /** Initial filters. Will be sent with the first request. */
@@ -680,7 +705,7 @@ type PagedQueryStoreConfig<ItemsType extends object, FilterType = unknown> = {
      * Useful for mapping `page/pageSize` and selected filter fields to API-specific query keys.
      * Returned object can contain nullable values; they are filtered before the transport call.
      */
-    parseRequest?: (data: PageableRequest & Partial<FilterType> & AnyDict) => AnyDict;
+    parseRequest?: BivariantCallback<PageableRequest & Partial<FilterType> & AnyDict, AnyDict>;
     /**
      * Custom parser of API response into unified `PageableResponse<ItemsType>`.
      * Use if the server returns an array or a non-standard structure.
@@ -733,7 +758,7 @@ type PagedQueryStoreProviderConfig = {
  * effect(() => console.log(ds.items(), ds.loading()));
  * ```
  */
-declare class PagedQueryStore<ItemsType extends object, FilterType = unknown> {
+declare class PagedQueryStore<ItemsType extends AnyDict, FilterType extends AnyDict = AnyDict> {
     #private;
     private route;
     config: PagedQueryStoreConfig<ItemsType, FilterType>;
@@ -774,29 +799,10 @@ declare class PagedQueryStore<ItemsType extends object, FilterType = unknown> {
     get totalElements(): number;
     /** Current sort rules. */
     get sort(): QuerySortRule[];
-    /**
-     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set filters(value: Partial<FilterType>);
-    /**
-     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set query(value: AnyDict);
-    /**
-     * @deprecated Prefer `updatePage(...)`, `fetch(...)`, or `refetchWith(...)`.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set page(value: number);
-    /**
-     * @deprecated Prefer `updatePageSize(...)`.
-     * Direct state mutation bypasses request semantics and should be treated as legacy.
-     */
     set pageSize(value: number);
-    /**
-     * @deprecated Managed by transport responses. Direct assignment should be treated as legacy.
-     */
     set totalElements(value: number);
     /**
      * Fetch data with explicit filters and query params from the first page.