@reforgium/statum 2.1.2 → 3.0.0-rc.1

package/README.md

@@ -1,4 +1,4 @@
-# @reforgium/statum
+# @reforgium/statum
 
 [![npm version](https://badge.fury.io/js/%40reforgium%2Fstatum.svg)](https://www.npmjs.com/package/@reforgium/statum)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -25,13 +25,29 @@ Designed for **application state**, not abstract reducers.
 
 ---
 
-## Installation
-
-```bash
-npm install @reforgium/statum
-```
-
----
+## Installation
+
+```bash
+npm install @reforgium/statum
+```
+
+## Configuration
+
+```ts
+import { provideStatum } from '@reforgium/statum';
+
+providers: [
+  provideStatum({
+    pagedQuery: {
+      defaultMethod: 'GET',
+      defaultHasCache: true,
+      defaultCacheSize: 10,
+    },
+  }),
+];
+```
+
+---
 
 ## Package Structure
 
@@ -136,7 +152,7 @@ const user = await userStore.get(
 );
 ```
 
-Retry + trace example:
+Retry + trace example:
 
 ```ts
 import { ResourceStore } from '@reforgium/statum';
@@ -150,11 +166,22 @@ const store = new ResourceStore<{ id: number; name: string }>(
   }
 );
 
-await store.get(
-  { params: { id: '42' } },
-  { retry: { attempts: 1 } } // per-call override
-);
-```
+await store.get(
+  { params: { id: '42' } },
+  { retry: { attempts: 1 } } // per-call override
+);
+```
+
+Profiles example:
+
+```ts
+import { createResourceProfile, ResourceStore } from '@reforgium/statum';
+
+const usersStore = new ResourceStore<{ id: number; name: string }>(
+  { GET: '/users' },
+  createResourceProfile('table', { baseUrl: '/api' })
+);
+```
 
 ---
 
@@ -179,9 +206,9 @@ entities.removeOne(1);
 
 ---
 
-## PaginatedDataStore
-
-Lightweight store for server-side pagination with sorting, filtering, and page cache.
+## PagedQueryStore
+
+Lightweight store for server-side pagination with filtering, dynamic query params, and page cache.
 
 ### When to use
 
@@ -200,46 +227,54 @@ Lightweight store for server-side pagination with sorting, filtering, and page c
 | page           | `number`                  | Current page (0-based)                 |
 | pageSize       | `number`                  | Page size                              |
 | totalElements  | `number`                  | Total items on server                  |
-| filters        | `Partial<F>`              | Active filters                         |
-| sort           | `string \| undefined`     | Sort as `"field,asc"` / `"field,desc"` |
+| filters        | `Partial<F>`              | Active filters                         |
+| query          | `Record<string, unknown>` | Active query params                    |
 
 ### Methods
 
-| Method         | Description                                       |
-|----------------|---------------------------------------------------|
-| refresh        | Repeat request with current params                |
-| updatePage     | Change page (can use cache)                       |
-| updatePageSize | Change page size (can use cache)                  |
-| updateFilters  | Merge filters, reset cache, go to page 0          |
-| setFilters     | Replace filters, reset cache + sort, go to page 0 |
-| updateQuery    | Map table events to `page`/`sort`                 |
-| updateRoute    | Change endpoint, reset meta/cache                 |
-| setRouteParams | Fill route url with params                        |
-| updateConfig   | Patch config and apply presets                    |
-| copy           | Copy config/meta from another store               |
-| destroy        | Manual destroying of caches and abort requests    |
+| Method         | Description                                                               |
+|----------------|---------------------------------------------------------------------------|
+| fetch          | Clean first-page request: `fetch({ filters, query, routeParams })`       |
+| refetchWith        | Repeat request, optional merge overrides: `refetchWith({ filters, query })`  |
+| updatePage     | Change page: `updatePage(page, { ignoreCache })`                         |
+| updatePageSize | Change page size and reset cache: `updatePageSize(size)`                 |
+| updateByOffset | Table-event mapper: `updateByOffset({ page/first/rows }, { query })`    |
+| setRouteParams | Update route params: `setRouteParams(params, { reset, abort })`         |
+| updateConfig   | Patch config: `updateConfig(config)`                                     |
+| copy           | Copy config/meta: `copy(store)`                                          |
+| destroy        | Manual destroying of caches and abort requests                           |
+
+### Cache behavior
+
+| Method         | Cache read | Cache reset | Notes |
+|----------------|------------|-------------|-------|
+| fetch          | no         | yes         | Always starts clean from page `0` |
+| refetchWith        | no         | no          | Uses active page/filters/query, merges overrides |
+| updatePage     | yes        | no          | Can bypass with `ignoreCache: true` |
+| updatePageSize | no         | yes         | Prevents mixed caches for different page sizes |
+| updateByOffset | yes        | no          | Internally maps to `page + size` |
 
 Example:
 
 ```ts
-import { PaginatedDataStore } from '@reforgium/statum';
+import { PagedQueryStore } from '@reforgium/statum';
 
 type User = { id: number; name: string };
 
-const store = new PaginatedDataStore<User, { search?: string }>('api/users', {
-  method: 'GET',
-  debounceTime: 200,
-});
-
-store.updateFilters({ search: 'neo' });
-store.updatePage(1);
+const store = new PagedQueryStore<User, { search?: string }>('api/users', {
+  method: 'GET',
+  debounceTime: 200,
+});
+
+store.fetch({ filters: { search: 'neo' }, query: { tenant: 'kg' } });
+store.updateByOffset({ first: 20, rows: 20 });
 ```
 
 ---
 
 ## DictStore
 
-Helper for dictionaries/options (select/autocomplete) on top of PaginatedDataStore.
+Helper for dictionaries/options (select/autocomplete) on top of PagedQueryStore.
 
 ### When to use
 
@@ -309,15 +344,15 @@ dict.search('kir');   // local search over cache
 
 ## Composition Patterns
 
-### PaginatedDataStore + EntityStore
+### PagedQueryStore + EntityStore
 
 ```ts
 import { effect } from '@angular/core';
-import { EntityStore, PaginatedDataStore } from '@reforgium/statum';
+import { EntityStore, PagedQueryStore } from '@reforgium/statum';
 
 type User = { id: number; name: string };
 
-const pages = new PaginatedDataStore<User, { search?: string }>('/api/users');
+const pages = new PagedQueryStore<User, { search?: string }>('/api/users');
 const entities = new EntityStore<User, 'id'>({ idKey: 'id' });
 
 effect(() => {
@@ -325,7 +360,7 @@ effect(() => {
 });
 ```
 
-This keeps page-loading logic in `PaginatedDataStore` and normalized lookup/update logic in `EntityStore`.
+This keeps page-loading logic in `PagedQueryStore` and normalized lookup/update logic in `EntityStore`.
 
 ---
 
@@ -374,11 +409,12 @@ const body = serializer.serialize({ name: '  Vasya  ', active: null });
 
 ---
 
-## Source Structure
-
-- Cache: `src/cache`
-- Stores: `src/stores`
-- Serializer: `src/serializer`
+## Source Structure
+
+- Cache: `src/cache`
+- Stores: `src/stores`
+- Serializer: `src/serializer`
+- Migration: `MIGRATION.md`
 
 ---
 
@@ -393,3 +429,6 @@ const body = serializer.serialize({ name: '  Vasya  ', active: null });
 ## License
 
 MIT
+
+
+

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, inject, signal, computed, DestroyRef, effect, untracked } from '@angular/core';
+import { InjectionToken, makeEnvironmentProviders, inject, signal, computed, DestroyRef, effect, untracked } from '@angular/core';
 import { Subject, filter, timer, merge, map } from 'rxjs';
 import { debounce, tap, throttle, finalize } from 'rxjs/operators';
 
