@reforgium/statum 1.0.0

package/types/reforgium-statum.d.ts

@@ -0,0 +1,852 @@
+import { AnyDict, AnyType, RestMethods, PageableRequest, Query, PageableResponse } from '@reforgium/internal';
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, WritableSignal } from '@angular/core';
+
+/**
+ * List of supported primitive and composite data types
+ * that can be serialized/deserialized.
+ *
+ * Used in field serialization configuration.
+ */
+type Types = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date' | 'period' | 'nullable';
+/**
+ * Allowed "flat" values after serialization.
+ * Such values are safe to pass in a query string or JSON.
+ */
+type SerializedPrimitives = string | number | boolean | null;
+type SerializedTypeType = SerializedPrimitives | SerializedPrimitives[];
+type DatePeriod = [Date | null, Date | null];
+/**
+ * Generic configuration shape to define `parse`/`format`
+ * for converting a value from/to a serialized form.
+ *
+ * @template TypeFrom — domain type before serialization
+ * @template TypeTo   — serialized type (by default a primitive/array of primitives)
+ */
+type ParseFormatConfig<TypeFrom, TypeTo = SerializedTypeType> = {
+    parse?: (val: TypeTo) => TypeFrom;
+    format?: (val: TypeFrom) => TypeTo;
+};
+/**
+ * Simplified configuration when only `format` is needed.
+ */
+type FormatConfig<TypeFrom, TypeTo = SerializedTypeType> = {
+    format?: (val: TypeFrom) => TypeTo;
+};
+type FieldConfig = {
+    type: Types;
+} | FieldsTypeConfig<DataType, AnyType>;
+type FieldsTypeConfig<EntityType extends DataType, TypeFrom, TypeTo = SerializedTypeType> = {
+    parse: (val: TypeTo, data: SerializedType) => TypeFrom;
+    format: (val: TypeFrom, data: EntityType) => TypeTo;
+};
+type PeriodSplitMode = {
+    mode: 'split';
+    dateFromKeyPostfix: string;
+    dateToKeyPostfix: string;
+};
+type PeriodJoinMode = {
+    mode: 'join';
+    concat: string;
+};
+type SerializerConfig = {
+    mapString: {
+        trim?: boolean;
+    } & ParseFormatConfig<string>;
+    mapNumber: {
+        fromString?: boolean;
+    } & ParseFormatConfig<number>;
+    mapBoolean: {
+        true?: string;
+        false?: string;
+    } & ParseFormatConfig<boolean>;
+    mapDate: {
+        dateFormat?: string;
+    } & ParseFormatConfig<Date>;
+    /**
+     * Settings for date period transformation.
+     * Allows choosing a mode:
+     *  - split: split the period into two keys (e.g., createdFrom/createdTo)
+     *  - join: join into a string using a delimiter
+     * And set the date format.
+     */
+    mapPeriod: {
+        transformMode?: PeriodSplitMode | PeriodJoinMode;
+        dateFormat?: string;
+    } & ParseFormatConfig<DatePeriod>;
+    /**
+     * Settings for handling "empty" values.
+     * - remove: remove the field from the result;
+     * - replaceWith: replace with a fixed value;
+     * - includeEmptyString: treat an empty string as "nullable".
+     */
+    mapNullable: {
+        remove?: boolean;
+        replaceWith?: string;
+        includeEmptyString?: boolean;
+    } & ParseFormatConfig<null | undefined>;
+    /**
+     * Array settings:
+     * - concatType: serialization strategy (`comma` | `multi` | `json`);
+     * - removeNullable: remove empty items;
+     * - format: custom array formatter.
+     */
+    mapArray: {
+        concatType: 'comma' | 'multi' | 'json';
+        removeNullable?: boolean;
+    } & FormatConfig<AnyType[]>;
+    /**
+     * Object settings:
+     * - deep: deep (recursive) serialization or treat as JSON string;
+     * - format: custom object formatter.
+     */
+    mapObject: {
+        deep: boolean;
+    } & FormatConfig<DataType>;
+    /**
+     * Per-field overrides by key.
+     */
+    mapFields?: Record<string, FieldConfig>;
+};
+/**
+ * Flat serialization result: dictionary key → primitive(s).
+ */
+type SerializedType = Record<string, SerializedTypeType>;
+/**
+ * Generic dictionary of domain data.
+ */
+type DataType = AnyDict;
+
+/**
+ * Universal serializer/deserializer for values used in forms, filters, and DTOs.
+ *
+ * Supports types: `string | number | boolean | Date | [Date, Date] (period) | array | object | nullable`.
+ * Capabilities:
+ * - normalize values according to config (trim strings, parse numbers from strings, boolean strings, etc.),
+ * - transform date periods into paired keys (`from/to`) or a single joined string,
+ * - build/parse a query string (or JSON) to and from an object.
+ *
+ * Example:
+ * ```ts
+ * type Filters = { q?: string; active?: boolean; created?: [Date, Date] | null };
+ * const s = new Serializer<Filters>({
+ *   mapPeriod: { transformMode: { mode: 'split', dateFromKeyPostfix: 'From', dateToKeyPostfix: 'To' } }
+ * });
+ *
+ * // -> { q: 'john', createdFrom: '2025-01-01', createdTo: '2025-01-31' }
+ * const plain = s.serialize({
+ *   q: '  john ',
+ *   active: undefined,
+ *   created: [new Date('2025-01-01'), new Date('2025-01-31')]
+ * });
+ *
+ * // -> 'q=john&createdFrom=2025-01-01&createdTo=2025-01-31'
+ * const qs = s.toQuery({ q: 'john', created: [new Date('2025-01-01'), new Date('2025-01-31')] });
+ *
+ * // <- { q: 'john', created: [Date, Date] }
+ * const parsed = s.deserialize('q=john&createdFrom=2025-01-01&createdTo=2025-01-31');
+ * ```
+ */
+declare class Serializer<EntityType extends DataType> {
+    readonly config: SerializerConfig;
+    /**
+     * Creates a serializer with a partially overridden configuration.
+     * Provide only the options you want to change (the rest are taken from defaults).
+     *
+     * @param config partial transformation configuration
+     */
+    constructor(config: Partial<SerializerConfig>);
+    /**
+     * Converts a domain object into a flat serialized representation
+     * (ready to send to an API or build a query string).
+     *
+     * Rules are taken from `config`:
+     * — strings can be trimmed (if enabled),
+     * — numbers can be converted from strings/numbers,
+     * — boolean supports custom true/false representations,
+     * — dates are formatted by `dateFormat`,
+     * — date periods can be split/joined,
+     * — `nullable` can be removed from the result (`remove`) or formatted.
+     *
+     * @param obj source object
+     * @returns a flat dictionary with string/primitive values
+     */
+    serialize(obj: EntityType): SerializedType;
+    /**
+     * Parse serialized data into a domain object.
+     *
+     * Source can be:
+     * — a query string (`key=value&arr=1,2`) or `JSON.stringify(obj)`,
+     * — an already prepared flat object.
+     *
+     * Transformations are reverse of `serialize`: strings → number/boolean/Date/period,
+     * arrays are collected according to strategy (`comma`/`pipe`/`multi`), objects — deeply or as JSON.
+     *
+     * @param val query string or object
+     * @returns a domain object of the specified type
+     */
+    deserialize: (val: string | AnyDict) => EntityType;
+    /**
+     * Build a query string from a domain object using `serialize` rules
+     * and the array joining strategy (`concatType`).
+     *
+     * @param val domain object
+     * @returns query string (suitable for URL or history API)
+     */
+    toQuery: (val: EntityType) => string;
+    /**
+     * Returns a new serializer instance with a merged configuration.
+     * Useful for ad-hoc overrides for a specific call.
+     *
+     * @param config partial config changes
+     * @returns new `Serializer` with the provided `config` applied
+     */
+    withConfig(config: Partial<SerializerConfig>): Serializer<EntityType>;
+    private serializeElement;
+    private deserializeElement;
+    private parseQuery;
+}
+
+declare const SERIALIZER_CONFIG: InjectionToken<Partial<SerializerConfig>>;
+
+type StorageStrategy = 'memory' | 'lru' | 'session' | 'persist';
+
+type StorageInterface<Key, Type> = {
+    get(key: Key): Type | null;
+    set(key: Key, value: Type): void;
+    remove(key: Key): void;
+    clear(): void;
+    get length(): number;
+};
+
+declare class LruCache<KeyT, ValueT> implements StorageInterface<KeyT, ValueT> {
+    limit: number;
+    private map;
+    constructor(limit?: number);
+    get length(): number;
+    get(key: KeyT): NonNullable<ValueT> | null;
+    set(key: KeyT, value: ValueT): void;
+    remove(key: KeyT): boolean;
+    clear(): void;
+    has(key: KeyT): boolean;
+    keys(): KeyT[];
+    values(): ValueT[];
+    toArray(): ValueT[];
+    fromArray(entries: [KeyT, ValueT][]): void;
+}
+
+/**
+ * Factory for data storage strategies.
+ *
+ * Returns a `StorageInterface` implementation depending on the selected strategy:
+ * - `'memory'`  — in-memory storage (for the session lifetime);
+ * - `'session'` — `sessionStorage`, lives until the tab is closed;
+ * - `'persist'` — `localStorage`, persists between sessions;
+ * - `'lru'`     — size-limited cache (Least Recently Used).
+ *
+ * Used to choose an appropriate storage implementation
+ * depending on the scenario: temporary data, long-term, cache, etc.
+ *
+ * @param strategy storage strategy type (`memory`, `session`, `persist`, `lru`)
+ * @returns instance implementing `StorageInterface<Key, Type>`
+ */
+declare const storageStrategy: <Key = string, Type extends AnyType = AnyDict>(strategy: StorageStrategy) => StorageInterface<Key, Type>;
+
+/**
+ * Object for request body (payload).
+ * Commonly used with POST/PUT/PATCH/DELETE.
+ */
+type PayloadData = AnyDict;
+/**
+ * Simple parameters dictionary (string/number).
+ * Suitable for path params and query.
+ */
+type SimpleDict = Record<string, string | number>;
+/**
+ * Resource status in `ResourceStore`:
+ * - `idle`    — not loaded yet
+ * - `loading` — request in progress
+ * - `success` — data successfully received
+ * - `error`   — request failed
+ * - `stale`   — showing cached data while background revalidation runs
+ */
+type ResourceStatus = 'idle' | 'loading' | 'success' | 'error' | 'stale';
+/**
+ * Delay mode for executing a request:
+ * - `debounce` — delay until silence
+ * - `throttle` — limit frequency
+ */
+type DelayMode = 'debounce' | 'throttle';
+/**
+ * Cache strategy for GET:
+ * - `network-first` — network preferred, cache as fallback
+ * - `cache-first`   — cache preferred, network if needed
+ * - `network-only`  — always network
+ * - `cache-only`    — cache only, throws `CacheMissError` if missing
+ */
+type CacheStrategy = 'network-first' | 'cache-first' | 'network-only' | 'cache-only';
+/**
+ * Map of route templates by HTTP methods.
+ * Example: `{ GET: '/users/:id', POST: '/users' }`
+ */
+type ResourceRoutesMap = Partial<Record<RestMethods, string>>;
+/**
+ * Global options for `ResourceStore`.
+ */
+type ResourceStoreOptions = {
+    /** Base URL for all requests (e.g., `/api`). */
+    baseUrl?: string;
+    /** Values automatically merged into each call's payload. */
+    presetPayload?: AnyDict;
+    /** Values automatically merged into each call's query. */
+    presetQueries?: AnyDict;
+    /** Delay before executing a request (ms). */
+    delay?: number;
+    /** Delay mode (`debounce`/`throttle`). */
+    delayMode?: DelayMode;
+    /** Cache freshness window (ms) for `cache-*` strategies. */
+    ttlMs?: number;
+};
+/**
+ * API call arguments.
+ * - `params`  — path parameters for the route template
+ * - `query`   — query string parameters
+ * - `payload` — request body (for mutations)
+ */
+type CallArgs<Params extends SimpleDict = SimpleDict, Query extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData> = {
+    params?: Params;
+    query?: Query;
+    payload?: Payload;
+};
+/**
+ * Common call configuration.
+ */
+type CallConfig<Response, Type> = {
+    /** Delay before execution (ms). */
+    delay?: number;
+    /** Delay mode (`debounce`/`throttle`). */
+    delayMode?: DelayMode;
+    /** Deduplicate concurrent identical requests. */
+    dedupe?: boolean;
+    /**
+     * Whether to promote the result to the "current" store (value/status/error).
+     * If `false`, the record remains only in the cache.
+     */
+    promote?: boolean;
+    /**
+     * Optional property to define the expected response data type.
+     *
+     * Possible values:
+     * - 'json' - response interpreted as JSON
+     * - 'text' - response interpreted as plain text
+     * - 'blob' - response as a Blob
+     * - 'arraybuffer' - response as an ArrayBuffer
+     */
+    responseType?: 'json' | 'text' | 'blob' | 'arraybuffer';
+    /**
+     * Custom response parser.
+     * Allows converting server `Response` to the domain type `Type`.
+     */
+    parseResponse?: ParseFn<Response, Type>;
+};
+/**
+ * Function that parses server response into the domain model.
+ */
+type ParseFn<Response, Type> = (data: Response) => Type;
+/**
+ * Special settings for GET requests.
+ */
+type GetCallConfig<Response, Type> = CallConfig<Response, Type> & {
+    strategy?: CacheStrategy;
+    revalidate?: boolean;
+    ttlMs?: number;
+};
+
+/**
+ * Store for REST resources with caching and request deduplication.
+ *
+ * Provides reactive access to current value, status, and error;
+ * supports cache strategies (cache-first / cache-only / network-first),
+ * TTL, delays (debounce/throttle), request cancellation, and auto-serialization of query/payload.
+ *
+ * Example:
+ * ```ts
+ * const store = new ResourceStore({ GET: '/users/:id' }, { baseUrl: '/api', ttlMs: 30_000 });
+ *
+ * effect(() => {
+ *   if (store.loading()) showSpinner();
+ *   if (store.error()) showError(store.error());
+ *   const user = store.value();
+ * });
+ *
+ * await store.get({ params: { id: '42' }, query: { expand: ['roles'] } }, { strategy: 'cache-first', dedupe: true });
+ * ```
+ */
+declare class ResourceStore<Data> {
+    #private;
+    private readonly http;
+    private readonly serializer;
+    /**
+     * Current resource value.
+     * Returns `null` if no data yet or the request failed.
+     */
+    value: Signal<Data | null>;
+    /**
+     * Current loading status of the resource: `idle | loading | stale | success | error`.
+     */
+    status: Signal<ResourceStatus>;
+    /**
+     * Last error (if any). Otherwise `null`.
+     */
+    error: Signal<unknown | null>;
+    /**
+     * Convenience loading flag: `true` when `loading` or `stale`.
+     * Useful for spinners and disabling buttons.
+     */
+    loading: Signal<boolean>;
+    private readonly routes;
+    private readonly opts;
+    private readonly entries;
+    private readonly scheduler;
+    /**
+     * @param routes Map of path templates for methods (`GET/POST/...` → `/users/:id`)
+     * @param opts   Global options (baseUrl, ttlMs, delay, delayMode, presetQueries/payload, etc.)
+     */
+    constructor(routes: ResourceRoutesMap, opts?: ResourceStoreOptions);
+    /**
+     * Perform a GET request.
+     *
+     * Supports cache strategies (`strategy`), TTL (`ttlMs`), revalidation,
+     * deduplication (`dedupe`), and response parsing (`parseResponse`).
+     *
+     * @param args { params, query }
+     * @param cfg  Call settings (strategy, ttlMs, revalidate, parseResponse, delay, delayMode, dedupe, promote)
+     * @returns Deserialized `Data`
+     */
+    get<Param extends SimpleDict = SimpleDict, Query extends PayloadData = PayloadData, Response extends AnyType = Data>(args: CallArgs<Param, Query, never>, cfg?: GetCallConfig<Response, Data>): Promise<Data>;
+    /**
+     * POST request.
+     *
+     * @param args { params, query, payload }
+     * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
+     * @returns API response (by default — as returned by the server)
+     */
+    post<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends PayloadData = PayloadData, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Payload>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    /**
+     * PUT request (full resource update).
+     *
+     * @param args { params, query, payload }
+     * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
+     * @returns API response (by default — as returned by the server)
+     */
+    put<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends SimpleDict = SimpleDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Partial<Payload>>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    /**
+     * PATCH request (partial update).
+     *
+     * @param args { params, query, payload }
+     * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
+     * @returns API response (by default — as returned by the server)
+     */
+    patch<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends SimpleDict = SimpleDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Partial<Payload>>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    /**
+     * DELETE request.
+     *
+     * @param args { params, query, payload }
+     * @param cfg  Call settings (parseResponse, delay, delayMode, dedupe, promote)
+     * @returns API response (by default — as returned by the server)
+     */
+    delete<Param extends SimpleDict = SimpleDict, Payload extends PayloadData = PayloadData, Query extends SimpleDict = SimpleDict, Response extends AnyType = AnyType>(args: CallArgs<Param, Query, Payload>, cfg?: CallConfig<Response, Response>): Promise<Response>;
+    /**
+     * Cancel scheduled/running requests for a specific call.
+     *
+     * @param method HTTP method
+     * @param args   Arguments used to build the URL (params, query)
+     * @param reason Cancellation reason (optional)
+     */
+    abort<Param extends SimpleDict = SimpleDict, Query extends PayloadData = PayloadData>(method: RestMethods, args: CallArgs<Param, Query>, reason?: string | Error): void;
+    /**
+     * Cancel all scheduled/running requests for this store.
+     *
+     * @param reason Cancellation reason (optional)
+     */
+    abortAll(reason?: string | Error): void;
+    private ensureEntry;
+    private callApi;
+    private buildUrl;
+    private prepareQuery;
+    private exec$;
+    private promoteCurrent;
+}
+
+/**
+ * Error thrown when requested data is missing in the cache.
+ *
+ * Used by the `cache-only` strategy when data is not found
+ * and a network request is not allowed.
+ *
+ * Example:
+ * ```ts
+ * try {
+ *   await store.get({ query }, { strategy: 'cache-only' });
+ * } catch (e) {
+ *   if (e instanceof CacheMissError) console.warn(e.key, 'not found in cache');
+ * }
+ * ```
+ */
+declare class CacheMissError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * Error indicating an aborted (canceled) request.
+ *
+ * May be thrown by `abort()` or `abortAll()` in `ResourceStore`.
+ * Usually does not require handling as an error — used to ignore canceled operations.
+ */
+declare class AbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Checks whether the exception is an `AbortError` (including compatible objects).
+ *
+ * @param e — any value that may be an error
+ * @returns `true` if it's an `AbortError`
+ */
+declare function isAbort(e: unknown): e is AbortError;
+
+/**
+ * Configuration for the paginated data store.
+ *
+ * Controls request method, page cache, debounce delay, and
+ * request/response transformations.
+ */
+type PaginatedDataConfig<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. */
+    hasCache?: boolean;
+    /** LRU cache size (number of pages). Defaults to global config. */
+    cacheSize?: number;
+    /** Debounce delay before request (ms). Useful for frequent filter changes. */
+    debounceTime?: number;
+    /** Initial pagination/sort 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.
+     */
+    parseRequest?: (data: PageableRequest) => Query;
+    /**
+     * Custom parser of API response into unified `PageableResponse<ItemsType>`.
+     * Use if the server returns an array or a "non-standard" structure.
+     */
+    parseResponse?: (data: AnyType) => PageableResponse<ItemsType>;
+};
+/**
+ * Global defaults for `PaginatedDataStore`.
+ * Can be provided via DI to avoid duplicating config in each store.
+ */
+interface PaginatedDataStoreConfig {
+    /** Default method for all stores (if not overridden locally). */
+    defaultMethod?: RestMethods;
+    /** Default base `page/pageSize/sort`. */
+    defaultQuery?: PaginatedDataConfig<object>['presetQuery'];
+    /** Global `parseRequest` — maps pagination/sort into a query object. */
+    defaultParseRequest?: PaginatedDataConfig<object>['parseRequest'];
+    /** Whether to enable page cache by default. */
+    defaultHasCache?: boolean;
+    /** Default LRU page cache size. */
+    defaultCacheSize?: number;
+}
+
+declare const PDS_CONFIG: InjectionToken<PaginatedDataStoreConfig>;
+
+type PaginationType = {
+    page?: number;
+    first?: number | null;
+    rows?: number | null;
+    sortField?: string | string[] | null;
+    sortOrder?: number | null;
+};
+/**
+ * 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;
+ * - optional LRU cache by pages;
+ * - configurable transport (GET/POST/PATCH/…).
+ *
+ * Example:
+ * ```ts
+ * const ds = new PaginatedDataStore<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> {
+    #private;
+    private route;
+    config: PaginatedDataConfig<ItemsType, FilterType>;
+    private readonly defaultConfig;
+    /** Current page data (reactive). */
+    items: WritableSignal<ItemsType[]>;
+    /** 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>;
+    /** Current page index (0-based). */
+    page: number;
+    /** Default page size. */
+    pageSize: number;
+    /** Total number of elements reported by the server. */
+    totalElements: number;
+    /**
+     * @param route  Resource URL pattern (e.g., `'/users'`)
+     * @param config Store behavior: method, cache, request/response parsers, debounce, presets, etc.
+     */
+    constructor(route: string, config?: PaginatedDataConfig<ItemsType, FilterType>);
+    /** Force reload current data (with the same page/filters/sort). */
+    refresh(): Promise<ItemsType[] | undefined>;
+    /**
+     * 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
+     */
+    updatePage: (page?: number, ignoreCache?: boolean) => 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.
+     * Previous cache is cleared.
+     */
+    updateFilters: (filters: Partial<FilterType>) => Promise<ItemsType[] | undefined>;
+    /**
+     * Update state from table events (PrimeNG, etc.) and fetch.
+     * Supports `page/first/rows/sortField/sortOrder`.
+     */
+    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 resource route (resets page, cache, and presets) without fetching.
+     * Useful when one store should work with different endpoints.
+     */
+    updateRoute: (route: string) => void;
+    /**
+     * Update store config on the fly (without re-creation).
+     * Does not trigger loading automatically.
+     */
+    updateConfig: (config: PaginatedDataConfig<ItemsType>) => void;
+    /**
+     * Copy configuration and presets from another store of the same type.
+     */
+    copy(helper: PaginatedDataStore<ItemsType, FilterType>): void;
+    /** Clean up resources and cancel active requests. Called automatically onDestroy. */
+    destroy(): void;
+    private initTransport;
+    private runTransport;
+    private parseQuery;
+    private parseResponseData;
+    private updateCache;
+    private parseFlatArray;
+    private applyConfig;
+    private applyPresetMeta;
+}
+
+/**
+ * `DictStore` configuration (dictionary for select/options).
+ *
+ * Configures cache strategy, autoload, request/response parsers,
+ * search mode (local/server) and label/value fields.
+ */
+type DictStoreConfig<ItemsType extends object> = {
+    /**
+     * Cache strategy for options:
+     * - 'memory'  — in-memory only,
+     * - 'session' — sessionStorage,
+     * - 'persist' — localStorage.
+     * ('lru' is excluded: used internally for inner structures)
+     */
+    cacheStrategy?: Omit<StorageStrategy, 'lru'>;
+    /** Initial filters (added to the first request/filtering). */
+    presetFilters?: Record<string, string>;
+    /** Autoload data on initialization (`true` by default). */
+    autoLoad?: boolean;
+    /**
+     * Custom mapper of pagination/sort request into query params.
+     * Useful if the API expects non-standard field names.
+     */
+    parseRequest?: (data: PageableRequest) => AnyDict;
+    /**
+     * Custom parser of server response into a unified PageableResponse.
+     * Needed if the API returns an array or a "non-standard" structure.
+     */
+    parseResponse?: (data: AnyType) => PageableResponse<ItemsType>;
+    /** Transport method for fetching the dictionary. Defaults to 'POST'. */
+    method?: 'GET' | 'POST';
+    /** Debounce delay before request (ms) — for frequent input/search. */
+    debounceTime?: number;
+    /** Maximum number of options exposed (truncates `options`). */
+    maxOptionsSize?: number;
+    /** Field key for label in a dictionary item. Defaults to `'name'`. */
+    labelKey?: keyof ItemsType & string;
+    /** Field key for value in a dictionary item. Defaults to `'code'`. */
+    valueKey?: keyof ItemsType & string;
+    /**
+     * Search mode:
+     * - `true`  — local (filters cache by label),
+     * - `false` — server (calls API by `name`).
+     * Defaults to `true`.
+     */
+    fixed?: boolean;
+};
+type DictLocalConfig<ItemsType extends object> = {
+    /** Maximum number of options exposed (truncates `options`). */
+    maxOptionsSize?: number;
+    /** Field key for label in a dictionary item. Defaults to `'name'`. */
+    labelKey?: keyof ItemsType & string;
+    /** Field key for value in a dictionary item. Defaults to `'code'`. */
+    valueKey?: keyof ItemsType & string;
+};
+type ValueType = string[] | string | number | null | undefined;
+
+/**
+ * Dictionary store (select/options) with local LRU cache and optional persistence.
+ *
+ * Provides:
+ * - 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.
+ *
+ * Example:
+ * ```ts
+ * const dict = new DictStore<Country>('/countries', 'countries', { labelKey: 'name', valueKey: 'code' });
+ * dict.search('ki'); // filters locally (fixed=true) or goes to server (fixed=false)
+ * effect(() => console.log(dict.options())); // [{label:'Kyrgyzstan', value:'KG'}, ...]
+ * ```
+ */
+declare class DictStore<Type extends AnyDict> {
+    #private;
+    private apiUrl;
+    private storageKey;
+    static readonly MAX_CACHE_SIZE = 400;
+    private readonly fixed;
+    private readonly labelKey;
+    private readonly valueKey;
+    private readonly maxOptionsSize?;
+    private readonly storage?;
+    /**
+     * Search text.
+     * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
+     */
+    searchText: _angular_core.WritableSignal<string>;
+    /**
+     * Additional filters for server request (or presets).
+     */
+    filters: _angular_core.WritableSignal<AnyDict>;
+    private cachedItems;
+    /**
+     * Current list of dictionary items.
+     * Source — local cache (fixed=true) or data from `PaginatedDataStore`.
+     */
+    items: _angular_core.Signal<readonly Type[]>;
+    /**
+     * Ready-to-use dropdown options: `{ label, value }`.
+     * Respects `maxOptionsSize` for truncating the list.
+     */
+    options: _angular_core.Signal<{
+        label: string;
+        value: Type[keyof Type & string];
+    }[]>;
+    private _lastPromise;
+    private _armed;
+    /**
+     * @param apiUrl      dictionary endpoint (e.g., `'/api/dicts/countries'`)
+     * @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, { method, autoLoad, presetFilters, parseResponse, parseRequest, debounceTime, fixed, maxOptionsSize, labelKey, valueKey, cacheStrategy, }: DictStoreConfig<Type>);
+    /** Восстановить кэш из выбранного хранилища (`persist`/`session`/`lru`/`memory`). */
+    restoreCache(): void;
+    /**
+     * Установить запрос и фильтры.
+     * При `fixed: false` инициирует серверный поиск; при `fixed: true` — локальную фильтрацию.
+     */
+    search: (name?: string, filters?: AnyDict) => void;
+    /**
+     * Найти отображаемую метку по значению (обычно для обратного биндинга).
+     * @returns строка метки или `undefined`, если не найдено
+     */
+    findLabel: (value: ValueType) => string | undefined;
+    /**
+     * Предзагрузить элементы словаря в локальный кэш.
+     * Удобно для SSR/статических списков/быстрых пресетов.
+     *
+     * @param items список элементов
+     * @param opts  `{ replace?: true }` — полностью заменить текущий кэш
+     */
+    preload: (items: readonly Type[], opts?: {
+        replace?: boolean;
+    }) => void;
+    /** Освободить ресурсы и остановить внутренние эффекты. */
+    dispose(): void;
+    /** Синтаксический сахар для `using`/`Symbol.dispose`. */
+    [Symbol.dispose](): void;
+    private mergeIntoCache;
+    private restoreFromStorage;
+    private filterLocal;
+    private keyOf;
+}
+
+declare class DictLocalStore<Type extends AnyDict> {
+    #private;
+    items: _angular_core.WritableSignal<readonly Type[]>;
+    /**
+     * Ready-to-use options for dropdowns: `{ label, value }`.
+     * Respects `maxOptionsSize` to truncate the list.
+     */
+    options: _angular_core.Signal<{
+        label: string;
+        value: Type[keyof Type & string];
+    }[]>;
+    private readonly labelKey;
+    private readonly valueKey;
+    private readonly maxOptionsSize?;
+    constructor(items: Type[], config?: DictLocalConfig<Type>);
+    /**
+     * No-op method for API compatibility with DictStore.
+     */
+    restoreCache(): void;
+    /**
+     * Find display label by value (usually for reverse binding).
+     * @returns label string or `undefined` if not found
+     */
+    findLabel: (value: ValueType) => string | undefined;
+    search: (name?: string) => void;
+    preload: (items: readonly Type[], opts?: {
+        replace?: boolean;
+    }) => void;
+}
+
+export { AbortError, CacheMissError, DictLocalStore, DictStore, LruCache, PDS_CONFIG, PaginatedDataStore, ResourceStore, SERIALIZER_CONFIG, Serializer, isAbort, storageStrategy };
+export type { DataType, DictLocalConfig, DictStoreConfig, FieldConfig, PaginatedDataConfig, PaginatedDataStoreConfig, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, SerializedType, SerializerConfig, StorageInterface, StorageStrategy, Types };
+//# sourceMappingURL=reforgium-statum.d.ts.map