@reforgium/statum 3.0.0-rc.0 → 3.0.0

package/fesm2022/reforgium-statum.mjs

@@ -1,6 +1,6 @@
-import { formatDate, isNullable, isDatePeriod, parseToDate, makeQuery, isNumber, isObject, parseToDatePeriod, parseQueryArray, fillUrlWithParams, deepEqual, concatArray, debounceSignal } from '@reforgium/internal';
-import { HttpClient } from '@angular/common/http';
-import { InjectionToken, makeEnvironmentProviders, inject, signal, computed, DestroyRef, effect, untracked } from '@angular/core';
+import { formatDate, isNullable, isDatePeriod, parseToDate, buildQueryParams, isNumber, isObject, parseToDatePeriod, parseQueryParamsByMode, fillUrlWithParams, mergeQueryParams, deepEqual, normalizeSortInput, sortInputToTokens, debounceSignal } from '@reforgium/internal';
+import { HttpClient, HttpParams } from '@angular/common/http';
+import { InjectionToken, makeEnvironmentProviders, inject, signal, computed, EnvironmentInjector, DestroyRef, runInInjectionContext, effect, untracked } from '@angular/core';
 import { Subject, filter, timer, merge, map } from 'rxjs';
 import { debounce, tap, throttle, finalize } from 'rxjs/operators';
 
