@reforgium/statum 3.1.6 → 3.3.0

package/CHANGELOG.md

@@ -1,39 +1,80 @@
-## [3.1.6]: 2026-04-17
+## [3.3.0]: 2026-05-29
 
-### 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
+### Feat:
+- `PagedQueryLocalStore`: added a public local/in-memory counterpart of `PagedQueryStore` with the same page/sort/version surface, so consumer apps can mock paged datasets or work with locally assembled collections without losing `DataGrid` source compatibility
+- `ResourceMockStore`: added a public handler-driven in-memory counterpart of `ResourceStore` with the same `value/status/error/loading` signals and `get/post/put/patch/delete` entry points for API-less feature work and service mocking
 
 ### Test:
-- added regression coverage for cache invalidation on route-param session changes without store destruction
+- added regression coverage for local page slicing, local multi-sort, custom local resolvers, seeded resource reads, cache-first mock reads, and handler-driven mock mutations
 
 ---
 
-## [3.1.4]: 2026-04-10
+## [3.2.1]: 2026-05-11
 
 ### 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
+- `PagedQueryStore`: fixed `parseRequest(...)` input typing to match actual runtime behavior; the hook now explicitly receives pre-serialization sort rules (`QuerySortRule[]`) instead of a transport-level `sort: string | string[]` contract
+
+### Test:
+- added regression coverage proving that `parseRequest(...)` receives object sort rules while the outgoing HTTP query still serializes them as repeated `sort=name,asc` params
+
+---
+
+## [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

@@ -18,11 +18,12 @@ It is not a reduced framework and does not try to replace NgRx-style global even
 - Signals-first API (`signal()` everywhere)
 - API-driven stores (resource / paginated / dictionaries)
 - Normalized entity store (`EntityStore`)
-- Built-in cache strategies (TTL, prefix grouping)
-- Deterministic request lifecycle: loading / error / data
-- Optional transport-level: dedupe, debounce/throttle, abort
-- Unified retry and trace hooks in `ResourceStore`
-- Explicit serialization / deserialization boundary
+- Built-in cache strategies (TTL, prefix grouping)
+- Deterministic request lifecycle: loading / error / data
+- Optional transport-level: dedupe, debounce/throttle, abort
+- Unified retry and trace hooks in `ResourceStore`
+- Public local/mock store counterparts for API-less flows
+- Explicit serialization / deserialization boundary
 
 ## Best Fit
 
@@ -38,13 +39,18 @@ Use `statum` when you need:
 - plain `HttpClient` services that have started to accumulate state logic
 - full application state frameworks where global reducers/effects are too expensive for the problem
 
-`statum` is usually not the right fit when:
+`statum` is usually not the right fit when:
 
 - you need cross-page event sourcing, time-travel tooling, or centralized action logs
 - your app is mostly local UI state with little backend orchestration
-- you want a framework-agnostic data layer
-
----
+- you want a framework-agnostic data layer
+
+For API-less feature work and staged backend delivery:
+
+- use `PagedQueryLocalStore` when the consumer still wants a `PagedQueryStore`-like source for `DataGrid`
+- use `ResourceMockStore` when the consumer wants `ResourceStore`-like signals and CRUD entry points backed by local handlers instead of HTTP
+
+---
 
 ## Installation
 
@@ -616,17 +622,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

@@ -1,7 +1,7 @@
-import { Serializer, fillUrlWithParams, mergeQueryParams, LruCache, deepEqual, isNullable, normalizeSortInput, sortInputToTokens, debounceSignal, storageStrategy } from '@reforgium/internal';
+import { Serializer, fillUrlWithParams, mergeQueryParams, deepEqual, normalizeSortInput, LruCache, isNullable, sortInputToTokens, debounceSignal, storageStrategy } from '@reforgium/internal';
 export { LocalStorage, LruCache, MemoryStorage, Serializer, SerializerFieldError, SessionStorage, storageStrategy } from '@reforgium/internal';
+import { signal, computed, InjectionToken, makeEnvironmentProviders, inject, untracked, EnvironmentInjector, DestroyRef, runInInjectionContext, effect } from '@angular/core';
 import { HttpClient, HttpParams } from '@angular/common/http';
