@reforgium/statum 3.1.6 → 3.2.0

package/CHANGELOG.md

@@ -1,39 +1,59 @@
-## [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:
-- `PagedQueryStore`: page cache is now invalidated when `routeParams` change even if `reset: false` is used, so long-lived singleton-like stores do not replay cached pages from the previous logical dataset/session after a screen remount or route-context change
-- `PagedQueryStore.updateConfig(...)` / `copy(...)`: cached page window is now cleared before transport reconfiguration so reused source instances do not leak stale buffered pages into `@reforgium/data-grid` source mode
-
-### Test:
-- added regression coverage for cache invalidation on route-param session changes without store destruction
-
----
-
-## [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
+## [3.2.0]: 2026-04-24
+
+### Feat:
+- `DictStore`: added `autoLoad: 'onDemand'` and `ensureLoaded()` for controlled lazy startup; dictionaries can now stay passive on construction and fetch only when a consumer explicitly needs them
+- `DictStore`: added `autoLoad: 'onAccess'` as an explicitly dirty opt-in mode for UI consumers that want the first read of `items()` / `options()` to lazily schedule loading
+- `DictStoreProviderConfig`: added `defaultAutoLoad` so the default startup policy can be set once at provider level instead of repeating `autoLoad` on every dictionary instance
+
+### Fix:
+- `DictStore`: `ttlMs` now enables stale-cache revalidation by default when `revalidate` is omitted; stale dictionaries no longer look like they have TTL configured while silently skipping refresh
+- `DictStore`: stale-cache refresh now depends only on `ttlMs`; deprecated `revalidate` no longer changes runtime behavior, so TTL-based freshness is no longer split across two partially overlapping flags
+
+### Test:
+- added regression coverage for deprecated `revalidate: false` compatibility, on-demand loading, and on-access lazy activation
+
+### Docs:
+- `README`: clarified that `ttlMs` implies background revalidation unless `revalidate` is set to `false` explicitly
+- `README`: documented `autoLoad: 'onDemand'`, `autoLoad: 'onAccess'`, `ensureLoaded()`, provider-level `defaultAutoLoad`, and the deprecation of `revalidate`
+
+---
+
+## [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:
+- `PagedQueryStore`: page cache is now invalidated when `routeParams` change even if `reset: false` is used, so long-lived singleton-like stores do not replay cached pages from the previous logical dataset/session after a screen remount or route-context change
+- `PagedQueryStore.updateConfig(...)` / `copy(...)`: cached page window is now cleared before transport reconfiguration so reused source instances do not leak stale buffered pages into `@reforgium/data-grid` source mode
+
+### Test:
+- added regression coverage for cache invalidation on route-param session changes without store destruction
+
+---
+
+## [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

@@ -616,17 +616,60 @@ 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',
-});
+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.
+Use `fixed: true` when the dataset is small enough to keep locally and you want immediate repeated searches without extra network calls.
+
+`DictStore` cache freshness notes:
+
+- `ttlMs` marks persisted dictionary cache as stale after the configured window
+- stale cache is refreshed automatically when `ttlMs` is set
+- `revalidate` is deprecated and no longer changes runtime behavior
+- storage `updatedAt` changes when cache is actually persisted again, not just because wall-clock time passed
+
+For controlled lazy startup, use `autoLoad: 'onDemand'` and trigger the first fetch explicitly:
+
+```ts
+const countries = new DictStore<Country>('/api/dictionaries/countries', 'countries', {
+  fixed: true,
+  autoLoad: 'onDemand',
+});
+
+countries.ensureLoaded(); // first request only when the UI actually needs the dictionary
+```
+
+There is also a dirtier opt-in mode for select-like consumers that want loading to start on the first read:
+
+```ts
+const countries = new DictStore<Country>('/api/dictionaries/countries', 'countries', {
+  fixed: true,
+  autoLoad: 'onAccess',
+});
+
+countries.options(); // first read schedules loading lazily
+```
+
+Use `onAccess` only when you explicitly accept read-triggered loading semantics. It is guarded against same-turn request storms, but it is still intentionally less pure than `onDemand`.
+
+The same policy can be moved to the global provider:
+
+```ts
+provideStatum({
+  dict: {
+    defaultAutoLoad: 'onDemand',
+  },
+});
+```
+
+`ensureLoaded()` is not required for every `DictStore`. It is only needed when the effective auto-load mode is `'onDemand'` and you want the first fetch to happen explicitly. In `true`, `false`, or `'whenEmpty'` modes it remains an optional manual trigger.
 
 ### Normalize Paged Data For Detail Mutations
 

