@reforgium/statum 3.1.3 → 3.1.4

package/CHANGELOG.md

@@ -1,4 +1,15 @@
-## [3.1.3]: 2026-04-06
+## [3.1.4]: 2026-04-10
+
+### Fix:
+- `PagedQueryStore`: `totalElements` now preserves `undefined` when `parseResponse` omits the field, so unknown-total datasets stay open-ended instead of being forced back to `0` after reset/refetch.
+- `PagedQueryStore`: `refetchWith(...)` now treats real filters/query/sort changes as dataset replacement, clearing page cache/items and bumping `version` so `@reforgium/data-grid` infinity buffers do not keep stale rows after an empty successful response.
+
+### Test:
+- added regression coverage for omitted `totalElements`, reset/refetch clearing, and empty-result unknown-total flows
+
+---
+
+## [3.1.3]: 2026-04-06
 
 ### Fix:
 - `PagedQueryStore`: all public state getters (`filters`, `query`, `page`, `pageSize`, `totalElements`, `sort`) and direct `#routeParams` reads now wrap the underlying signal in `untracked()`; previously calling `fetch()`, `refetchWith()`, `updatePage()`, `setRouteParams()`, etc. from inside an Angular `effect()` or `computed()` would inadvertently subscribe the reactive context to internal state signals, causing cascading re-runs; reactive subscriptions remain available exclusively through the `*State` readonly signals (`filtersState`, `sortState`, `pageState`, …)

package/README.md

@@ -345,7 +345,7 @@ Lightweight store for server-side pagination with filtering, dynamic query param
 | 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                  |
+| totalElements  | `number \| undefined`     | Total items on server, if known        |
 | filters        | `Partial<F>`              | Active filters                         |
 | query          | `Record<string, unknown>` | Active query params                    |
 | sort           | `ReadonlyArray<{ sort: string; order: 'asc' \| 'desc' }>` | Active sort state |
@@ -396,7 +396,7 @@ Concurrency can be configured per store:
 | 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 |
