@reforgium/statum 3.1.5 → 3.1.6

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [3.1.6]: 2026-04-17
+
+### Fix:
+- `PagedQueryStore`: plain array responses (`T[]`) no longer synthesize `totalElements = data.length`; `parseFlatArray()` now keeps `totalElements` as `undefined` unless the backend or a custom `parseResponse(...)` provides an exact total explicitly
+
+### Test:
+- updated flat-array regression coverage to assert unknown-total semantics instead of the old inferred-length behavior
+
+### Docs:
+- `README`: clarified that bare array responses are treated as unknown-total datasets and that exact totals must come from the backend or a custom `parseResponse(...)`
+
+---
+
 ## [3.1.5]: 2026-04-14
 
 ### Fix:

package/README.md

@@ -336,19 +336,19 @@ Lightweight store for server-side pagination with filtering, dynamic query param
 
 ### State
 
-| Field / Signal | Type                      | Description                            |
-|----------------|---------------------------|----------------------------------------|
-| 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 \| 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 |
+| Field / Signal | Type                                                      | Description                           |
+|----------------|-----------------------------------------------------------|---------------------------------------|
+| 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 \| undefined`                                     | Exact 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                     |
 
 Reactive metadata signals are also available:
 
@@ -368,9 +368,9 @@ Reactive metadata signals are also available:
 | 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                                      |
+| 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)`                                                    |
@@ -393,13 +393,13 @@ Concurrency can be configured per store:
 
 ### Cache behavior
 
-| Method         | Cache read | Cache reset | Notes                                            |
-|----------------|------------|-------------|--------------------------------------------------|
-| fetch          | no         | yes         | Always starts clean from page `0`                |
-| 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`                 |
+| Method         | Cache read | Cache reset | Notes                                                                                                       |
+|----------------|------------|-------------|-------------------------------------------------------------------------------------------------------------|
+| fetch          | no         | yes         | Always starts clean from page `0`                                                                           |
+| 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`                                                                            |
 
 Example:
 
@@ -422,7 +422,9 @@ 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. `totalElements` may be `undefined` when the backend does not report a total.
+`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.
+
+If the transport returns a bare array (`T[]`) instead of a pageable object, `PagedQueryStore` treats it as an unknown-total dataset and keeps `totalElements === undefined`. A plain array does not prove the final dataset size. If your backend knows the exact total, return it explicitly or map the response with `parseResponse(...)`.
 
 ### PagedQueryStore + DataGrid source mode
 
@@ -449,6 +451,8 @@ This works because the store already exposes the expected source contract:
 - `updatePage(...)`
 - `updatePageSize(...)`
 - `updateSort(...)`
+
+When `PagedQueryStore` is fed by a flat-array response without an exact backend total, `totalElements` stays `undefined`. This is intentional: consumers such as `@reforgium/data-grid` can then stay in open-ended paging mode instead of trusting a fake total derived from `data.length`.
 - `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.

package/fesm2022/reforgium-statum.mjs

@@ -1177,7 +1177,7 @@ class PagedQueryStore {
         this.cached.set([]);
     }
     parseFlatArray(data) {
-        return { content: data, totalElements: data.length };
+        return { content: data };
     }
     resetDataset() {
         this.page = 0;

package/package.json

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