package/fesm2022/reforgium-statum.mjs

@@ -1296,9 +1296,10 @@ class DictStore {
     storage;
     metaStorage;
     ttlMs;
-    revalidate;
+    accessAutoLoadMode;
     cacheUpdatedAt = signal(null, ...(ngDevMode ? [{ debugName: "cacheUpdatedAt" }] : /* istanbul ignore next */ []));
     presetFilters = {};
+    accessLoadQueued = false;
     /**
      * Search text.
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
@@ -1315,6 +1316,7 @@ class DictStore {
      * Source — local cache (fixed=true) or data from `PagedQueryStore`.
      */
     items = computed(() => {
+        this.maybeScheduleAccessLoad();
         const cached = this.cachedItems();
         if (!this.fixed) {
             return this.debouncedSearchText() || !cached.length ? this.#helper.items() : cached;
@@ -1337,7 +1339,7 @@ class DictStore {
      * @param storageKey  key for saving cache in the selected strategy
      * @param cfg         behavior (fixed/search, parsers, label/value keys, cache strategy, etc.)
      */
-    constructor(apiUrl, storageKey, { autoLoad = true, method = this.defaultConfig.defaultRestMethod, presetFilters = this.defaultConfig.defaultPresetFilters, parseResponse, parseRequest, debounceTime = this.defaultConfig.defaultDebounceTime, ttlMs = this.defaultConfig.defaultTtlMs, revalidate = this.defaultConfig.defaultRevalidate ?? false, fixed = true, maxOptionsSize = this.defaultConfig.defaultMaxOptionsSize, labelKey = this.defaultConfig.defaultLabelKey || 'name', valueKey = this.defaultConfig.defaultValueKey || 'code', keyPrefix = this.defaultConfig.defaultPrefix || 're', cacheStrategy = this.defaultConfig.defaultCacheStrategy || 'persist', }) {
+    constructor(apiUrl, storageKey, { autoLoad = this.defaultConfig.defaultAutoLoad ?? true, method = this.defaultConfig.defaultRestMethod, presetFilters = this.defaultConfig.defaultPresetFilters, parseResponse, parseRequest, debounceTime = this.defaultConfig.defaultDebounceTime, ttlMs = this.defaultConfig.defaultTtlMs, fixed = true, maxOptionsSize = this.defaultConfig.defaultMaxOptionsSize, labelKey = this.defaultConfig.defaultLabelKey || 'name', valueKey = this.defaultConfig.defaultValueKey || 'code', keyPrefix = this.defaultConfig.defaultPrefix || 're', cacheStrategy = this.defaultConfig.defaultCacheStrategy || 'persist', }) {
         this.apiUrl = apiUrl;
         this.storageKey = storageKey;
         const searchDebounce = debounceTime ?? 300;
@@ -1352,7 +1354,7 @@ class DictStore {
         });
         this.fixed = fixed;
         this.ttlMs = ttlMs;
-        this.revalidate = revalidate;
+        this.accessAutoLoadMode = autoLoad === 'onAccess';
         this.labelKey = labelKey;
         this.valueKey = valueKey;
         this.maxOptionsSize = maxOptionsSize;
@@ -1414,6 +1416,16 @@ class DictStore {
         this.searchText.set(name);
         this.filters.set(filters);
     };
+    /**
+     * Explicitly arms the store and loads data only when it is actually needed.
+     *
+     * Useful for dropdown/popup flows where eager constructor-time requests would
+     * create too many parallel dictionary loads.
+     */
+    ensureLoaded = (filters = this.filters()) => {
+        this._armed.set(true);
+        this.filters.set(filters);
+    };
     /**
      * Find display label by value (typically for reverse binding).
      * @returns label string or `undefined` if not found
@@ -1538,17 +1550,45 @@ class DictStore {
     setAutoload(autoLoad) {
         if (autoLoad === 'whenEmpty') {
             const isEmpty = !this.cachedItems().length;
-            this._armed.set(isEmpty || this.shouldRevalidateCache());
+            this._armed.set(isEmpty || this.isCacheStale());
+            return;
+        }
+        if (autoLoad === 'onDemand' || autoLoad === 'onAccess') {
+            this._armed.set(false);
+            return;
         }
         else {
             this._armed.set(autoLoad);
         }
     }
     shouldFetchFixedCache() {
-        return !this.cachedItems().length || this.shouldRevalidateCache();
+        return !this.cachedItems().length || this.isCacheStale();
     }
-    shouldRevalidateCache() {
-        return this.revalidate && this.isCacheStale();
+    maybeScheduleAccessLoad() {
+        if (!this.accessAutoLoadMode || this._armed() || this.accessLoadQueued) {
+            return;
+        }
+        if (!this.shouldFetchOnAccessRead()) {
+            return;
+        }
+        this.accessLoadQueued = true;
+        // Note: this is an intentionally dirty opt-in mode.
+        // We never mutate `_armed` synchronously inside `computed()`, because reads should stay pure by default.
+        // Instead, `autoLoad: 'onAccess'` schedules a single deferred activation after the first read of
+        // `items()` / `options()`. This keeps the hack isolated and prevents request storms from repeated reads
+        // during the same render/effect turn.
+        queueMicrotask(() => {
+            this.accessLoadQueued = false;
+            if (!this._armed() && this.shouldFetchOnAccessRead()) {
+                this.ensureLoaded();
+            }
+        });
+    }
+    shouldFetchOnAccessRead() {
+        if (this.fixed) {
+            return this.shouldFetchFixedCache();
+        }
+        return this.#helper.items().length === 0 && !this.cachedItems().length;
     }
     isCacheStale() {
         if (!this.cachedItems().length) {

package/package.json

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

package/types/reforgium-statum.d.ts

@@ -644,8 +644,16 @@ type DictStoreConfig<ItemsType extends object> = {
     keyPrefix?: string;
     /** Initial filters (added to the first request/filtering). */
     presetFilters?: Record<string, string>;
-    /** Autoload data on initialization (`true` by default). */
-    autoLoad?: boolean | 'whenEmpty';
+    /**
+     * Autoload data on initialization (`true` by default).
+     *
+     * - `true`: arm immediately on construction
+     * - `false`: stay passive until `search(...)` or `ensureLoaded()`
+     * - `'whenEmpty'`: arm on init only when cache is empty or stale
+     * - `'onDemand'`: never arm on init; load only after an explicit `ensureLoaded()` / `search(...)`
+     * - `'onAccess'`: dirty opt-in mode; first read of `items()` / `options()` lazily schedules loading
+     */
+    autoLoad?: boolean | 'whenEmpty' | 'onDemand' | 'onAccess';
     /**
      * Custom mapper of pagination/sort request into query params.
      * Useful if the API expects non-standard field names.
@@ -662,7 +670,10 @@ type DictStoreConfig<ItemsType extends object> = {
     debounceTime?: number;
     /** Cache freshness window (ms). Undefined means restored cache does not expire. */
     ttlMs?: number;
-    /** When cache is stale, keep visible items and refresh them in the background. */
+    /**
+     * @deprecated `DictStore` now revalidates stale cache whenever `ttlMs` is set.
+     * Pass `ttlMs: undefined` to disable time-based refresh semantics entirely.
+     */
     revalidate?: boolean;
     /** Maximum number of options exposed (truncates `options`). */
     maxOptionsSize?: number;
@@ -708,13 +719,18 @@ type DictStoreProviderConfig = {
     defaultPrefix?: string;
     /** Initial filters (added to the first request/filtering). */
     defaultPresetFilters?: DictStoreConfig<AnyType>['presetFilters'];
+    /** Default autoload policy for dictionary stores. */
+    defaultAutoLoad?: DictStoreConfig<AnyType>['autoLoad'];
     /** Transport method for fetching the dictionary. Defaults to 'POST'. */
     defaultRestMethod?: DictStoreConfig<AnyType>['method'];
     /** Debounce delay before request (ms) — for frequent input/search. */
     defaultDebounceTime?: DictStoreConfig<AnyType>['debounceTime'];
     /** Cache freshness window (ms). Undefined means restored cache does not expire. */
     defaultTtlMs?: DictStoreConfig<AnyType>['ttlMs'];
-    /** When cache is stale, keep visible items and refresh them in the background. */
+    /**
+     * @deprecated `DictStore` now revalidates stale cache whenever `defaultTtlMs` is set.
+     * Keep this field only for backward compatibility.
+     */
     defaultRevalidate?: DictStoreConfig<AnyType>['revalidate'];
     /** Maximum number of options exposed (truncates `options`). */
     defaultMaxOptionsSize?: DictStoreConfig<AnyType>['maxOptionsSize'];
@@ -760,9 +776,10 @@ declare class DictStore<Type extends AnyDict> {
     private readonly storage?;
     private readonly metaStorage?;
     private readonly ttlMs?;
-    private readonly revalidate;
+    private readonly accessAutoLoadMode;
     private readonly cacheUpdatedAt;
     private readonly presetFilters;
+    private accessLoadQueued;
     /**
      * Search text.
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
@@ -794,7 +811,7 @@ declare class DictStore<Type extends AnyDict> {
      * @param storageKey  key for saving cache in the selected strategy
      * @param cfg         behavior (fixed/search, parsers, label/value keys, cache strategy, etc.)
      */
-    constructor(apiUrl: string, storageKey: string, { autoLoad, method, presetFilters, parseResponse, parseRequest, debounceTime, ttlMs, revalidate, fixed, maxOptionsSize, labelKey, valueKey, keyPrefix, cacheStrategy, }: DictStoreConfig<Type>);
+    constructor(apiUrl: string, storageKey: string, { autoLoad, method, presetFilters, parseResponse, parseRequest, debounceTime, ttlMs, fixed, maxOptionsSize, labelKey, valueKey, keyPrefix, cacheStrategy, }: DictStoreConfig<Type>);
     /** Restore cache from the selected storage (`persist`/`session`/`lru`/`memory`). */
     restoreCache(): void;
     clearCache(): void;
@@ -803,6 +820,13 @@ declare class DictStore<Type extends AnyDict> {
      * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
      */
     search: (name?: string, filters?: AnyDict) => void;
+    /**
+     * Explicitly arms the store and loads data only when it is actually needed.
+     *
+     * Useful for dropdown/popup flows where eager constructor-time requests would
+     * create too many parallel dictionary loads.
+     */
+    ensureLoaded: (filters?: AnyDict) => void;
     /**
      * Find display label by value (typically for reverse binding).
      * @returns label string or `undefined` if not found
@@ -829,7 +853,8 @@ declare class DictStore<Type extends AnyDict> {
     private keyOf;
     private setAutoload;
     private shouldFetchFixedCache;
-    private shouldRevalidateCache;
+    private maybeScheduleAccessLoad;
+    private shouldFetchOnAccessRead;
     private isCacheStale;
     private metaKey;
 }