+| refetchWith    | no         | conditional | Reloads current state; when filters/query/sort actually change, resets to page `0` and replaces the dataset |
 | 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`                 |
@@ -422,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.
 
-`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.
+`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. `totalElements` may be `undefined` when the backend does not report a total.
 
 ### PagedQueryStore + DataGrid source mode
 

package/fesm2022/reforgium-statum.mjs

@@ -277,10 +277,10 @@ class KeyedScheduler {
 class ResourceStore {
     http = inject(HttpClient);
     serializer;
-    #value = signal(null, ...(ngDevMode ? [{ debugName: "#value" }] : []));
-    #status = signal('idle', ...(ngDevMode ? [{ debugName: "#status" }] : []));
-    #error = signal(null, ...(ngDevMode ? [{ debugName: "#error" }] : []));
-    #activeRequests = signal(0, ...(ngDevMode ? [{ debugName: "#activeRequests" }] : []));
+    #value = signal(null, ...(ngDevMode ? [{ debugName: "#value" }] : /* istanbul ignore next */ []));
+    #status = signal('idle', ...(ngDevMode ? [{ debugName: "#status" }] : /* istanbul ignore next */ []));
+    #error = signal(null, ...(ngDevMode ? [{ debugName: "#error" }] : /* istanbul ignore next */ []));
+    #activeRequests = signal(0, ...(ngDevMode ? [{ debugName: "#activeRequests" }] : /* istanbul ignore next */ []));
     /**
      * Current resource value.
      * Returns `null` if no data yet or the request failed.
@@ -298,7 +298,7 @@ class ResourceStore {
      * Convenience loading flag: `true` when `loading` or `stale`.
      * Useful for spinners and disabling buttons.
      */
-    loading = computed(() => this.#activeRequests() > 0 || this.#status() === 'stale', ...(ngDevMode ? [{ debugName: "loading" }] : []));
+    loading = computed(() => this.#activeRequests() > 0 || this.#status() === 'stale', ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
     routes;
     opts;
     maxEntries;
@@ -839,22 +839,22 @@ class PagedQueryStore {
     #transport;
     #cache;
     /** Current page data (reactive). */
-    items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : []));
+    items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : /* istanbul ignore next */ []));
     /** Merged cache of pages (flat list) handy for search/export. */
-    cached = signal([], ...(ngDevMode ? [{ debugName: "cached" }] : []));
+    cached = signal([], ...(ngDevMode ? [{ debugName: "cached" }] : /* istanbul ignore next */ []));
     /** Loading flag of the current operation. */
-    loading = signal(false, ...(ngDevMode ? [{ debugName: "loading" }] : []));
+    loading = signal(false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
     /** Last request error (if any). */
-    error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : []));
+    error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
     /** Increments when the current dataset is reset/replaced. Useful for external consumers with local buffers. */
-    version = signal(0, ...(ngDevMode ? [{ debugName: "version" }] : []));
-    #page = signal(0, ...(ngDevMode ? [{ debugName: "#page" }] : []));
-    #pageSize = signal(20, ...(ngDevMode ? [{ debugName: "#pageSize" }] : []));
-    #totalElements = signal(0, ...(ngDevMode ? [{ debugName: "#totalElements" }] : []));
-    #filters = signal({}, ...(ngDevMode ? [{ debugName: "#filters" }] : []));
-    #query = signal({}, ...(ngDevMode ? [{ debugName: "#query" }] : []));
-    #sort = signal([], ...(ngDevMode ? [{ debugName: "#sort" }] : []));
-    #routeParams = signal({}, ...(ngDevMode ? [{ debugName: "#routeParams" }] : []));
+    version = signal(0, ...(ngDevMode ? [{ debugName: "version" }] : /* istanbul ignore next */ []));
+    #page = signal(0, ...(ngDevMode ? [{ debugName: "#page" }] : /* istanbul ignore next */ []));
+    #pageSize = signal(20, ...(ngDevMode ? [{ debugName: "#pageSize" }] : /* istanbul ignore next */ []));
+    #totalElements = signal(undefined, ...(ngDevMode ? [{ debugName: "#totalElements" }] : /* istanbul ignore next */ []));
+    #filters = signal({}, ...(ngDevMode ? [{ debugName: "#filters" }] : /* istanbul ignore next */ []));
+    #query = signal({}, ...(ngDevMode ? [{ debugName: "#query" }] : /* istanbul ignore next */ []));
+    #sort = signal([], ...(ngDevMode ? [{ debugName: "#sort" }] : /* istanbul ignore next */ []));
+    #routeParams = signal({}, ...(ngDevMode ? [{ debugName: "#routeParams" }] : /* istanbul ignore next */ []));
     pageState = this.#page.asReadonly();
     pageSizeState = this.#pageSize.asReadonly();
     totalElementsState = this.#totalElements.asReadonly();
@@ -891,7 +891,7 @@ class PagedQueryStore {
     get pageSize() {
         return untracked(this.#pageSize);
     }
-    /** Total number of elements reported by the server. */
+    /** Total number of elements reported by the server, or `undefined` when the total is unknown. */
     get totalElements() {
         return untracked(this.#totalElements);
     }
@@ -931,6 +931,11 @@ class PagedQueryStore {
         const nextFilters = filters == null ? this.filters : { ...this.filters, ...filters };
         const nextQuery = query == null ? this.query : mergeQueryParams(this.query, query);
         const nextSort = sort == null ? this.sort : this.normalizeSort(sort);
+        const shouldResetDataset = !deepEqual(this.filters, nextFilters) || !deepEqual(this.query, nextQuery) || !deepEqual(this.sort, nextSort);
+        if (shouldResetDataset) {
+            this.resetDataset();
+            return this.#fetchItems({ page: 0, filters: nextFilters, query: nextQuery, sort: nextSort });
+        }
         return this.#fetchItems({ filters: nextFilters, query: nextQuery, sort: nextSort });
     }
     /**
@@ -1169,7 +1174,7 @@ class PagedQueryStore {
     }
     resetDataset() {
         this.page = 0;
-        this.totalElements = 0;
+        this.totalElements = undefined;
         this.#cache.clear();
         this.cached.set([]);
         this.items.set([]);
@@ -1285,19 +1290,19 @@ class DictStore {
     metaStorage;
     ttlMs;
     revalidate;
-    cacheUpdatedAt = signal(null, ...(ngDevMode ? [{ debugName: "cacheUpdatedAt" }] : []));
+    cacheUpdatedAt = signal(null, ...(ngDevMode ? [{ debugName: "cacheUpdatedAt" }] : /* istanbul ignore next */ []));
     presetFilters = {};
     /**
      * Search text.
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
      */
-    searchText = signal('', ...(ngDevMode ? [{ debugName: "searchText" }] : []));
+    searchText = signal('', ...(ngDevMode ? [{ debugName: "searchText" }] : /* istanbul ignore next */ []));
     debouncedSearchText;
     /**
      * Additional filters for server request (or presets).
      */
-    filters = signal({}, ...(ngDevMode ? [{ debugName: "filters" }] : []));
-    cachedItems = signal([], ...(ngDevMode ? [{ debugName: "cachedItems" }] : []));
+    filters = signal({}, ...(ngDevMode ? [{ debugName: "filters" }] : /* istanbul ignore next */ []));
+    cachedItems = signal([], ...(ngDevMode ? [{ debugName: "cachedItems" }] : /* istanbul ignore next */ []));
     /**
      * Current list of dictionary items.
      * Source — local cache (fixed=true) or data from `PagedQueryStore`.
@@ -1308,7 +1313,7 @@ class DictStore {
             return this.debouncedSearchText() || !cached.length ? this.#helper.items() : cached;
         }
         return cached.length ? this.filterLocal() : this.#helper.items();
-    }, ...(ngDevMode ? [{ debugName: "items" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "items" }] : /* istanbul ignore next */ []));
     /**
      * Ready-to-use dropdown options: `{ label, value }`.
      * Respects `maxOptionsSize` for truncating the list.
@@ -1316,9 +1321,9 @@ class DictStore {
     options = computed(() => {
         const options = this.items().map((it) => ({ label: String(it[this.labelKey] ?? ''), value: it[this.valueKey] }));
         return this.maxOptionsSize ? options.slice(0, this.maxOptionsSize) : options;
-    }, ...(ngDevMode ? [{ debugName: "options" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
     _lastPromise = null;
-    _armed = signal(false, ...(ngDevMode ? [{ debugName: "_armed" }] : []));
+    _armed = signal(false, ...(ngDevMode ? [{ debugName: "_armed" }] : /* istanbul ignore next */ []));
     // todo add i18n support
     /**
      * @param apiUrl      dictionary endpoint (e.g., `'/api/dicts/countries'`)
@@ -1574,8 +1579,8 @@ class DictLocalStore {
      * Represents the full, unfiltered list of dictionary entries.
      * Used as the base data set for search and option generation.
      */
-    items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : []));
-    #draftItems = signal([], ...(ngDevMode ? [{ debugName: "#draftItems" }] : []));
+    items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : /* istanbul ignore next */ []));
+    #draftItems = signal([], ...(ngDevMode ? [{ debugName: "#draftItems" }] : /* istanbul ignore next */ []));
     /**
      * Computed list of options in `{ label, value }` format.
      *
@@ -1590,7 +1595,7 @@ class DictLocalStore {
             value: it[this.valueKey],
         }));
         return this.maxOptionsSize ? options.slice(0, this.maxOptionsSize) : options;
-    }, ...(ngDevMode ? [{ debugName: "options" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
     labelKey;
     valueKey;
     maxOptionsSize;
@@ -1675,14 +1680,14 @@ class DictLocalStore {
 class EntityStore {
     idKey;
     sortIds;
-    byId = signal({}, ...(ngDevMode ? [{ debugName: "byId" }] : []));
-    ids = signal([], ...(ngDevMode ? [{ debugName: "ids" }] : []));
+    byId = signal({}, ...(ngDevMode ? [{ debugName: "byId" }] : /* istanbul ignore next */ []));
+    ids = signal([], ...(ngDevMode ? [{ debugName: "ids" }] : /* istanbul ignore next */ []));
     items = computed(() => {
         const byId = this.byId();
         return this.ids()
             .map((id) => byId[String(id)])
             .filter((item) => item !== undefined);
-    }, ...(ngDevMode ? [{ debugName: "items" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "items" }] : /* istanbul ignore next */ []));
     constructor(config) {
         this.idKey = config.idKey;
         this.sortIds = config.sortIds;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.1.3",
+  "version": "3.1.4",
   "name": "@reforgium/statum",
   "description": "Signals-first API state and query stores for Angular",
   "author": "rtommievich",

package/types/reforgium-statum.d.ts

@@ -505,7 +505,7 @@ declare class PagedQueryStore<ItemsType extends AnyDict, FilterType extends AnyD
     version: WritableSignal<number>;
     readonly pageState: _angular_core.Signal<number>;
     readonly pageSizeState: _angular_core.Signal<number>;
-    readonly totalElementsState: _angular_core.Signal<number>;
+    readonly totalElementsState: _angular_core.Signal<number | undefined>;
     readonly filtersState: _angular_core.Signal<Partial<FilterType>>;
     readonly queryState: _angular_core.Signal<AnyDict>;
     readonly sortState: _angular_core.Signal<QuerySortRule[]>;
@@ -523,15 +523,15 @@ declare class PagedQueryStore<ItemsType extends AnyDict, FilterType extends AnyD
     get page(): number;
     /** Default page size. */
     get pageSize(): number;
-    /** Total number of elements reported by the server. */
-    get totalElements(): number;
+    /** Total number of elements reported by the server, or `undefined` when the total is unknown. */
+    get totalElements(): number | undefined;
     /** Current sort rules. */
     get sort(): QuerySortRule[];
     set filters(value: Partial<FilterType>);
     set query(value: AnyDict);
     set page(value: number);
     set pageSize(value: number);
-    set totalElements(value: number);
+    set totalElements(value: number | undefined);
     /**
      * Fetch data with explicit filters and query params from the first page.
      * Replaces legacy `setFilters`.