@@ -599,6 +599,7 @@ const storageStrategy = (strategy, options = {}) => {
 
 // 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.
@@ -1219,39 +1220,64 @@ class ResourceStore {
     }
 }
 
+const RESOURCE_PROFILES = {
+    table: {
+        ttlMs: 15_000,
+        delay: 120,
+        delayMode: 'debounce',
+        maxEntries: 500,
+    },
+    lookup: {
+        ttlMs: 60_000,
+        delay: 200,
+        delayMode: 'debounce',
+        maxEntries: 300,
+    },
+    mutation: {
+        ttlMs: 0,
+        delay: 0,
+        delayMode: 'throttle',
+        maxEntries: 50,
+    },
+};
+const createResourceProfile = (profile, overrides = {}) => ({
+    ...RESOURCE_PROFILES[profile],
+    ...overrides,
+});
+
 // noinspection ES6PreferShortImport
 /**
  * Store for paginated data (tables/lists) with per-page cache and unified requests.
  *
  * Provides:
  * - reactive signals: `items`, `loading`, `cached`;
- * - methods to control page/size/filters/sorting;
+ * - methods to control page/size/query;
  * - optional LRU cache by pages;
- * - configurable transport (GET/POST/PATCH/…).
+ * - configurable transport (GET/POST/PATCH/…).
  *
  * Example:
  * ```ts
- * const ds = new PaginatedDataStore<User>('/users', { method: 'GET', hasCache: true });
+ * const ds = new PagedQueryStore<User>('/users', { method: 'GET', hasCache: true });
  * await ds.updatePage(0); // load the first page
  * effect(() => console.log(ds.items(), ds.loading()));
  * ```
  */