-import { InjectionToken, makeEnvironmentProviders, inject, signal, computed, EnvironmentInjector, DestroyRef, untracked, runInInjectionContext, effect } from '@angular/core';
 import { Subject, filter, timer, merge, map } from 'rxjs';
 import { debounce, tap, throttle, finalize } from 'rxjs/operators';
 
@@ -30,10 +30,6 @@ const createStrictSerializer = (config = {}) => {
     });
 };
 
-// noinspection ES6PreferShortImport
-const STATUM_CONFIG = new InjectionToken('RE_STATUM_CONFIG');
-const provideStatum = (config) => makeEnvironmentProviders([{ provide: STATUM_CONFIG, useValue: config }]);
-
 /**
  * Error thrown when requested data is missing in the cache.
  *
@@ -119,6 +115,170 @@ function stableStringify(value) {
     return String(value);
 }
 
+/**
+ * Lightweight in-memory counterpart of `ResourceStore`.
+ *
+ * It preserves the result-facing API (`value/status/error/loading` + CRUD methods),
+ * but does not try to reproduce transport, retry, or per-key cache internals.
+ */
+class ResourceMockStore {
+    #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 */ []));
+    value = this.#value.asReadonly();
+    status = this.#status.asReadonly();
+    error = this.#error.asReadonly();
+    loading = computed(() => this.#activeRequests() > 0 || this.#status() === 'stale', ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
+    routes;
+    opts;
+    constructor(routes = {}, opts = {}) {
+        this.routes = routes;
+        this.opts = opts;
+        if (opts.seed !== undefined) {
+            this.#value.set(opts.seed);
+            this.#status.set(opts.seed == null ? 'idle' : 'success');
+        }
+    }
+    setValue(value) {
+        this.#value.set(value);
+        this.#status.set(value == null ? 'idle' : 'success');
+        this.#error.set(null);
+    }
+    patchValue(patch) {
+        const current = this.#value();
+        if (!current || typeof current !== 'object') {
+            this.#value.set(patch);
+        }
+        else {
+            this.#value.set({ ...current, ...patch });
+        }
+        this.#status.set('success');
+        this.#error.set(null);
+    }
+    reset(value = this.opts.seed ?? null) {
+        this.#value.set(value);
+        this.#status.set(value == null ? 'idle' : 'success');
+        this.#error.set(null);
+    }
+    get(args, cfg = {}) {
+        const strategy = cfg.strategy ?? 'network-first';
+        if (strategy === 'cache-only' && this.#value() == null && !this.opts.handlers?.GET) {
+            return Promise.reject(new CacheMissError(this.buildUrl('GET', args)));
+        }
+        if (strategy === 'cache-first' && this.#value() != null && !cfg.revalidate) {
+            return Promise.resolve(this.#value());
+        }
+        return this.run('GET', args, async () => {
+            const url = this.buildUrl('GET', args);
+            const handler = this.opts.handlers?.GET;
+            const result = handler
+                ? await handler({ method: 'GET', route: this.routes.GET, url, args, current: this.#value() })
+                : this.#value();
+            if (result == null) {
+                throw new Error('ResourceMockStore GET has no handler result and no current value.');
+            }
+            const parsed = cfg.parseResponse ? cfg.parseResponse(result) : result;
+            this.#value.set(parsed);
+            this.#status.set('success');
+            this.#error.set(null);
+            return parsed;
+        });
+    }
+    post(args, cfg = {}) {
+        return this.runMutation('POST', args, cfg);
+    }
+    put(args, cfg = {}) {
+        return this.runMutation('PUT', args, cfg);
+    }
+    patch(args, cfg = {}) {
+        return this.runMutation('PATCH', args, cfg);
+    }
+    delete(args, cfg = {}) {
+        return this.runMutation('DELETE', args, cfg);
+    }
+    abort() { }
+    abortAll() { }
+    runMutation(method, args, cfg) {
+        return this.run(method, args, async () => {
+            const result = await this.resolveMutation(method, args);
+            const parsed = cfg.parseResponse ? cfg.parseResponse(result) : result;
+            this.#value.set(parsed ?? null);
+            this.#status.set('success');
+            this.#error.set(null);
+            return parsed;
+        });
+    }
+    async resolveMutation(method, args) {
+        const url = this.buildUrl(method, args);
+        const handler = this.opts.handlers?.[method];
+        if (handler) {
+            return handler({
+                method,
+                route: this.routes[method],
+                url,
+                args: args,
+                current: this.#value(),
+            });
+        }
+        if (method === 'DELETE') {
+            return null;
+        }
+        if (method === 'PATCH') {
+            const current = this.#value();
+            const patch = args.payload;
+            if (current && typeof current === 'object' && patch && typeof patch === 'object' && !Array.isArray(patch)) {
+                return { ...current, ...patch };
+            }
+        }
+        return args.payload ?? this.#value();
+    }
+    run(method, args, exec) {
+        const url = this.buildUrl(method, args);
+        const delay = this.opts.delay ?? 0;
+        this.#activeRequests.update((count) => count + 1);
+        this.#status.set(this.#value() == null ? 'loading' : 'stale');
+        this.trace({ type: 'request-start', method, key: url, attempt: 1 });
+        return new Promise((resolve, reject) => {
+            setTimeout(() => {
+                void exec()
+                    .then((result) => {
+                    this.trace({ type: 'request-success', method, key: url });
+                    resolve(result);
+                })
+                    .catch((error) => {
+                    this.#status.set('error');
+                    this.#error.set(error);
+                    this.trace({ type: 'request-error', method, key: url, error });
+                    reject(error);
+                })
+                    .finally(() => {
+                    this.#activeRequests.update((count) => Math.max(0, count - 1));
+                });
+            }, delay);
+        });
+    }
+    buildUrl(method, args) {
+        const template = this.routes[method];
+        if (template == null) {
+            throw new Error(`${method} route not configured`);
+        }
+        return joinUrl(this.opts.baseUrl, fillUrlWithParams(template, args.params));
+    }
+    trace(event) {
+        try {
+            this.opts.onTrace?.(event);
+        }
+        catch {
+            /* noop */
+        }
+    }
+}
+
+// noinspection ES6PreferShortImport
+const STATUM_CONFIG = new InjectionToken('RE_STATUM_CONFIG');
+const provideStatum = (config) => makeEnvironmentProviders([{ provide: STATUM_CONFIG, useValue: config }]);
+
 /**
  * Per-key task scheduler with `debounce`/`throttle` and result deduplication.
  *
@@ -811,6 +971,251 @@ const createResourceProfile = (profile, overrides = {}) => ({
     ...overrides,
 });
 
+/**
+ * Lightweight local counterpart of `PagedQueryStore`.
+ *
+ * It keeps the same result-facing shape needed by consumers and `DataGrid source`,
+ * but resolves pages from an in-memory collection instead of HTTP.
+ */
+class PagedQueryLocalStore {
+    items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : /* istanbul ignore next */ []));
+    cached = signal([], ...(ngDevMode ? [{ debugName: "cached" }] : /* istanbul ignore next */ []));
+    loading = signal(false, ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
+    error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    version = signal(0, ...(ngDevMode ? [{ debugName: "version" }] : /* istanbul ignore next */ []));
+    allItemsState = signal([], ...(ngDevMode ? [{ debugName: "allItemsState" }] : /* istanbul ignore next */ []));
+    pageState = signal(0, ...(ngDevMode ? [{ debugName: "pageState" }] : /* istanbul ignore next */ []));
+    pageSizeState = signal(20, ...(ngDevMode ? [{ debugName: "pageSizeState" }] : /* istanbul ignore next */ []));
+    totalElementsState = signal(undefined, ...(ngDevMode ? [{ debugName: "totalElementsState" }] : /* istanbul ignore next */ []));
+    filtersState = signal({}, ...(ngDevMode ? [{ debugName: "filtersState" }] : /* istanbul ignore next */ []));
+    queryState = signal({}, ...(ngDevMode ? [{ debugName: "queryState" }] : /* istanbul ignore next */ []));
+    sortState = signal([], ...(ngDevMode ? [{ debugName: "sortState" }] : /* istanbul ignore next */ []));
+    routeParamsState = signal({}, ...(ngDevMode ? [{ debugName: "routeParamsState" }] : /* istanbul ignore next */ []));
+    config;
+    prefetchMode;
+    constructor(items = [], config = {}) {
+        this.config = config;
+        this.prefetchMode = config.prefetchMode ?? 'sequential';
+        this.allItemsState.set(items);
+        this.filtersState.set(config.presetFilters ?? {});
+        this.sortState.set(this.normalizeSort(config.presetSort));
+        this.routeParamsState.set(config.presetRouteParams ?? {});
+        this.pageState.set(config.presetQuery?.page ?? 0);
+        this.pageSizeState.set(config.presetQuery?.pageSize ?? 20);
+        void this.refresh();
+    }
+    get page() {
+        return untracked(this.pageState);
+    }
+    get pageSize() {
+        return untracked(this.pageSizeState);
+    }
+    get totalElements() {
+        return untracked(this.totalElementsState);
+    }
+    get filters() {
+        return untracked(this.filtersState);
+    }
+    get query() {
+        return untracked(this.queryState);
+    }
+    get sort() {
+        return untracked(this.sortState);
+    }
+    get routeParams() {
+        return untracked(this.routeParamsState);
+    }
+    set page(value) {
+        this.pageState.set(value);
+    }
+    set pageSize(value) {
+        this.pageSizeState.set(value);
+    }
+    set totalElements(value) {
+        this.totalElementsState.set(value);
+    }
+    set filters(value) {
+        this.filtersState.set(value);
+    }
+    set query(value) {
+        this.queryState.set(value);
+    }
+    setData = (items, opts) => {
+        const nextItems = opts?.replace === false ? [...this.allItemsState(), ...items] : [...items];
+        this.allItemsState.set(nextItems);
+        this.bumpVersion();
+        return this.refresh({ page: 0 });
+    };
+    preload = this.setData;
+    fetch = ({ filters = {}, query = {}, routeParams = {}, sort = this.sort } = {}) => {
+        this.filtersState.set(filters);
+        this.queryState.set(query);
+        this.routeParamsState.set(routeParams);
+        this.sortState.set(this.normalizeSort(sort));
+        this.pageState.set(0);
+        this.bumpVersion();
+        return this.refresh();
+    };
+    refetchWith({ filters, query, sort } = {}) {
+        const nextFilters = filters == null ? this.filters : { ...this.filters, ...filters };
+        const nextQuery = query == null ? this.query : { ...this.query, ...query };
+        const nextSort = sort == null ? this.sort : this.normalizeSort(sort);
+        if (!deepEqual(this.filters, nextFilters) || !deepEqual(this.query, nextQuery) || !deepEqual(this.sort, nextSort)) {
+            this.pageState.set(0);
+            this.bumpVersion();
+        }
+        this.filtersState.set(nextFilters);
+        this.queryState.set(nextQuery);
+        this.sortState.set(nextSort);
+        return this.refresh();
+    }
+    updatePage = (page = this.page, _options) => {
+        this.pageState.set(typeof page === 'number' ? page : page.page);
+        return this.refresh();
+    };
+    updatePageSize = (size = this.pageSize) => {
+        this.pageSizeState.set(size);
+        this.pageState.set(0);
+        this.bumpVersion();
+        return this.refresh();
+    };
+    updateByOffset = ({ page: pageNum, first = 0, rows = 0 } = {}, { query = this.query, sort = this.sort } = {}) => {
+        const page = (pageNum ?? (first && rows && Math.floor(first / rows))) || 0;
+        this.pageState.set(page);
+        this.pageSizeState.set(rows || this.pageSize);
+        this.queryState.set(query);
+        this.sortState.set(this.normalizeSort(sort));
+        return this.refresh();
+    };
+    setSort = (sort) => {
+        this.sortState.set(this.normalizeSort(sort));
+    };
+    updateSort = (sort) => this.updateSorts(sort ? [sort] : []);
+    updateSorts = (sort) => {
+        this.sortState.set(this.normalizeSort(sort));
+        this.pageState.set(0);
+        this.bumpVersion();
+        return this.refresh();
+    };
+    setRouteParams = (params = {}, opts = {}) => {
+        this.routeParamsState.set(params);
+        if (opts.reset) {
+            this.pageState.set(0);
+            this.bumpVersion();
+        }
+    };
+    updateConfig = (config) => {
+        this.config = { ...this.config, ...config };
+        this.prefetchMode = this.config.prefetchMode ?? 'sequential';
+        if (config.presetFilters) {
+            this.filtersState.set(config.presetFilters);
+        }
+        if (config.presetSort) {
+            this.sortState.set(this.normalizeSort(config.presetSort));
+        }
+        if (config.presetRouteParams) {
+            this.routeParamsState.set(config.presetRouteParams);
+        }
+        if (config.presetQuery?.page != null) {
+            this.pageState.set(config.presetQuery.page);
+        }
+        if (config.presetQuery?.pageSize != null) {
+            this.pageSizeState.set(config.presetQuery.pageSize);
+        }
+        void this.refresh();
+    };
+    copy(store) {
+        this.config = { ...store.config };
+        this.prefetchMode = store.prefetchMode;
+        this.allItemsState.set(store.allItemsState());
+        this.filtersState.set(store.filters);
+        this.queryState.set(store.query);
+        this.sortState.set([...store.sort]);
+        this.routeParamsState.set(store.routeParams);
+        this.pageState.set(store.page);
+        this.pageSizeState.set(store.pageSize);
+        this.totalElementsState.set(store.totalElements);
+        this.cached.set(store.cached());
+        this.items.set(store.items());
+        this.bumpVersion();
+    }
+    destroy() { }
+    async refresh(override) {
+        const page = override?.page ?? this.page;
+        const size = this.pageSize;
+        const sort = this.sort;
+        try {
+            const resolved = await this.resolveItems({
+                page,
+                size,
+                ...this.filters,
+                ...this.query,
+                sort,
+                items: this.allItemsState(),
+                routeParams: this.routeParams,
+            });
+            const sorted = this.applyClientSort(resolved, sort);
+            const start = Math.max(0, page) * Math.max(1, size);
+            const pageItems = sorted.slice(start, start + Math.max(1, size));
+            this.pageState.set(page);
+            this.totalElementsState.set(sorted.length);
+            this.cached.set(sorted);
+            this.items.set(pageItems);
+            return pageItems;
+        }
+        catch (error) {
+            this.error.set(error);
+            throw error;
+        }
+    }
+    resolveItems(input) {
+        if (this.config.resolveItems) {
+            return this.config.resolveItems(input);
+        }
+        return input.items;
+    }
+    applyClientSort(items, sort) {
+        const clone = [...items];
+        if (!sort.length) {
+            return clone;
+        }
+        clone.sort((left, right) => {
+            for (const rule of sort) {
+                const result = this.compareValues(left[rule.sort], right[rule.sort]);
+                if (result !== 0) {
+                    return rule.order === 'desc' ? -result : result;
+                }
+            }
+            return 0;
+        });
+        return clone;
+    }
+    compareValues(left, right) {
+        if (left == null && right == null) {
+            return 0;
+        }
+        if (left == null) {
+            return -1;
+        }
+        if (right == null) {
+            return 1;
+        }
+        if (typeof left === 'number' && typeof right === 'number') {
+            return left - right;
+        }
+        if (left instanceof Date && right instanceof Date) {
+            return left.getTime() - right.getTime();
+        }
+        return String(left).localeCompare(String(right), undefined, { numeric: true, sensitivity: 'base' });
+    }
+    normalizeSort(sort) {
+        return normalizeSortInput(sort);
+    }
+    bumpVersion() {
+        this.version.update((current) => current + 1);
+    }
+}
+
 // noinspection ES6PreferShortImport
 /**
  * Store for paginated data (tables/lists) with per-page cache and unified requests.
@@ -1126,6 +1531,7 @@ class PagedQueryStore {
         const method = this.config.method || 'GET';
         const normalizedSort = this.normalizeSort(sort);
         const sortQueryKey = this.resolveSortQueryKey();
+        // parseRequest works on the pre-serialization request model, so sort is still object-based here.
         const requestPayload = mergeQueryParams(mergeQueryParams({ page, size }, filters), mergeQueryParams(query, normalizedSort.length ? { [sortQueryKey]: normalizedSort } : {}));
         const fallbackQuery = method === 'GET' ? requestPayload : mergeQueryParams({ page, size }, query);
         const rawQueries = this.config.parseRequest?.(requestPayload) || fallbackQuery;
@@ -1296,9 +1702,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 +1722,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 +1745,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 +1760,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 +1822,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 +1956,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) {
@@ -1817,5 +2263,5 @@ class EntityStore {
  * Generated bundle index. Do not edit.
  */
 
-export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, PagedQueryStore, RESOURCE_PROFILES, ResourceStore, STATUM_CONFIG, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, PagedQueryLocalStore, PagedQueryStore, RESOURCE_PROFILES, ResourceMockStore, ResourceStore, STATUM_CONFIG, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum };
 //# sourceMappingURL=reforgium-statum.mjs.map

package/package.json

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

package/types/reforgium-statum.d.ts

@@ -1,4 +1,4 @@
-import { DataType, SerializerConfig, Serializer, RestMethods, AnyDict, AnyType, QueryParams, PageableRequest, PageableResponse, StorageStrategy } from '@reforgium/internal';
+import { DataType, SerializerConfig, Serializer, RestMethods, AnyDict, AnyType, QueryParams, PageableResponse, StorageStrategy } from '@reforgium/internal';
 export { DataType, FieldConcatType, FieldConfig, FormatConfig, LocalStorage, LruCache, MemoryStorage, ParseFormatConfig, SerializedType, Serializer, SerializerConfig, SerializerFieldError, SessionStorage, StorageInterface, StorageStrategy, StorageStrategyOptions, Types, storageStrategy } from '@reforgium/internal';
 import * as _angular_core from '@angular/core';
 import { Signal, WritableSignal, EnvironmentProviders, InjectionToken } from '@angular/core';
@@ -168,6 +168,51 @@ type ResourceTraceEvent = {
     error?: unknown;
 };
 
+type ResourceMockHandlerContext<Data, Param extends SimpleDict = SimpleDict, Query extends QueryDict = QueryDict, Payload extends PayloadData = PayloadData> = {
+    method: RestMethods;
+    route?: string;
+    url: string;
+    args: CallArgs<Param, Query, Payload>;
+    current: Data | null;
+};
+type ResourceMockHandler<Data, Result = Data, Param extends SimpleDict = SimpleDict, Query extends QueryDict = QueryDict, Payload extends PayloadData = PayloadData> = (ctx: ResourceMockHandlerContext<Data, Param, Query, Payload>) => Result | Promise<Result>;
+type ResourceMockHandlers<Data> = Partial<Record<RestMethods, ResourceMockHandler<Data, AnyType>>>;
+type ResourceMockStoreOptions<Data> = Pick<ResourceStoreOptions, 'baseUrl' | 'delay' | 'onTrace'> & {
+    seed?: Data | null;
+    handlers?: ResourceMockHandlers<Data>;
+};
+/**
+ * Lightweight in-memory counterpart of `ResourceStore`.
+ *
+ * It preserves the result-facing API (`value/status/error/loading` + CRUD methods),
+ * but does not try to reproduce transport, retry, or per-key cache internals.
+ */
+declare class ResourceMockStore<Data> {
+    #private;
+    readonly value: Signal<Data | null>;
+    readonly status: Signal<ResourceStatus>;
+    readonly error: Signal<unknown | null>;
+    readonly loading: Signal<boolean>;
+    private readonly routes;
+    private readonly opts;
+    constructor(routes?: ResourceRoutesMap, opts?: ResourceMockStoreOptions<Data>);
+    setValue(value: Data | null): void;
+    patchValue(patch: Partial<Data>): void;
+    reset(value?: Data | null): void;
+    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<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<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<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<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>;
+    abort(): void;
+    abortAll(): void;
+    private runMutation;
+    private resolveMutation;
+    private run;
+    private buildUrl;
+    private trace;
+}
+
 /**
  * Store for REST resources with caching and request deduplication.
  *
@@ -358,6 +403,10 @@ type QuerySortRule<Key extends string = string> = {
     order: QuerySortOrder;
 };
 type QuerySortInput<Key extends string = string> = QuerySortRule<Key> | ReadonlyArray<QuerySortRule<Key>> | null | undefined;
+type PagedQueryRequestInput<FilterType extends AnyDict = AnyDict> = Omit<QueryParams<FilterType>, 'page' | 'sort'> & {
+    page: number;
+    sort?: QuerySortInput;
+} & Partial<FilterType> & AnyDict;
 type PagedQueryConcurrency = 'latest-wins' | 'parallel';
 type OffsetPaginationType = {
     page?: number;
@@ -433,7 +482,7 @@ type PagedQueryStoreConfig<ItemsType extends object, FilterType extends AnyDict
      * 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?: BivariantCallback<PageableRequest & Partial<FilterType> & AnyDict, AnyDict>;
+    parseRequest?: BivariantCallback<PagedQueryRequestInput<FilterType>, AnyDict>;
     /**
      * Custom parser of API response into unified `PageableResponse<ItemsType>`.
      * Use if the server returns an array or a non-standard structure.
@@ -470,6 +519,85 @@ type PagedQueryStoreProviderConfig = {
     defaultDisableCacheLimit?: boolean;
 };
 
+type PagedQueryLocalResolverInput<ItemsType extends AnyDict, FilterType extends AnyDict = AnyDict> = PagedQueryRequestInput<FilterType> & {
+    items: readonly ItemsType[];
+    routeParams: AnyDict;
+};
+type PagedQueryLocalResolverResult<ItemsType extends AnyDict> = readonly ItemsType[] | Promise<readonly ItemsType[]>;
+type PagedQueryLocalStoreConfig<ItemsType extends AnyDict, FilterType extends AnyDict = AnyDict> = {
+    presetQuery?: {
+        page?: number;
+        pageSize?: number;
+    };
+    presetFilters?: Partial<FilterType>;
+    presetSort?: ReadonlyArray<QuerySortRule>;
+    presetRouteParams?: AnyDict;
+    prefetchMode?: 'sequential' | 'parallel';
+    resolveItems?: (input: PagedQueryLocalResolverInput<ItemsType, FilterType>) => PagedQueryLocalResolverResult<ItemsType>;
+};
+/**
+ * Lightweight local counterpart of `PagedQueryStore`.
+ *
+ * It keeps the same result-facing shape needed by consumers and `DataGrid source`,
+ * but resolves pages from an in-memory collection instead of HTTP.
+ */
+declare class PagedQueryLocalStore<ItemsType extends AnyDict, FilterType extends AnyDict = AnyDict> {
+    readonly items: _angular_core.WritableSignal<ItemsType[]>;
+    readonly cached: _angular_core.WritableSignal<ItemsType[]>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly error: _angular_core.WritableSignal<unknown>;
+    readonly version: _angular_core.WritableSignal<number>;
+    readonly allItemsState: _angular_core.WritableSignal<readonly ItemsType[]>;
+    readonly pageState: _angular_core.WritableSignal<number>;
+    readonly pageSizeState: _angular_core.WritableSignal<number>;
+    readonly totalElementsState: _angular_core.WritableSignal<number | undefined>;
+    readonly filtersState: _angular_core.WritableSignal<Partial<FilterType>>;
+    readonly queryState: _angular_core.WritableSignal<AnyDict>;
+    readonly sortState: _angular_core.WritableSignal<QuerySortRule[]>;
+    readonly routeParamsState: _angular_core.WritableSignal<AnyDict>;
+    config: PagedQueryLocalStoreConfig<ItemsType, FilterType>;
+    prefetchMode: 'sequential' | 'parallel';
+    constructor(items?: readonly ItemsType[], config?: PagedQueryLocalStoreConfig<ItemsType, FilterType>);
+    get page(): number;
+    get pageSize(): number;
+    get totalElements(): number | undefined;
+    get filters(): Partial<FilterType>;
+    get query(): AnyDict;
+    get sort(): QuerySortRule[];
+    get routeParams(): AnyDict;
+    set page(value: number);
+    set pageSize(value: number);
+    set totalElements(value: number | undefined);
+    set filters(value: Partial<FilterType>);
+    set query(value: AnyDict);
+    setData: (items: readonly ItemsType[], opts?: {
+        replace?: boolean;
+    }) => Promise<ItemsType[]>;
+    preload: (items: readonly ItemsType[], opts?: {
+        replace?: boolean;
+    }) => Promise<ItemsType[]>;
+    fetch: ({ filters, query, routeParams, sort }?: FetchInput<FilterType>) => Promise<ItemsType[]>;
+    refetchWith({ filters, query, sort }?: RefetchWithInput<FilterType>): Promise<ItemsType[]>;
+    updatePage: (page?: number | {
+        page: number;
+    }, _options?: UpdatePageOptions) => Promise<ItemsType[]>;
+    updatePageSize: (size?: number) => Promise<ItemsType[]>;
+    updateByOffset: ({ page: pageNum, first, rows }?: OffsetPaginationType, { query, sort }?: UpdateByOffsetOptions) => Promise<ItemsType[]>;
+    setSort: (sort?: QuerySortInput) => void;
+    updateSort: (sort?: QuerySortRule | null) => Promise<ItemsType[]>;
+    updateSorts: (sort?: ReadonlyArray<QuerySortRule> | null) => Promise<ItemsType[]>;
+    setRouteParams: (params?: AnyDict, opts?: SetRouteParamsOptions) => void;
+    updateConfig: (config: PagedQueryLocalStoreConfig<ItemsType, FilterType>) => void;
+    copy(store: PagedQueryLocalStore<ItemsType, FilterType>): void;
+    destroy(): void;
+    private refresh;
+    private resolveItems;
+    private applyClientSort;
+    private compareValues;
+    private normalizeSort;
+    private bumpVersion;
+}
+
 /**
  * Store for paginated data (tables/lists) with per-page cache and unified requests.
  *
@@ -644,13 +772,21 @@ 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.
      */
-    parseRequest?: (data: PageableRequest) => AnyDict;
+    parseRequest?: (data: PagedQueryRequestInput<FilterType>) => AnyDict;
     /**
      * Custom parser of server response into a unified PageableResponse.
      * Needed if the API returns an array or a "non-standard" structure.
@@ -662,7 +798,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 +847,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'];
@@ -724,6 +868,9 @@ type DictStoreProviderConfig = {
     defaultValueKey?: DictStoreConfig<AnyType>['valueKey'];
 };
 type ValueType = string[] | string | number | null | undefined;
+type FilterType = {
+    name: string;
+};
 
 /**
  * Dictionary store (select/options) with local LRU cache and optional persistence.
@@ -760,9 +907,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 +942,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 +951,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 +984,8 @@ declare class DictStore<Type extends AnyDict> {
     private keyOf;
     private setAutoload;
     private shouldFetchFixedCache;
-    private shouldRevalidateCache;
+    private maybeScheduleAccessLoad;
+    private shouldFetchOnAccessRead;
     private isCacheStale;
     private metaKey;
 }
@@ -951,6 +1107,6 @@ type StatumConfig = PagedQueryProviderConfig & SerializerProviderConfig & DictPr
 declare const STATUM_CONFIG: InjectionToken<StatumConfig>;
 declare const provideStatum: (config: StatumConfig) => EnvironmentProviders;
 
-export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, PagedQueryStore, RESOURCE_PROFILES, ResourceStore, STATUM_CONFIG, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum };
-export type { DictLocalConfig, DictStoreConfig, DictStoreProviderConfig, EntityId, EntityStoreConfig, FetchInput, FetchParams, OffsetPaginationType, PagedQueryStoreConfig, PagedQueryStoreProviderConfig, QuerySortInput, QuerySortOrder, QuerySortRule, RefetchWithInput, ResourceProfileName, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, ResourceTraceEvent, RetryConfig, SetRouteParamsOptions, StatumConfig, UpdateByOffsetOptions, UpdatePageInput, UpdatePageOptions };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, PagedQueryLocalStore, PagedQueryStore, RESOURCE_PROFILES, ResourceMockStore, ResourceStore, STATUM_CONFIG, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum };
+export type { DictLocalConfig, DictStoreConfig, DictStoreProviderConfig, EntityId, EntityStoreConfig, FetchInput, FetchParams, OffsetPaginationType, PagedQueryLocalResolverInput, PagedQueryLocalResolverResult, PagedQueryLocalStoreConfig, PagedQueryRequestInput, PagedQueryStoreConfig, PagedQueryStoreProviderConfig, QuerySortInput, QuerySortOrder, QuerySortRule, RefetchWithInput, ResourceMockHandler, ResourceMockHandlerContext, ResourceMockHandlers, ResourceMockStoreOptions, ResourceProfileName, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, ResourceTraceEvent, RetryConfig, SetRouteParamsOptions, StatumConfig, UpdateByOffsetOptions, UpdatePageInput, UpdatePageOptions };
 //# sourceMappingURL=reforgium-statum.d.ts.map