@@ -162,8 +162,8 @@ class Serializer {
                     .replace(periodTransform.dateFromKeyPostfix, '')
                     .replace(periodTransform.dateToKeyPostfix, '');
                 const field = this.config.mapFields?.[keyJoint];
-                // @ts-ignore
-                if (field?.['type'] === 'period' && (isFrom || isTo)) {
+                const fieldType = field && 'type' in field ? field.type : undefined;
+                if (fieldType === 'period' && (isFrom || isTo)) {
                     result[keyJoint] ??= [null, null];
                     if (isFrom) {
                         result[keyJoint][0] = parseToDate(value, this.config.mapPeriod.dateFormat);
@@ -194,7 +194,7 @@ class Serializer {
      * @returns query string (suitable for URL or history API)
      */
     toQuery = (val) => {
-        return makeQuery(this.serialize(val), this.config.mapArray.concatType);
+        return buildQueryParams(this.serialize(val), this.config.mapArray.concatType, this.resolveArrayFieldModes());
     };
     /**
      * Returns a new serializer instance with a merged configuration.
@@ -280,8 +280,7 @@ class Serializer {
                     return isObject(value) ? this.deserialize(value) : value;
                 }
                 else {
-                    // @ts-ignore
-                    return JSON.parse(value);
+                    return typeof value === 'string' ? JSON.parse(value) : value;
                 }
             }
             catch {
@@ -321,21 +320,7 @@ class Serializer {
         return value;
     }
     parseQuery(val) {
-        const params = new URLSearchParams(val);
-        const data = {};
-        params.forEach((value, key) => {
-            const field = this.config.mapFields?.[key] || {};
-            const concatType = this.config.mapArray.concatType;
-            if ('type' in field && field.type === 'array') {
-                data[key] ??= [];
-                concatType !== 'multi' && (data[key] = parseQueryArray(value, concatType, key));
-                concatType === 'multi' && data[key].push(value);
-            }
-            else {
-                data[key] = value;
-            }
-        });
-        return data;
+        return parseQueryParamsByMode(val, undefined, this.resolveArrayFieldModes());
     }
     parseJsonObject(val) {
         try {
@@ -379,6 +364,15 @@ class Serializer {
             mapFields: { ...(base.mapFields || {}), ...(override.mapFields || {}) },
         };
     }
+    resolveArrayFieldModes() {
+        const result = {};
+        Object.entries(this.config.mapFields || {}).forEach(([key, field]) => {
+            if ('type' in field && field.type === 'array') {
+                result[key] = field.concatType ?? this.config.mapArray.concatType;
+            }
+        });
+        return result;
+    }
 }
 
 const createQuerySerializer = (config = {}) => {
@@ -408,19 +402,19 @@ const createStrictSerializer = (config = {}) => {
 
 class LruCache {
     map = new Map();
+    _limit = 100;
     constructor(limit = 100) {
         this.limit = limit;
     }
-    _limit = 100;
     get limit() {
         return this._limit;
     }
-    set limit(value) {
-        this._limit = Math.max(1, Math.floor(value || 0));
-    }
     get length() {
         return this.map.size;
     }
+    set limit(value) {
+        this._limit = Math.max(1, Math.floor(value || 0));
+    }
     get(key) {
         if (!this.map.has(key)) {
             return null;
@@ -647,7 +641,14 @@ function isAbort(e) {
         (typeof e === 'object' && e != null && e?.name === 'AbortError' && e?.message === 'aborted'));
 }
 function joinUrl(base, path) {
-    return base ? `${base.replace(/\/$/, '')}/${path.replace(/^\//, '')}` : path;
+    if (!base) {
+        return path;
+    }
+    const normalizedBase = base.replace(/\/$/, '');
+    if (!path) {
+        return normalizedBase;
+    }
+    return `${normalizedBase}/${path.replace(/^\//, '')}`;
 }
 function buildKey(method, path, args) {
     const params = stableStringify(args.params || {});
@@ -835,7 +836,7 @@ class KeyedScheduler {
  */
 class ResourceStore {
     http = inject(HttpClient);
-    serializer = new Serializer(inject(STATUM_CONFIG, { optional: true })?.serializer ?? {});
+    serializer;
     #value = signal(null, ...(ngDevMode ? [{ debugName: "#value" }] : []));
     #status = signal('idle', ...(ngDevMode ? [{ debugName: "#status" }] : []));
     #error = signal(null, ...(ngDevMode ? [{ debugName: "#error" }] : []));
@@ -863,6 +864,11 @@ class ResourceStore {
     maxEntries;
     entries = new Map();
     scheduler = new KeyedScheduler();
+    mutationMethods = {
+        PATCH: this.http.patch.bind(this.http),
+        POST: this.http.post.bind(this.http),
+        PUT: this.http.put.bind(this.http),
+    };
     /**
      * @param routes Map of path templates for methods (`GET/POST/...` → `/users/:id`)
      * @param opts   Global options (baseUrl, ttlMs, delay, delayMode, presetQueries/payload, etc.)
@@ -871,6 +877,10 @@ class ResourceStore {
         this.routes = routes;
         this.opts = opts;
         this.maxEntries = Math.max(1, opts.maxEntries ?? 1000);
+        this.serializer = new Serializer({
+            ...(inject(STATUM_CONFIG, { optional: true })?.serializer ?? {}),
+            ...(opts.serializer ?? {}),
+        });
     }
     /**
      * Perform a GET request.
@@ -882,11 +892,20 @@ class ResourceStore {
      * @param cfg  Call settings (strategy, ttlMs, revalidate, parseResponse, delay, delayMode, dedupe, promote)
      * @returns Deserialized `Data`
      */
-    async get(args, cfg = {}) {
-        const url = this.buildUrl('GET', args);
-        const key = buildKey('GET', url, args);
-        const query = this.prepareQuery(args);
-        const responseType = cfg.responseType ?? 'json';
+    get(args, cfg = {}) {
+        let url;
+        let key;
+        let query;
+        let responseType;
+        try {
+            url = this.buildUrl('GET', args);
+            key = buildKey('GET', url, args);
+            query = this.prepareQuery(args);
+            responseType = cfg.responseType ?? 'json';
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
         const entry = this.ensureEntry(key);
         const strategy = cfg.strategy ?? 'network-first';
         const ttlMs = cfg.ttlMs ?? this.opts.ttlMs ?? 0;
@@ -898,15 +917,15 @@ class ResourceStore {
             if (fresh && entry.data != null) {
                 this.trace({ type: 'cache-hit', method: 'GET', key, strategy });
                 this.promoteCurrent(entry, cfg.promote);
-                return entry.data;
+                return Promise.resolve(entry.data);
             }
             this.trace({ type: 'cache-miss', method: 'GET', key, strategy });
-            throw new CacheMissError(key);
+            return Promise.reject(new CacheMissError(key));
         }
         if (strategy === 'cache-first' && fresh && !cfg.revalidate && entry.data != null) {
             this.trace({ type: 'cache-hit', method: 'GET', key, strategy });
             this.promoteCurrent(entry, cfg.promote);
-            return entry.data;
+            return Promise.resolve(entry.data);
         }
         const delay = cfg.delay ?? this.opts.delay ?? 0;
         const mode = cfg.delayMode ?? this.opts.delayMode ?? 'debounce';
@@ -971,8 +990,8 @@ class ResourceStore {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    async post(args, cfg = {}) {
-        return await this.callApi('POST', args, cfg);
+    post(args, cfg = {}) {
+        return this.callApi('POST', args, cfg);
     }
     /**
      * PUT request (full resource update).
@@ -981,8 +1000,8 @@ class ResourceStore {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    async put(args, cfg = {}) {
-        return await this.callApi('PUT', args, cfg);
+    put(args, cfg = {}) {
+        return this.callApi('PUT', args, cfg);
     }
     /**
      * PATCH request (partial update).
@@ -991,8 +1010,8 @@ class ResourceStore {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    async patch(args, cfg = {}) {
-        return await this.callApi('PATCH', args, cfg);
+    patch(args, cfg = {}) {
+        return this.callApi('PATCH', args, cfg);
     }
     /**
      * DELETE request.
@@ -1001,8 +1020,8 @@ class ResourceStore {
      * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
      * @returns API response (by default — as returned by the server)
      */
-    async delete(args, cfg = {}) {
-        return await this.callApi('DELETE', args, cfg);
+    delete(args, cfg = {}) {
+        return this.callApi('DELETE', args, cfg);
     }
     /**
      * Cancel scheduled/running requests for a specific call.
@@ -1071,13 +1090,22 @@ class ResourceStore {
             this.entries.delete(keyToDelete);
         }
     }
-    async callApi(method, args, config = {}) {
-        const url = this.buildUrl(method, args);
-        const key = buildKey(method, url, args);
-        const query = this.prepareQuery(args);
-        const payload = { ...(this.opts.presetPayload || {}), ...(args.payload || {}) };
-        const serializedPayload = this.serializer.serialize(payload);
-        const responseType = config.responseType ?? 'json';
+    callApi(method, args, config = {}) {
+        let url;
+        let key;
+        let query;
+        let payload;
+        let responseType;
+        try {
+            url = this.buildUrl(method, args);
+            key = buildKey(method, url, args);
+            query = this.prepareQuery(args);
+            payload = this.preparePayload(args.payload);
+            responseType = config.responseType ?? 'json';
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
         const entry = this.ensureEntry(key);
         if (config.dedupe && entry.inflight) {
             return entry.inflight;
@@ -1090,14 +1118,14 @@ class ResourceStore {
         let req$;
         if (method === 'DELETE') {
             req$ = this.http.delete(url, {
-                body: serializedPayload,
+                body: payload,
                 params: query,
                 responseType: responseType,
             });
         }
         else {
             // @ts-ignore
-            req$ = this.http[method.toLowerCase()](url, serializedPayload, {
+            req$ = this.mutationMethods[method](url, payload, {
                 params: query,
                 responseType: responseType,
             });
@@ -1132,15 +1160,45 @@ class ResourceStore {
     }
     buildUrl(method, args) {
         const tpl = this.routes[method];
-        if (!tpl) {
+        if (tpl == null) {
             throw new Error(`${method} route not configured`);
         }
         const path = fillUrlWithParams(tpl, args.params);
         return joinUrl(this.opts.baseUrl, path);
     }
     prepareQuery(args) {
-        const mergedQuery = { ...(this.opts.presetQueries || {}), ...(args.query || {}) };
-        return this.serializer.serialize(mergedQuery);
+        const presetQuery = this.opts.presetQueries;
+        const requestQuery = args.query;
+        if (!presetQuery && !requestQuery) {
+            return new HttpParams();
+        }
+        const mergedQuery = mergeQueryParams(presetQuery, requestQuery);
+        if (this.isEmptyObject(mergedQuery)) {
+            return new HttpParams();
+        }
+        return new HttpParams({
+            fromString: this.serializer.toQuery(mergedQuery),
+        });
+    }
+    preparePayload(payload) {
+        const presetPayload = this.opts.presetPayload;
+        if (!presetPayload && !payload) {
+            return {};
+        }
+        let mergedPayload;
+        if (!presetPayload) {
+            mergedPayload = payload ?? {};
+        }
+        else if (!payload) {
+            mergedPayload = presetPayload;
+        }
+        else {
+            mergedPayload = { ...presetPayload, ...payload };
+        }
+        if (this.isEmptyObject(mergedPayload)) {
+            return {};
+        }
+        return this.serializer.serialize(mergedPayload);
     }
     trace(event) {
         try {
@@ -1218,6 +1276,14 @@ class ResourceStore {
         this.#status.set(entry.status);
         this.#error.set(entry.error);
     }
+    isEmptyObject(value) {
+        for (const _key in value) {
+            if (Object.prototype.hasOwnProperty.call(value, _key)) {
+                return false;
+            }
+        }
+        return true;
+    }
 }
 
 const RESOURCE_PROFILES = {
@@ -1265,26 +1331,37 @@ const createResourceProfile = (profile, overrides = {}) => ({
 class PagedQueryStore {
     route;
     config;
+    static DISABLED_CACHE_LIMIT = Number.MAX_SAFE_INTEGER;
     defaultConfig = inject(STATUM_CONFIG, { optional: true })?.pagedQuery || {};
+    injector = inject(EnvironmentInjector);
+    #requestId = 0;
+    #activeRequests = 0;
     #transport;
     #cache;
     /** Current page data (reactive). */
     items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : []));
-    /** Merged cache of pages (flat list) — handy for search/export. */
+    /** Merged cache of pages (flat list) handy for search/export. */
     cached = signal([], ...(ngDevMode ? [{ debugName: "cached" }] : []));
     /** Loading flag of the current operation. */
     loading = signal(false, ...(ngDevMode ? [{ debugName: "loading" }] : []));
-    /** Current filters (applied to requests). */
-    filters = {};
-    /** Additional query params sent to transport requests. */
-    query = {};
-    /** Current page index (0-based). */
-    page = 0;
-    /** Default page size. */
-    pageSize = 20;
-    /** Total number of elements reported by the server. */
-    totalElements = 0;
-    routeParams = {};
+    /** Last request error (if any). */
+    error = signal(null, ...(ngDevMode ? [{ debugName: "error" }] : []));
+    /** 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" }] : []));
+    pageState = this.#page.asReadonly();
+    pageSizeState = this.#pageSize.asReadonly();
+    totalElementsState = this.#totalElements.asReadonly();
+    filtersState = this.#filters.asReadonly();
+    queryState = this.#query.asReadonly();
+    sortState = this.#sort.asReadonly();
+    routeParamsState = this.#routeParams.asReadonly();
     /**
      * @param route  Resource URL pattern (e.g., `'/users'`)
      * @param config Store behavior: method, cache, request/response parsers, debounce, presets, etc.
@@ -1293,45 +1370,105 @@ class PagedQueryStore {
         this.route = route;
         this.config = config;
         this.applyConfig(config);
-        this.#cache = new LruCache(this.config.cacheSize);
+        this.#cache = new LruCache(this.resolveCacheLimit());
         this.applyPresetMeta();
         this.initTransport();
         inject(DestroyRef).onDestroy(() => this.destroy());
     }
+    /** Current filters (applied to requests). */
+    get filters() {
+        return this.#filters();
+    }
+    /** Additional query params sent to transport requests. */
+    get query() {
+        return this.#query();
+    }
+    /** Current page index (0-based). */
+    get page() {
+        return this.#page();
+    }
+    /** Default page size. */
+    get pageSize() {
+        return this.#pageSize();
+    }
+    /** Total number of elements reported by the server. */
+    get totalElements() {
+        return this.#totalElements();
+    }
+    /** Current sort rules. */
+    get sort() {
+        return this.#sort();
+    }
+    /**
+     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
+     */
+    set filters(value) {
+        this.#filters.set(value);
+    }
+    /**
+     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
+     */
+    set query(value) {
+        this.#query.set(value);
+    }
+    /**
+     * @deprecated Prefer `updatePage(...)`, `fetch(...)`, or `refetchWith(...)`.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
+     */
+    set page(value) {
+        this.#page.set(value);
+    }
+    /**
+     * @deprecated Prefer `updatePageSize(...)`.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
+     */
+    set pageSize(value) {
+        this.#pageSize.set(value);
+    }
+    /**
+     * @deprecated Managed by transport responses. Direct assignment should be treated as legacy.
+     */
+    set totalElements(value) {
+        this.#totalElements.set(value);
+    }
     /**
      * Fetch data with explicit filters and query params from the first page.
      * Replaces legacy `setFilters`.
      */
-    fetch = ({ filters = {}, query = {}, routeParams = {} } = {}) => {
-        this.#cache.clear();
-        this.cached.set([]);
-        return this.#fetchItems({ page: 0, filters, query, routeParams });
+    fetch = ({ filters = {}, query = {}, routeParams = {}, sort = this.sort } = {}) => {
+        this.resetDataset();
+        return this.#fetchItems({ page: 0, filters, query, routeParams, sort });
     };
     /**
      * Force reload current data.
      * Optional args merge into active filters/query.
-     * Route params are intentionally not changed from `refresh`.
+     * Route params are intentionally not changed from `refetchWith`.
      */
-    refresh({ filters, query } = {}) {
+    refetchWith({ filters, query, sort } = {}) {
         const nextFilters = filters == null ? this.filters : { ...this.filters, ...filters };
-        const nextQuery = query == null ? this.query : { ...this.query, ...query };
-        return this.#fetchItems({ filters: nextFilters, query: nextQuery });
+        const nextQuery = query == null ? this.query : mergeQueryParams(this.query, query);
+        const nextSort = sort == null ? this.sort : this.normalizeSort(sort);
+        return this.#fetchItems({ filters: nextFilters, query: nextQuery, sort: nextSort });
     }
     /**
      * Switch page with a request.
-     * If cache is enabled and the page is present in LRU — returns it from cache.
-     * @param page        page index (0-based)
-     * @param ignoreCache ignore cache and fetch from network
+     * If cache is enabled and the page is present in LRU returns it from cache.
+     * @param page        page index (0-based) or object form: `{ page }`
+     * @param options     request options
+     * @param options.ignoreCache ignore cache and fetch from network
      */
     updatePage = (page = this.page, { ignoreCache = false } = {}) => {
-        if (this.config.hasCache && this.#cache.has(page) && !ignoreCache) {
-            const cached = this.#cache.get(page);
+        const normalizedPage = typeof page === 'number' ? page : page.page;
+        if (this.config.hasCache && this.#cache.has(normalizedPage) && !ignoreCache) {
+            const cached = this.#cache.get(normalizedPage);
             this.items.set(cached);
-            this.page = page;
+            this.page = normalizedPage;
             return Promise.resolve(cached);
         }
         else {
-            return this.#fetchItems({ page });
+            return this.#fetchItems({ page: normalizedPage });
         }
     };
     /**
@@ -1339,50 +1476,58 @@ class PagedQueryStore {
      * @param size new size (rows per page)
      */
     updatePageSize = (size = this.pageSize) => {
-        this.#cache.clear();
-        this.cached.set([]);
+        this.resetDataset();
         return this.#fetchItems({ page: 0, size });
     };
     /**
      * Helper for offset-based table events (PrimeNG, etc.) with `page/first/rows`.
      */
-    updateByOffset = ({ page: pageNum, first = 0, rows = 0 } = {}, { query = this.query } = {}) => {
+    updateByOffset = ({ page: pageNum, first = 0, rows = 0 } = {}, { query = this.query, sort = this.sort } = {}) => {
         const page = (pageNum ?? (first && rows && Math.floor(first / rows))) || 0;
         const size = rows || this.pageSize;
-        return this.#fetchItems({ page, size, query });
+        return this.#fetchItems({ page, size, query, sort });
+    };
+    setSort = (sort) => {
+        this.#sort.set(this.normalizeSort(sort));
+    };
+    updateSort = (sort) => {
+        return this.updateSorts(sort ? [sort] : []);
+    };
+    updateSorts = (sort) => {
+        const normalizedSort = this.normalizeSort(sort);
+        this.resetDataset();
+        return this.#fetchItems({ page: 0, sort: normalizedSort });
     };
     /**
      * Set route parameters (path variables) for the resource URL.
-     * Does not trigger loading automatically - call `refresh()` or `updatePage()` after.
+     * Does not trigger loading automatically - call `refetchWith()` or `updatePage()` after.
      *
      * @param params Dictionary of route parameters (e.g., `{ id: '123' }`)
+     * @param opts
      * @param opts.reset  If `true`, resets page to 0, clears cache, total elements count, and items
      * @param opts.abort  If `true`, aborts all active transport requests and sets loading to false
      *
      * @example
      * ```ts
      * store.setRouteParams({ userId: '42' });
-     * await store.refresh(); // fetch with new params
+     * await store.refetchWith(); // fetch with new params
      *
      * // Or with options:
      * store.setRouteParams({ userId: '42' }, { reset: false, abort: true });
      * ```
      */
-    setRouteParams = (params = {}, { reset = false, abort = false } = {}) => {
-        const isChanged = !deepEqual(this.routeParams, params);
+    setRouteParams = (params = {}, opts = {}) => {
+        const isChanged = !deepEqual(this.#routeParams(), params);
         if (!isChanged) {
             return;
         }
-        this.routeParams = params;
-        if (reset) {
-            this.page = 0;
-            this.totalElements = 0;
-            this.#cache.clear();
-            this.cached.set([]);
-            this.items.set([]);
+        this.#routeParams.set(params);
+        if (opts.reset) {
+            this.resetDataset();
         }
-        if (abort) {
+        if (opts.abort) {
             try {
+                this.invalidateRequests();
                 this.#transport?.abortAll?.('Route params changed');
             }
             finally {
@@ -1396,8 +1541,9 @@ class PagedQueryStore {
      */
     updateConfig = (config) => {
         this.config = { ...this.config, ...config };
-        this.#cache.limit = this.config.cacheSize || this.defaultConfig.defaultCacheSize || 5;
+        this.#cache.limit = this.resolveCacheLimit();
         this.applyPresetMeta();
+        this.reinitTransport();
     };
     /**
      * Copy configuration and presets from another store of the same type.
@@ -1405,10 +1551,12 @@ class PagedQueryStore {
     copy(store) {
         this.applyConfig(store.config);
         this.applyPresetMeta();
+        this.reinitTransport();
     }
     /** Clean up resources and cancel active requests. Automatically called onDestroy. */
     destroy() {
         try {
+            this.invalidateRequests();
             this.#transport?.abortAll?.('PagedQueryStore destroyed');
         }
         catch (e) {
@@ -1417,17 +1565,29 @@ class PagedQueryStore {
             }
         }
     }
-    #fetchItems = async ({ page = this.page, size = this.pageSize, filters = this.filters, query = this.query, routeParams = this.routeParams, }) => {
-        const builtQuery = this.parseQuery({ page, size, filters, query });
+    #fetchItems = async ({ page = this.page, size = this.pageSize, filters = this.filters, query = this.query, routeParams = this.#routeParams(), sort = this.sort, }) => {
+        const builtQuery = this.parseQuery({ page, size, filters, query, sort });
+        const requestId = ++this.#requestId;
+        this.#activeRequests++;
         this.loading.set(true);
-        this.routeParams = routeParams;
-        this.#transport.abortAll();
+        this.error.set(null);
+        this.#routeParams.set(routeParams);
+        if (this.resolveConcurrency() === 'latest-wins') {
+            this.#transport.abortAll();
+        }
         try {
             const response = await this.runTransport(filters, builtQuery, routeParams);
+            if (this.shouldIgnoreRequestResult(requestId)) {
+                return;
+            }
             this.page = page;
             this.filters = filters;
             this.query = query;
+            this.#sort.set(this.normalizeSort(sort));
             const parsed = await this.parseResponseData(response);
+            if (this.shouldIgnoreRequestResult(requestId)) {
+                return;
+            }
             this.pageSize = parsed.pageable?.pageSize || size;
             this.totalElements = parsed.totalElements;
             this.items.set(parsed.content);
@@ -1438,42 +1598,62 @@ class PagedQueryStore {
             if (isAbort(e)) {
                 return;
             }
+            if (!this.shouldIgnoreRequestResult(requestId)) {
+                this.error.set(e);
+            }
             throw e;
         }
         finally {
-            this.loading.set(false);
+            this.#activeRequests = Math.max(0, this.#activeRequests - 1);
+            this.loading.set(this.#activeRequests > 0);
         }
     };
     initTransport() {
-        this.#transport = new ResourceStore({ [this.config.method || 'GET']: this.route }, {
+        this.#transport = runInInjectionContext(this.injector, () => new ResourceStore({ [this.config.method || 'GET']: this.route }, {
+            baseUrl: this.config.baseUrl,
             delay: this.config.debounceTime,
             delayMode: 'debounce',
             presetQueries: { page: this.page, size: this.pageSize },
             presetPayload: this.filters,
-        });
+            serializer: {
+                mapFields: {
+                    [this.resolveSortQueryKey()]: {
+                        type: 'array',
+                        concatType: 'multi',
+                    },
+                },
+            },
+        }));
     }
     async runTransport(payload, query, params) {
         if (this.config.method === 'GET') {
             return this.#transport.get({ query, params }, { promote: false, dedupe: true });
         }
-        const method = this.config.method?.toLowerCase() || 'post';
+        const method = (this.config.method?.toLowerCase() || 'post');
         // @ts-ignore
         return this.#transport[method]({ query, payload, params }, { promote: false, dedupe: true });
     }
-    parseQuery({ page = 0, size, filters, query = {} }) {
+    parseQuery({ page = 0, size, filters, query = {}, sort = this.sort }) {
         const method = this.config.method || 'GET';
-        const requestPayload = {
-            page,
-            size,
-            ...filters,
-            ...query,
-        };
-        const fallbackQuery = method === 'GET' ? requestPayload : { page, size, ...query };
+        const normalizedSort = this.normalizeSort(sort);
+        const sortQueryKey = this.resolveSortQueryKey();
+        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;
         const queries = {};
         Object.entries(rawQueries).forEach(([key, value]) => {
-            if (Array.isArray(value)) {
-                queries[key] = concatArray(value, 'comma');
+            if (key === sortQueryKey && Array.isArray(value)) {
+                if (value.every((item) => typeof item === 'string')) {
+                    queries[key] = value;
+                    return;
+                }
+                const sortRules = this.normalizeSort(value);
+                if (sortRules.length) {
+                    queries[key] = this.sortRulesToTokens(sortRules);
+                }
+            }
+            else if (Array.isArray(value)) {
+                queries[key] = value;
             }
             else if (!isNullable(value)) {
                 queries[key] = value;
@@ -1506,25 +1686,83 @@ class PagedQueryStore {
     parseFlatArray(data) {
         return { content: data, totalElements: data.length };
     }
+    resetDataset() {
+        this.page = 0;
+        this.totalElements = 0;
+        this.#cache.clear();
+        this.cached.set([]);
+        this.items.set([]);
+        this.error.set(null);
+        this.bumpVersion();
+    }
+    bumpVersion() {
+        this.version.update((current) => current + 1);
+    }
+    invalidateRequests() {
+        this.#requestId++;
+    }
+    resolveConcurrency() {
+        return this.config.concurrency || this.defaultConfig.defaultConcurrency || 'latest-wins';
+    }
+    shouldIgnoreRequestResult(requestId) {
+        return this.resolveConcurrency() === 'latest-wins' && requestId !== this.#requestId;
+    }
     applyConfig(config) {
         this.config = {
             ...config,
+            baseUrl: config.baseUrl ?? this.defaultConfig.defaultBaseUrl,
             method: config.method || this.defaultConfig.defaultMethod || 'POST',
             presetQuery: config.presetQuery || this.defaultConfig.defaultQuery,
             parseRequest: config.parseRequest || this.defaultConfig.defaultParseRequest,
+            sorting: config.sorting || this.defaultConfig.defaultSorting,
+            concurrency: config.concurrency || this.defaultConfig.defaultConcurrency || 'latest-wins',
             debounceTime: config.debounceTime || 0,
             hasCache: config.hasCache === undefined ? this.defaultConfig.defaultHasCache : config.hasCache,
-            cacheSize: config.cacheSize || this.defaultConfig.defaultCacheSize || 5,
+            cacheSize: config.cacheSize ?? this.defaultConfig.defaultCacheSize ?? 5,
+            disableCacheLimit: config.disableCacheLimit === undefined
+                ? (this.defaultConfig.defaultDisableCacheLimit ?? false)
+                : config.disableCacheLimit,
         };
         if (this.#cache) {
-            this.#cache.limit = this.config.cacheSize;
+            this.#cache.limit = this.resolveCacheLimit();
         }
     }
+    resolveCacheLimit() {
+        if (this.config.disableCacheLimit) {
+            return PagedQueryStore.DISABLED_CACHE_LIMIT;
+        }
+        return this.config.cacheSize ?? this.defaultConfig.defaultCacheSize ?? 5;
+    }
     applyPresetMeta() {
         this.filters = this.config.presetFilters || {};
+        this.#sort.set(this.normalizeSort(this.config.presetSort));
         this.pageSize = this.config.presetQuery?.pageSize || 20;
         this.page = this.config.presetQuery?.page || 0;
     }
+    normalizeSort(sort) {
+        return normalizeSortInput(sort);
+    }
+    resolveSortQueryKey() {
+        return this.config.sorting?.queryKey || 'sort';
+    }
+    sortRulesToTokens(sort) {
+        if (this.config.sorting?.serialize) {
+            return sort.map((item) => this.config.sorting.serialize(item));
+        }
+        return sortInputToTokens(sort);
+    }
+    reinitTransport() {
+        try {
+            this.invalidateRequests();
+            this.#transport?.abortAll?.('PagedQueryStore transport reconfigured');
+        }
+        catch (e) {
+            if (!isAbort(e)) {
+                throw e;
+            }
+        }
+        this.initTransport();
+    }
 }
 
 var _a;
@@ -1548,6 +1786,7 @@ class DictStore {
     apiUrl;
     storageKey;
     static MAX_CACHE_SIZE = 400;
+    static META_SUFFIX = ':meta';
     /**
      * Default dictionary configuration resolved from {@link STATUM_CONFIG}.
      *
@@ -1562,6 +1801,10 @@ class DictStore {
     valueKey;
     maxOptionsSize;
     storage;
+    metaStorage;
+    ttlMs;
+    revalidate;
+    cacheUpdatedAt = signal(null, ...(ngDevMode ? [{ debugName: "cacheUpdatedAt" }] : []));
     /**
      * Search text.
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
@@ -1600,7 +1843,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, 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 = 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', }) {
         this.apiUrl = apiUrl;
         this.storageKey = storageKey;
         const searchDebounce = debounceTime ?? 300;
@@ -1614,15 +1857,19 @@ class DictStore {
             debounceTime: debounceTime,
         });
         this.fixed = fixed;
+        this.ttlMs = ttlMs;
+        this.revalidate = revalidate;
         this.labelKey = labelKey;
         this.valueKey = valueKey;
         this.maxOptionsSize = maxOptionsSize;
         if (cacheStrategy !== 'memory') {
             this.storage = storageStrategy(cacheStrategy);
             this.storage.prefix = keyPrefix;
+            this.metaStorage = storageStrategy(cacheStrategy);
+            this.metaStorage.prefix = keyPrefix;
         }
-        this.setAutoload(autoLoad);
         this.restoreFromStorage();
+        this.setAutoload(autoLoad);
         this.#effectRefs.push(effect(() => {
             const incoming = this.#helper.items();
             if (incoming.length === 0) {
@@ -1641,9 +1888,12 @@ class DictStore {
                     this._lastPromise = this.#helper.fetch({ filters: { name: query, ...rest } });
                 });
             }
-            else if (!this.cachedItems().length) {
+            else if (this.shouldFetchFixedCache()) {
                 untracked(() => {
-                    this._lastPromise = this.#helper.fetch({ filters: { name: '', ...rest } });
+                    this._lastPromise = this.#helper.fetch({ filters: { name: '', ...rest } }).then((items) => {
+                        items?.length && this.mergeIntoCache(items);
+                        return items;
+                    });
                 });
             }
         }));
@@ -1652,6 +1902,13 @@ class DictStore {
     restoreCache() {
         this.restoreFromStorage();
     }
+    clearCache() {
+        this.#lru.clear();
+        this.cachedItems.set([]);
+        this.cacheUpdatedAt.set(null);
+        this.storage?.remove(this.storageKey);
+        this.metaStorage?.remove(this.metaKey());
+    }
     /**
      * Set a search query and filters.
      * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
@@ -1700,8 +1957,7 @@ class DictStore {
         }
         if (changed || opts?.replace) {
             const arr = this.#lru.toArray();
-            this.cachedItems.set(arr);
-            this.storage?.set(this.storageKey, arr.slice(0, _a.MAX_CACHE_SIZE));
+            this.persistCache(arr);
         }
     };
     /** Release resources and stop internal effects. */
@@ -1726,8 +1982,7 @@ class DictStore {
         }
         if (changed > 0) {
             const arr = this.#lru.toArray();
-            this.cachedItems.set(arr);
-            this.storage?.set(this.storageKey, arr.slice(0, _a.MAX_CACHE_SIZE));
+            this.persistCache(arr);
         }
     }
     restoreFromStorage() {
@@ -1741,19 +1996,29 @@ class DictStore {
                 this.#lru.set(key, it);
             }
             this.cachedItems.set(this.#lru.toArray());
+            this.cacheUpdatedAt.set(this.metaStorage?.get(this.metaKey())?.updatedAt ?? null);
         }
         catch {
             try {
                 this.storage?.remove(this.storageKey);
+                this.metaStorage?.remove(this.metaKey());
             }
             catch {
                 /* noop */
             }
         }
     }
+    persistCache(items) {
+        const capped = items.slice(0, _a.MAX_CACHE_SIZE);
+        const updatedAt = Date.now();
+        this.cachedItems.set(items);
+        this.cacheUpdatedAt.set(updatedAt);
+        this.storage?.set(this.storageKey, capped);
+        this.metaStorage?.set(this.metaKey(), { updatedAt });
+    }
     filterLocal() {
         const list = this.cachedItems();
-        const query = (this.fixed ? this.searchText() : this.debouncedSearchText()).toLowerCase();
+        const query = this.searchText().toLowerCase();
         if (!query) {
             return list;
         }
@@ -1776,13 +2041,38 @@ class DictStore {
     }
     setAutoload(autoLoad) {
         if (autoLoad === 'whenEmpty') {
-            const isEmpty = !this.storage?.get(this.storageKey)?.length;
-            this._armed.set(isEmpty);
+            const isEmpty = !this.cachedItems().length;
+            this._armed.set(isEmpty || this.shouldRevalidateCache());
         }
         else {
             this._armed.set(autoLoad);
         }
     }
+    shouldFetchFixedCache() {
+        return !this.cachedItems().length || this.shouldRevalidateCache();
+    }
+    shouldRevalidateCache() {
+        return this.revalidate && this.isCacheStale();
+    }
+    isCacheStale() {
+        if (!this.cachedItems().length) {
+            return false;
+        }
+        if (this.ttlMs == null) {
+            return false;
+        }
+        if (this.ttlMs <= 0) {
+            return true;
+        }
+        const updatedAt = this.cacheUpdatedAt();
+        if (updatedAt == null) {
+            return true;
+        }
+        return Date.now() - updatedAt >= this.ttlMs;
+    }
+    metaKey() {
+        return `${this.storageKey}${_a.META_SUFFIX}`;
+    }
 }
 _a = DictStore;