-class PaginatedDataStore {
+class PagedQueryStore {
     route;
     config;
-    defaultConfig = inject(STATUM_CONFIG, { optional: true })?.paginatedData || {};
+    defaultConfig = inject(STATUM_CONFIG, { optional: true })?.pagedQuery || {};
     #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 = {};
-    /** Current sorting (`field,asc|desc`). */
-    sort;
+    /** Additional query params sent to transport requests. */
+    query = {};
     /** Current page index (0-based). */
     page = 0;
     /** Default page size. */
@@ -1272,17 +1298,32 @@ class PaginatedDataStore {
         this.initTransport();
         inject(DestroyRef).onDestroy(() => this.destroy());
     }
-    /** Force reload current data (with the same page/filters/sort). */
-    refresh() {
-        return this.#fetchItems({});
+    /**
+     * 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 });
+    };
+    /**
+     * Force reload current data.
+     * Optional args merge into active filters/query.
+     * Route params are intentionally not changed from `refetchWith`.
+     */
+    refetchWith({ filters, query } = {}) {
+        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 });
     }
     /**
      * Switch page with a request.
-     * If cache is enabled and the page is present in LRU — returns it from cache.
+     * 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
      */
-    updatePage = (page = this.page, ignoreCache = false) => {
+    updatePage = (page = this.page, { ignoreCache = false } = {}) => {
         if (this.config.hasCache && this.#cache.has(page) && !ignoreCache) {
             const cached = this.#cache.get(page);
             this.items.set(cached);
@@ -1298,61 +1339,31 @@ class PaginatedDataStore {
      * @param size new size (rows per page)
      */
     updatePageSize = (size = this.pageSize) => {
-        return this.#fetchItems({ page: 0, size });
-    };
-    /**
-     * Update filters (goes to the first page) and fetch.
-     * The previous cache is cleared.
-     */
-    updateFilters = (filters) => {
         this.#cache.clear();
         this.cached.set([]);
-        return this.#fetchItems({ page: 0, filters: { ...this.filters, ...filters } });
+        return this.#fetchItems({ page: 0, size });
     };
     /**
-     * Update the state from table events (PrimeNG, etc.) and fetch.
-     * Supports `page/first/rows/sortField/sortOrder`.
+     * Helper for offset-based table events (PrimeNG, etc.) with `page/first/rows`.
      */
-    updateQuery = ({ page: pageNum, first = 0, rows = 0, sortOrder, sortField }) => {
+    updateByOffset = ({ page: pageNum, first = 0, rows = 0 } = {}, { query = this.query } = {}) => {
         const page = (pageNum ?? (first && rows && Math.floor(first / rows))) || 0;
-        const sort = sortField ? `${sortField},${sortOrder === 1 ? 'asc' : 'desc'}` : '';
-        return this.#fetchItems({ page, sort });
-    };
-    /**
-     * Set filters from scratch (goes to the first page and resets sorting) and fetch.
-     * Useful for quick presets.
-     */
-    setFilters = (filters = {}) => {
-        this.#cache.clear();
-        this.cached.set([]);
-        return this.#fetchItems({ page: 0, filters, sort: undefined });
-    };
-    /**
-     * Change the resource route (resets page, cache, and presets) without fetching.
-     * Useful when one store should work with different endpoints.
-     */
-    updateRoute = (route) => {
-        this.route = route;
-        this.page = 0;
-        this.pageSize = 20;
-        this.totalElements = 0;
-        this.#cache.clear();
-        this.cached.set([]);
-        this.initTransport();
+        const size = rows || this.pageSize;
+        return this.#fetchItems({ page, size, query });
     };
     /**
      * 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   Options object
+     * @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 });
@@ -1371,7 +1382,7 @@ class PaginatedDataStore {
             this.cached.set([]);
             this.items.set([]);
         }
-        if (opts?.abort) {
+        if (opts.abort) {
             try {
                 this.#transport?.abortAll?.('Route params changed');
             }
@@ -1392,14 +1403,14 @@ class PaginatedDataStore {
     /**
      * Copy configuration and presets from another store of the same type.
      */
-    copy(helper) {
-        this.applyConfig(helper.config);
+    copy(store) {
+        this.applyConfig(store.config);
         this.applyPresetMeta();
     }
     /** Clean up resources and cancel active requests. Automatically called onDestroy. */
     destroy() {
         try {
-            this.#transport?.abortAll?.('PaginatedDataStore destroyed');
+            this.#transport?.abortAll?.('PagedQueryStore destroyed');
         }
         catch (e) {
             if (!isAbort(e)) {
@@ -1407,15 +1418,16 @@ class PaginatedDataStore {
             }
         }
     }
-    #fetchItems = async ({ page = this.page, size = this.pageSize, sort = this.sort, filters = this.filters, }) => {
-        const query = this.parseQuery({ page, size, sort, filters });
+    #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 });
         this.loading.set(true);
+        this.routeParams = routeParams;
         this.#transport.abortAll();
         try {
-            const response = await this.runTransport(filters, query);
+            const response = await this.runTransport(filters, builtQuery, routeParams);
             this.page = page;
-            this.sort = sort;
             this.filters = filters;
+            this.query = query;
             const parsed = await this.parseResponseData(response);
             this.pageSize = parsed.pageable?.pageSize || size;
             this.totalElements = parsed.totalElements;
@@ -1437,12 +1449,11 @@ class PaginatedDataStore {
         this.#transport = new ResourceStore({ [this.config.method || 'GET']: this.route }, {
             delay: this.config.debounceTime,
             delayMode: 'debounce',
-            presetQueries: { page: this.page, size: this.pageSize, sort: this.sort },
+            presetQueries: { page: this.page, size: this.pageSize },
             presetPayload: this.filters,
         });
     }
-    async runTransport(payload, query) {
-        const params = this.routeParams;
+    async runTransport(payload, query, params) {
         if (this.config.method === 'GET') {
             return this.#transport.get({ query, params }, { promote: false, dedupe: true });
         }
@@ -1450,10 +1461,16 @@ class PaginatedDataStore {
         // @ts-ignore
         return this.#transport[method]({ query, payload, params }, { promote: false, dedupe: true });
     }
-    parseQuery({ page = 0, size, sort, filters }) {
+    parseQuery({ page = 0, size, filters, query = {} }) {
         const method = this.config.method || 'GET';
-        const requestPayload = { page, size, ...(method === 'GET' ? filters : {}) };
-        const rawQueries = this.config.parseRequest?.({ ...requestPayload, sort }) || requestPayload;
+        const requestPayload = {
+            page,
+            size,
+            ...filters,
+            ...query,
+        };
+        const fallbackQuery = method === 'GET' ? requestPayload : { page, size, ...query };
+        const rawQueries = this.config.parseRequest?.(requestPayload) || fallbackQuery;
         const queries = {};
         Object.entries(rawQueries).forEach(([key, value]) => {
             if (Array.isArray(value)) {
@@ -1463,7 +1480,6 @@ class PaginatedDataStore {
                 queries[key] = value;
             }
         });
-        sort && (queries['sort'] = sort);
         return queries;
     }
     parseResponseData = async (data) => {
@@ -1509,7 +1525,6 @@ class PaginatedDataStore {
         this.filters = this.config.presetFilters || {};
         this.pageSize = this.config.presetQuery?.pageSize || 20;
         this.page = this.config.presetQuery?.page || 0;
-        this.sort = this.config.presetQuery?.sort;
     }
 }
 
@@ -1521,7 +1536,7 @@ var _a;
  * - reactive `items` (current list) and `options` (label/value),
  * - local cache filtering (`fixed: true`) or server-side search by name (`fixed: false`),
  * - preload and restore cache from `storage` (`localStorage/session/LRU`),
- * - smooth integration with `PaginatedDataStore` for server fetching.
+ * - smooth integration with `PagedQueryStore` for server fetching.
  *
  * Example:
  * ```ts
@@ -1561,7 +1576,7 @@ class DictStore {
     cachedItems = signal([], ...(ngDevMode ? [{ debugName: "cachedItems" }] : []));
     /**
      * Current list of dictionary items.
-     * Source — local cache (fixed=true) or data from `PaginatedDataStore`.
+     * Source — local cache (fixed=true) or data from `PagedQueryStore`.
      */
     items = computed(() => {
         const cached = this.cachedItems();
@@ -1591,7 +1606,7 @@ class DictStore {
         this.storageKey = storageKey;
         const searchDebounce = debounceTime ?? 300;
         this.debouncedSearchText = debounceSignal(this.searchText, searchDebounce);
-        this.#helper = new PaginatedDataStore(this.apiUrl, {
+        this.#helper = new PagedQueryStore(this.apiUrl, {
             method: method,
             hasCache: false,
             presetFilters: { name: '', ...presetFilters },
@@ -1624,12 +1639,12 @@ class DictStore {
             if (!this.fixed) {
                 const query = this.debouncedSearchText().trim();
                 untracked(() => {
-                    this._lastPromise = this.#helper.updateFilters({ name: query, ...rest });
+                    this._lastPromise = this.#helper.fetch({ filters: { name: query, ...rest } });
                 });
             }
             else if (!this.cachedItems().length) {
                 untracked(() => {
-                    this._lastPromise = this.#helper.updateFilters({ name: '', ...rest });
+                    this._lastPromise = this.#helper.fetch({ filters: { name: '', ...rest } });
                 });
             }
         }));
@@ -1640,7 +1655,7 @@ class DictStore {
     }
     /**
      * Set a search query and filters.
-     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
+     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
      */
     search = (name = '', filters = {}) => {
         this._armed.set(true);
@@ -2017,5 +2032,5 @@ class EntityStore {
  * Generated bundle index. Do not edit.
  */
 
-export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, LruCache, PaginatedDataStore, ResourceStore, STATUM_CONFIG, Serializer, SerializerFieldError, createBodySerializer, createQuerySerializer, createStrictSerializer, isAbort, storageStrategy };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, LruCache, PagedQueryStore, RESOURCE_PROFILES, ResourceStore, STATUM_CONFIG, Serializer, SerializerFieldError, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum, storageStrategy };
 //# sourceMappingURL=reforgium-statum.mjs.map

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.2",
+  "version": "3.0.0-rc.1",
   "name": "@reforgium/statum",
   "description": "reforgium State modules",
   "author": "rtommievich",
@@ -32,6 +32,7 @@
     "types/*.d.ts",
     "package.json",
     "README.md",
+    "MIGRATION.md",
     "CHANGELOG.md",
     "LICENSE*"
   ],

package/types/reforgium-statum.d.ts

@@ -1,6 +1,6 @@
-import { AnyType, AnyDict, RestMethods, PageableRequest, Query, PageableResponse } from '@reforgium/internal';
+import { AnyType, AnyDict, RestMethods, PageableRequest, PageableResponse, QueryParams } from '@reforgium/internal';
 import * as _angular_core from '@angular/core';
-import { Signal, WritableSignal, InjectionToken } from '@angular/core';
+import { Signal, WritableSignal, EnvironmentProviders, InjectionToken } from '@angular/core';
 import * as _reforgium_statum from '@reforgium/statum';
 
 /**
@@ -534,6 +534,29 @@ declare class ResourceStore<Data> {
     private promoteCurrent;
 }
 
+declare const RESOURCE_PROFILES: {
+    readonly table: {
+        readonly ttlMs: 15000;
+        readonly delay: 120;
+        readonly delayMode: "debounce";
+        readonly maxEntries: 500;
+    };
+    readonly lookup: {
+        readonly ttlMs: 60000;
+        readonly delay: 200;
+        readonly delayMode: "debounce";
+        readonly maxEntries: 300;
+    };
+    readonly mutation: {
+        readonly ttlMs: 0;
+        readonly delay: 0;
+        readonly delayMode: "throttle";
+        readonly maxEntries: 50;
+    };
+};
+type ResourceProfileName = keyof typeof RESOURCE_PROFILES;
+declare const createResourceProfile: (profile: ResourceProfileName, overrides?: ResourceStoreOptions) => ResourceStoreOptions;
+
 /**
  * Error thrown when requested data is missing in the cache.
  *
@@ -576,7 +599,7 @@ declare function isAbort(e: unknown): e is AbortError;
  * Controls request method, page cache, debounce delay, and
  * request/response transformations.
  */
-type PaginatedDataStoreConfig<ItemsType extends object, FilterType = unknown> = {
+type PagedQueryStoreConfig<ItemsType extends object, FilterType = unknown> = {
     /** Transport HTTP method: `GET`/`POST`/`PATCH`/`PUT`/`DELETE`. Defaults to global config or `POST`. */
     method?: RestMethods;
     /** Enable LRU cache for pages. */
@@ -585,19 +608,19 @@ type PaginatedDataStoreConfig<ItemsType extends object, FilterType = unknown> =
     cacheSize?: number;
     /** Debounce delay before request (ms). Useful for frequent filter changes. */
     debounceTime?: number;
-    /** Initial pagination/sort params. `page` is required. */
+    /** Initial pagination params. `page` is required. */
     presetQuery?: {
         page: number;
         pageSize?: number;
-        sort?: string;
     };
     /** Initial filters. Will be sent with the first request. */
     presetFilters?: Partial<FilterType>;
     /**
      * Custom transformation of request data into a query object.
-     * Useful for mapping `page/pageSize/sort` → API-specific keys.
+     * Useful for mapping `page/pageSize` and selected filter fields в†’ API-specific query keys.
+     * Returned object can contain nullable values; they are filtered before the transport call.
      */
-    parseRequest?: (data: PageableRequest) => Query;
+    parseRequest?: (data: PageableRequest & Partial<FilterType> & AnyDict) => AnyDict;
     /**
      * Custom parser of API response into unified `PageableResponse<ItemsType>`.
      * Use if the server returns an array or a "non-standard" structure.
@@ -605,60 +628,82 @@ type PaginatedDataStoreConfig<ItemsType extends object, FilterType = unknown> =
     parseResponse?: (data: AnyType) => PageableResponse<ItemsType> | Promise<PageableResponse<ItemsType>>;
 };
 /**
- * Global defaults for `PaginatedDataStore`.
+ * Global defaults for `PagedQueryStore`.
  * Can be provided via DI to avoid duplicating config in each store.
  */
-type PaginatedDataStoreProviderConfig = {
+type PagedQueryStoreProviderConfig = {
     /** Default method for all stores (if not overridden locally). */
     defaultMethod?: RestMethods;
-    /** Default base `page/pageSize/sort`. */
-    defaultQuery?: PaginatedDataStoreConfig<object>['presetQuery'];
-    /** Global `parseRequest` — maps pagination/sort into a query object. */
-    defaultParseRequest?: PaginatedDataStoreConfig<object>['parseRequest'];
+    /** Default base `page/pageSize`. */
+    defaultQuery?: PagedQueryStoreConfig<object>['presetQuery'];
+    /** Global `parseRequest` — maps pagination into a query object. */
+    defaultParseRequest?: PagedQueryStoreConfig<object>['parseRequest'];
     /** Whether to enable page cache by default. */
     defaultHasCache?: boolean;
     /** Default LRU page cache size. */
     defaultCacheSize?: number;
 };
 
-type PaginationType = {
+type OffsetPaginationType = {
     page?: number;
     first?: number | null;
     rows?: number | null;
-    sortField?: string | string[] | null;
-    sortOrder?: number | null;
 };
+type FetchParams<FilterType> = QueryParams<FilterType> & {
+    query?: AnyDict;
+    routeParams?: AnyDict;
+};
+type FetchInput<FilterType> = {
+    filters?: Partial<FilterType>;
+    query?: AnyDict;
+    routeParams?: AnyDict;
+};
+type RefetchWithInput<FilterType> = {
+    filters?: Partial<FilterType>;
+    query?: AnyDict;
+};
+type UpdatePageOptions = {
+    ignoreCache?: boolean;
+};
+type UpdateByOffsetOptions = {
+    query?: AnyDict;
+};
+type SetRouteParamsOptions = {
+    reset?: boolean;
+    abort?: boolean;
+};
+
 /**
  * Store for paginated data (tables/lists) with per-page cache and unified requests.
  *
  * Provides:
  * - reactive signals: `items`, `loading`, `cached`;
- * - methods to control page/size/filters/sorting;
+ * - methods to control page/size/query;
  * - optional LRU cache by pages;
- * - configurable transport (GET/POST/PATCH/…).
+ * - configurable transport (GET/POST/PATCH/…).
  *
  * Example:
  * ```ts
- * const ds = new PaginatedDataStore<User>('/users', { method: 'GET', hasCache: true });
+ * const ds = new PagedQueryStore<User>('/users', { method: 'GET', hasCache: true });
  * await ds.updatePage(0); // load the first page
  * effect(() => console.log(ds.items(), ds.loading()));
  * ```
  */
-declare class PaginatedDataStore<ItemsType extends object, FilterType = unknown> {
+declare class PagedQueryStore<ItemsType extends object, FilterType = unknown> {
     #private;
     private route;
-    config: PaginatedDataStoreConfig<ItemsType, FilterType>;
+    config: PagedQueryStoreConfig<ItemsType, FilterType>;
     private readonly defaultConfig;
     /** Current page data (reactive). */
     items: WritableSignal<ItemsType[]>;
-    /** Merged cache of pages (flat list) — handy for search/export. */
+    /** Merged cache of pages (flat list) — handy for search/export. */
     cached: WritableSignal<ItemsType[]>;
     /** Loading flag of the current operation. */
     loading: WritableSignal<boolean>;
     /** Current filters (applied to requests). */
     filters: Partial<FilterType>;
-    /** Current sorting (`field,asc|desc`). */
-    sort?: string | ReadonlyArray<string>;
+    /** Additional query params sent to transport requests. */
+    query: AnyDict;
     /** Current page index (0-based). */
     page: number;
     /** Default page size. */
@@ -670,72 +715,62 @@ declare class PaginatedDataStore<ItemsType extends object, FilterType = unknown>
      * @param route  Resource URL pattern (e.g., `'/users'`)
      * @param config Store behavior: method, cache, request/response parsers, debounce, presets, etc.
      */
-    constructor(route: string, config?: PaginatedDataStoreConfig<ItemsType, FilterType>);
-    /** Force reload current data (with the same page/filters/sort). */
-    refresh(): Promise<ItemsType[] | undefined>;
+    constructor(route: string, config?: PagedQueryStoreConfig<ItemsType, FilterType>);
+    /**
+     * Fetch data with explicit filters and query params from the first page.
+     * Replaces legacy `setFilters`.
+     */
+    fetch: ({ filters, query, routeParams }?: FetchInput<FilterType>) => Promise<ItemsType[] | undefined>;
+    /**
+     * Force reload current data.
+     * Optional args merge into active filters/query.
+     * Route params are intentionally not changed from `refetchWith`.
+     */
+    refetchWith({ filters, query }?: RefetchWithInput<FilterType>): Promise<ItemsType[] | undefined>;
     /**
      * Switch page with a request.
-     * If cache is enabled and the page is present in LRU — returns it from cache.
+     * 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
      */
-    updatePage: (page?: number, ignoreCache?: boolean) => Promise<ItemsType[] | undefined>;
+    updatePage: (page?: number, { ignoreCache }?: UpdatePageOptions) => Promise<ItemsType[] | undefined>;
     /**
      * Change page size (will go to the first page) and fetch.
      * @param size new size (rows per page)
      */
     updatePageSize: (size?: number) => Promise<ItemsType[] | undefined>;
     /**
-     * Update filters (goes to the first page) and fetch.
-     * The previous cache is cleared.
-     */
-    updateFilters: (filters: Partial<FilterType>) => Promise<ItemsType[] | undefined>;
-    /**
-     * Update the state from table events (PrimeNG, etc.) and fetch.
-     * Supports `page/first/rows/sortField/sortOrder`.
+     * Helper for offset-based table events (PrimeNG, etc.) with `page/first/rows`.
      */
-    updateQuery: ({ page: pageNum, first, rows, sortOrder, sortField }: PaginationType) => Promise<ItemsType[] | undefined>;
-    /**
-     * Set filters from scratch (goes to the first page and resets sorting) and fetch.
-     * Useful for quick presets.
-     */
-    setFilters: (filters?: Partial<FilterType>) => Promise<ItemsType[] | undefined>;
-    /**
-     * Change the resource route (resets page, cache, and presets) without fetching.
-     * Useful when one store should work with different endpoints.
-     */
-    updateRoute: (route: string) => void;
+    updateByOffset: ({ page: pageNum, first, rows }?: OffsetPaginationType, { query }?: UpdateByOffsetOptions) => Promise<ItemsType[] | undefined>;
     /**
      * 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   Options object
+     * @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?: AnyDict, opts?: {
-        reset?: boolean;
-        abort?: boolean;
-    }) => void;
+    setRouteParams: (params?: AnyDict, opts?: SetRouteParamsOptions) => void;
     /**
      * Update store config on the fly (without re-creation).
      * Does not trigger loading automatically.
      */
-    updateConfig: (config: PaginatedDataStoreConfig<ItemsType>) => void;
+    updateConfig: (config: PagedQueryStoreConfig<ItemsType, FilterType>) => void;
     /**
      * Copy configuration and presets from another store of the same type.
      */
-    copy(helper: PaginatedDataStore<ItemsType, FilterType>): void;
+    copy(store: PagedQueryStore<ItemsType, FilterType>): void;
     /** Clean up resources and cancel active requests. Automatically called onDestroy. */
     destroy(): void;
     private initTransport;
@@ -856,7 +891,7 @@ type ValueType = string[] | string | number | null | undefined;
  * - reactive `items` (current list) and `options` (label/value),
  * - local cache filtering (`fixed: true`) or server-side search by name (`fixed: false`),
  * - preload and restore cache from `storage` (`localStorage/session/LRU`),
- * - smooth integration with `PaginatedDataStore` for server fetching.
+ * - smooth integration with `PagedQueryStore` for server fetching.
  *
  * Example:
  * ```ts
@@ -894,7 +929,7 @@ declare class DictStore<Type extends AnyDict> {
     private cachedItems;
     /**
      * Current list of dictionary items.
-     * Source — local cache (fixed=true) or data from `PaginatedDataStore`.
+     * Source — local cache (fixed=true) or data from `PagedQueryStore`.
      */
     items: Signal<readonly Type[]>;
     /**
@@ -917,7 +952,7 @@ declare class DictStore<Type extends AnyDict> {
     restoreCache(): void;
     /**
      * Set a search query and filters.
-     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
+     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
      */
     search: (name?: string, filters?: AnyDict) => void;
     /**
@@ -1050,8 +1085,8 @@ declare class EntityStore<Entity extends AnyDict, IdKey extends keyof Entity = k
     private isValidId;
 }
 
-type PaginatedDataProviderConfig = {
-    paginatedData?: PaginatedDataStoreProviderConfig;
+type PagedQueryProviderConfig = {
+    pagedQuery?: PagedQueryStoreProviderConfig;
 };
 type SerializerProviderConfig = {
     serializer?: Partial<SerializerConfig>;
@@ -1059,9 +1094,10 @@ type SerializerProviderConfig = {
 type DictProviderConfig = {
     dict?: DictStoreProviderConfig;
 };
-type StatumConfig = PaginatedDataProviderConfig & SerializerProviderConfig & DictProviderConfig;
+type StatumConfig = PagedQueryProviderConfig & SerializerProviderConfig & DictProviderConfig;
 declare const STATUM_CONFIG: InjectionToken<StatumConfig>;
+declare const provideStatum: (config: StatumConfig) => EnvironmentProviders;
 
-export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, LruCache, PaginatedDataStore, ResourceStore, STATUM_CONFIG, Serializer, SerializerFieldError, createBodySerializer, createQuerySerializer, createStrictSerializer, isAbort, storageStrategy };
-export type { DataType, DictLocalConfig, DictStoreConfig, DictStoreProviderConfig, EntityId, EntityStoreConfig, FieldConfig, PaginatedDataStoreConfig, PaginatedDataStoreProviderConfig, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, ResourceTraceEvent, RetryConfig, SerializedType, SerializerConfig, StorageInterface, StorageStrategy, StorageStrategyOptions, Types };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, LruCache, PagedQueryStore, RESOURCE_PROFILES, ResourceStore, STATUM_CONFIG, Serializer, SerializerFieldError, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum, storageStrategy };
+export type { DataType, DictLocalConfig, DictStoreConfig, DictStoreProviderConfig, EntityId, EntityStoreConfig, FetchInput, FetchParams, FieldConfig, OffsetPaginationType, PagedQueryStoreConfig, PagedQueryStoreProviderConfig, RefetchWithInput, ResourceProfileName, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, ResourceTraceEvent, RetryConfig, SerializedType, SerializerConfig, SetRouteParamsOptions, StatumConfig, StorageInterface, StorageStrategy, StorageStrategyOptions, Types, UpdateByOffsetOptions, UpdatePageOptions };
 //# sourceMappingURL=reforgium-statum.d.ts.map