@reforgium/statum 3.0.0-rc.1 → 3.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
-  "version": "3.0.0-rc.1",
+  "version": "3.0.0",
   "name": "@reforgium/statum",
-  "description": "reforgium State modules",
+  "description": "Signals-first query and data stores for Angular",
   "author": "rtommievich",
   "license": "MIT",
   "type": "module",
@@ -42,7 +42,7 @@
   "peerDependencies": {
     "@angular/common": ">=18.0.0",
     "@angular/core": ">=18.0.0",
-    "@reforgium/internal": ">=1.1.0",
+    "@reforgium/internal": ">=1.3.0",
     "rxjs": ">=7.0.0"
   },
   "module": "fesm2022/reforgium-statum.mjs",

package/types/reforgium-statum.d.ts

@@ -1,4 +1,4 @@
-import { AnyType, AnyDict, RestMethods, PageableRequest, PageableResponse, QueryParams } from '@reforgium/internal';
+import { AnyType, AnyDict, RestMethods, QueryParams, PageableRequest, PageableResponse } from '@reforgium/internal';
 import * as _angular_core from '@angular/core';
 import { Signal, WritableSignal, EnvironmentProviders, InjectionToken } from '@angular/core';
 import * as _reforgium_statum from '@reforgium/statum';
@@ -10,6 +10,7 @@ import * as _reforgium_statum from '@reforgium/statum';
  * Used in field serialization configuration.
  */
 type Types = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date' | 'period' | 'nullable';
+type FieldConcatType = 'comma' | 'multi' | 'json';
 /**
  * Allowed "flat" values after serialization.
  * Such values are safe to pass in a query string or JSON.
@@ -34,9 +35,12 @@ type ParseFormatConfig<TypeFrom, TypeTo = SerializedTypeType> = {
 type FormatConfig<TypeFrom, TypeTo = SerializedTypeType> = {
     format?: (val: TypeFrom) => TypeTo;
 };
-type FieldConfig = {
+type FieldConfig = ({
     type: Types;
-} | FieldsTypeConfig<DataType, AnyType>;
+    concatType?: FieldConcatType;
+} | FieldsTypeConfig<DataType, AnyType>) & {
+    concatType?: FieldConcatType;
+};
 type FieldsTypeConfig<EntityType extends DataType, TypeFrom, TypeTo = SerializedTypeType> = {
     parse: (val: TypeTo, data: SerializedType) => TypeFrom;
     format: (val: TypeFrom, data: EntityType) => TypeTo;
@@ -93,7 +97,7 @@ type SerializerConfig = {
      * - format: custom array formatter.
      */
     mapArray: {
-        concatType: 'comma' | 'multi' | 'json';
+        concatType: FieldConcatType;
         removeNullable?: boolean;
     } & FormatConfig<AnyType[]>;
     /**
@@ -219,6 +223,7 @@ declare class Serializer<EntityType extends DataType> {
     private parseJsonObject;
     private parseInputString;
     private mergeConfig;
+    private resolveArrayFieldModes;
 }
 
 declare const createQuerySerializer: <EntityType extends DataType = DataType>(config?: Partial<SerializerConfig>) => Serializer<EntityType>;
@@ -241,11 +246,11 @@ type StorageInterface<Key, Type> = {
 
 declare class LruCache<KeyT, ValueT> implements StorageInterface<KeyT, ValueT> {
     private map;
-    constructor(limit?: number);
     private _limit;
+    constructor(limit?: number);
     get limit(): number;
-    set limit(value: number);
     get length(): number;
+    set limit(value: number);
     get(key: KeyT): NonNullable<ValueT> | null;
     set(key: KeyT, value: ValueT): void;
     remove(key: KeyT): boolean;
@@ -342,6 +347,7 @@ type ResourceStoreOptions = {
     retry?: RetryConfig;
     /** Trace hook for request/cache lifecycle events. */
     onTrace?: (event: ResourceTraceEvent) => void;
+    serializer?: Partial<SerializerConfig>;
 };
 /**
  * API call arguments.
@@ -459,6 +465,7 @@ declare class ResourceStore<Data> {
     private readonly maxEntries;
     private readonly entries;
     private readonly scheduler;
+    private readonly mutationMethods;
     /**
      * @param routes Map of path templates for methods (`GET/POST/...` → `/users/:id`)
      * @param opts   Global options (baseUrl, ttlMs, delay, delayMode, presetQueries/payload, etc.)
@@ -526,12 +533,14 @@ declare class ResourceStore<Data> {
     private callApi;
     private buildUrl;
     private prepareQuery;
+    private preparePayload;
     private trace;
     private resolveRetryConfig;
     private defaultShouldRetry;
     private runWithRetry;
     private exec$;
     private promoteCurrent;
+    private isEmptyObject;
 }
 
 declare const RESOURCE_PROFILES: {
@@ -593,21 +602,70 @@ declare class AbortError extends Error {
  */
 declare function isAbort(e: unknown): e is AbortError;
 
+type QuerySortOrder = 'asc' | 'desc';
+type QuerySortRule<Key extends string = string> = {
+    sort: Key;
+    order: QuerySortOrder;
+};
+type QuerySortInput<Key extends string = string> = QuerySortRule<Key> | ReadonlyArray<QuerySortRule<Key>> | null | undefined;
+type PagedQueryConcurrency = 'latest-wins' | 'parallel';
+type OffsetPaginationType = {
+    page?: number;
+    first?: number | null;
+    rows?: number | null;
+};
+type FetchParams<FilterType> = Omit<QueryParams<FilterType>, 'sort'> & {
+    query?: AnyDict;
+    routeParams?: AnyDict;
+    sort?: QuerySortInput;
+};
+type FetchInput<FilterType> = {
+    filters?: Partial<FilterType>;
+    query?: AnyDict;
+    routeParams?: AnyDict;
+    sort?: QuerySortInput;
+};
+type RefetchWithInput<FilterType> = {
+    filters?: Partial<FilterType>;
+    query?: AnyDict;
+    sort?: QuerySortInput;
+};
+type UpdatePageOptions = {
+    ignoreCache?: boolean;
+};
+type UpdatePageInput = UpdatePageOptions & {
+    page?: number;
+};
+type UpdateByOffsetOptions = {
+    query?: AnyDict;
+    sort?: QuerySortInput;
+};
+type SetRouteParamsOptions = {
+    reset?: boolean;
+    abort?: boolean;
+};
+
 /**
  * Configuration for the paginated data store.
  *
- * Controls request method, page cache, debounce delay, and
+ * Controls request method, page cache, debounce delay, concurrency policy, and
  * request/response transformations.
  */
 type PagedQueryStoreConfig<ItemsType extends object, FilterType = unknown> = {
+    /** Optional base URL prepended to the route before the request is sent. */
+    baseUrl?: string;
     /** 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;
+    /** Disable LRU eviction and keep all loaded pages in memory. */
+    disableCacheLimit?: boolean;
     /** Debounce delay before request (ms). Useful for frequent filter changes. */
     debounceTime?: number;
+    /** Concurrency policy for overlapping requests. Defaults to `latest-wins`. */
+    concurrency?: PagedQueryConcurrency;
     /** Initial pagination params. `page` is required. */
     presetQuery?: {
         page: number;
@@ -615,62 +673,48 @@ type PagedQueryStoreConfig<ItemsType extends object, FilterType = unknown> = {
     };
     /** Initial filters. Will be sent with the first request. */
     presetFilters?: Partial<FilterType>;
+    /** Initial sort applied to requests. */
+    presetSort?: ReadonlyArray<QuerySortRule>;
     /**
      * Custom transformation of request data into a query object.
-     * Useful for mapping `page/pageSize` and selected filter fields в†’ API-specific query keys.
+     * Useful for mapping `page/pageSize` and selected filter fields to API-specific query keys.
      * Returned object can contain nullable values; they are filtered before the transport call.
      */
     parseRequest?: (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.
+     * Use if the server returns an array or a non-standard structure.
      */
     parseResponse?: (data: AnyType) => PageableResponse<ItemsType> | Promise<PageableResponse<ItemsType>>;
+    /** Sorting query serialization. Defaults to repeated `sort=a,asc` params. */
+    sorting?: {
+        queryKey?: string;
+        serialize?: (sort: QuerySortRule) => string;
+    };
 };
 /**
  * Global defaults for `PagedQueryStore`.
  * Can be provided via DI to avoid duplicating config in each store.
  */
 type PagedQueryStoreProviderConfig = {
+    /** Default base URL for all stores (if not overridden locally). */
+    defaultBaseUrl?: string;
     /** Default method for all stores (if not overridden locally). */
     defaultMethod?: RestMethods;
     /** Default base `page/pageSize`. */
     defaultQuery?: PagedQueryStoreConfig<object>['presetQuery'];
-    /** Global `parseRequest` — maps pagination into a query object. */
+    /** Global `parseRequest` maps pagination into a query object. */
     defaultParseRequest?: PagedQueryStoreConfig<object>['parseRequest'];
+    /** Global default sorting config. */
+    defaultSorting?: PagedQueryStoreConfig<object>['sorting'];
+    /** Global default concurrency policy. */
+    defaultConcurrency?: PagedQueryStoreConfig<object>['concurrency'];
     /** Whether to enable page cache by default. */
     defaultHasCache?: boolean;
     /** Default LRU page cache size. */
     defaultCacheSize?: number;
-};
-
-type OffsetPaginationType = {
-    page?: number;
-    first?: number | null;
-    rows?: 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;
+    /** Disable LRU eviction globally for all stores unless overridden locally. */
+    defaultDisableCacheLimit?: boolean;
 };
 
 /**
@@ -693,47 +737,88 @@ declare class PagedQueryStore<ItemsType extends object, FilterType = unknown> {
     #private;
     private route;
     config: PagedQueryStoreConfig<ItemsType, FilterType>;
+    private static readonly DISABLED_CACHE_LIMIT;
     private readonly defaultConfig;
+    private readonly injector;
     /** 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>;
+    /** Last request error (if any). */
+    error: WritableSignal<unknown>;
+    /** Increments when the current dataset is reset/replaced. Useful for external consumers with local buffers. */
+    version: WritableSignal<number>;
+    readonly pageState: _angular_core.Signal<number>;
+    readonly pageSizeState: _angular_core.Signal<number>;
+    readonly totalElementsState: _angular_core.Signal<number>;
+    readonly filtersState: _angular_core.Signal<Partial<FilterType>>;
+    readonly queryState: _angular_core.Signal<AnyDict>;
+    readonly sortState: _angular_core.Signal<QuerySortRule[]>;
+    readonly routeParamsState: _angular_core.Signal<AnyDict>;
+    /**
+     * @param route  Resource URL pattern (e.g., `'/users'`)
+     * @param config Store behavior: method, cache, request/response parsers, debounce, presets, etc.
+     */
+    constructor(route: string, config?: PagedQueryStoreConfig<ItemsType, FilterType>);
     /** Current filters (applied to requests). */
-    filters: Partial<FilterType>;
+    get filters(): Partial<FilterType>;
     /** Additional query params sent to transport requests. */
-    query: AnyDict;
+    get query(): AnyDict;
     /** Current page index (0-based). */
-    page: number;
+    get page(): number;
     /** Default page size. */
-    pageSize: number;
+    get pageSize(): number;
     /** Total number of elements reported by the server. */
-    totalElements: number;
-    routeParams: AnyDict;
+    get totalElements(): number;
+    /** Current sort rules. */
+    get sort(): QuerySortRule[];
     /**
-     * @param route  Resource URL pattern (e.g., `'/users'`)
-     * @param config Store behavior: method, cache, request/response parsers, debounce, presets, etc.
+     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
      */
-    constructor(route: string, config?: PagedQueryStoreConfig<ItemsType, FilterType>);
+    set filters(value: Partial<FilterType>);
+    /**
+     * @deprecated Prefer `fetch(...)`, `refetchWith(...)`, or a dedicated setter method.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
+     */
+    set query(value: AnyDict);
+    /**
+     * @deprecated Prefer `updatePage(...)`, `fetch(...)`, or `refetchWith(...)`.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
+     */
+    set page(value: number);
+    /**
+     * @deprecated Prefer `updatePageSize(...)`.
+     * Direct state mutation bypasses request semantics and should be treated as legacy.
+     */
+    set pageSize(value: number);
+    /**
+     * @deprecated Managed by transport responses. Direct assignment should be treated as legacy.
+     */
+    set totalElements(value: number);
     /**
      * Fetch data with explicit filters and query params from the first page.
      * Replaces legacy `setFilters`.
      */
-    fetch: ({ filters, query, routeParams }?: FetchInput<FilterType>) => Promise<ItemsType[] | undefined>;
+    fetch: ({ filters, query, routeParams, sort }?: 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>;
+    refetchWith({ filters, query, sort }?: 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.
-     * @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?: number, { ignoreCache }?: UpdatePageOptions) => Promise<ItemsType[] | undefined>;
+    updatePage: (page?: number | {
+        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)
@@ -742,7 +827,10 @@ declare class PagedQueryStore<ItemsType extends object, FilterType = unknown> {
     /**
      * Helper for offset-based table events (PrimeNG, etc.) with `page/first/rows`.
      */
-    updateByOffset: ({ page: pageNum, first, rows }?: OffsetPaginationType, { query }?: UpdateByOffsetOptions) => Promise<ItemsType[] | undefined>;
+    updateByOffset: ({ page: pageNum, first, rows }?: OffsetPaginationType, { query, sort }?: UpdateByOffsetOptions) => Promise<ItemsType[] | undefined>;
+    setSort: (sort?: QuerySortInput) => void;
+    updateSort: (sort?: QuerySortRule | null) => Promise<ItemsType[] | undefined>;
+    updateSorts: (sort?: ReadonlyArray<QuerySortRule> | null) => Promise<ItemsType[] | undefined>;
     /**
      * Set route parameters (path variables) for the resource URL.
      * Does not trigger loading automatically - call `refetchWith()` or `updatePage()` after.
@@ -779,8 +867,18 @@ declare class PagedQueryStore<ItemsType extends object, FilterType = unknown> {
     private parseResponseData;
     private updateCache;
     private parseFlatArray;
+    private resetDataset;
+    private bumpVersion;
+    private invalidateRequests;
+    private resolveConcurrency;
+    private shouldIgnoreRequestResult;
     private applyConfig;
+    private resolveCacheLimit;
     private applyPresetMeta;
+    private normalizeSort;
+    private resolveSortQueryKey;
+    private sortRulesToTokens;
+    private reinitTransport;
 }
 
 /**
@@ -827,6 +925,10 @@ type DictStoreConfig<ItemsType extends object> = {
     method?: 'GET' | 'POST';
     /** Debounce delay before request (ms) — for frequent input/search. */
     debounceTime?: number;
+    /** Cache freshness window (ms). Undefined means restored cache does not expire. */
+    ttlMs?: number;
+    /** When cache is stale, keep visible items and refresh them in the background. */
+    revalidate?: boolean;
     /** Maximum number of options exposed (truncates `options`). */
     maxOptionsSize?: number;
     /** Field key for label in a dictionary item. Defaults to `'name'`. */
@@ -875,6 +977,10 @@ type DictStoreProviderConfig = {
     defaultRestMethod?: DictStoreConfig<AnyType>['method'];
     /** Debounce delay before request (ms) — for frequent input/search. */
     defaultDebounceTime?: DictStoreConfig<AnyType>['debounceTime'];
+    /** Cache freshness window (ms). Undefined means restored cache does not expire. */
+    defaultTtlMs?: DictStoreConfig<AnyType>['ttlMs'];
+    /** When cache is stale, keep visible items and refresh them in the background. */
+    defaultRevalidate?: DictStoreConfig<AnyType>['revalidate'];
     /** Maximum number of options exposed (truncates `options`). */
     defaultMaxOptionsSize?: DictStoreConfig<AnyType>['maxOptionsSize'];
     /** Field key for label in a dictionary item. Defaults to `'name'`. */
@@ -905,6 +1011,7 @@ declare class DictStore<Type extends AnyDict> {
     private apiUrl;
     private storageKey;
     static readonly MAX_CACHE_SIZE = 400;
+    private static readonly META_SUFFIX;
     /**
      * Default dictionary configuration resolved from {@link STATUM_CONFIG}.
      *
@@ -916,12 +1023,16 @@ declare class DictStore<Type extends AnyDict> {
     private readonly valueKey;
     private readonly maxOptionsSize?;
     private readonly storage?;
+    private readonly metaStorage?;
+    private readonly ttlMs?;
+    private readonly revalidate;
+    private readonly cacheUpdatedAt;
     /**
      * Search text.
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
      */
     searchText: _angular_core.WritableSignal<string>;
-    private debouncedSearchText;
+    private readonly debouncedSearchText;
     /**
      * Additional filters for server request (or presets).
      */
@@ -947,9 +1058,10 @@ declare class DictStore<Type extends AnyDict> {
      * @param storageKey  key for saving cache in the selected strategy
      * @param cfg         behavior (fixed/search, parsers, label/value keys, cache strategy, etc.)
      */
-    constructor(apiUrl: string, storageKey: string, { autoLoad, method, presetFilters, parseResponse, parseRequest, debounceTime, fixed, maxOptionsSize, labelKey, valueKey, keyPrefix, cacheStrategy, }: DictStoreConfig<Type>);
+    constructor(apiUrl: string, storageKey: string, { autoLoad, method, presetFilters, parseResponse, parseRequest, debounceTime, ttlMs, revalidate, fixed, maxOptionsSize, labelKey, valueKey, keyPrefix, cacheStrategy, }: DictStoreConfig<Type>);
     /** Restore cache from the selected storage (`persist`/`session`/`lru`/`memory`). */
     restoreCache(): void;
+    clearCache(): void;
     /**
      * Set a search query and filters.
      * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
@@ -976,9 +1088,14 @@ declare class DictStore<Type extends AnyDict> {
     [Symbol.dispose](): void;
     private mergeIntoCache;
     private restoreFromStorage;
+    private persistCache;
     private filterLocal;
     private keyOf;
     private setAutoload;
+    private shouldFetchFixedCache;
+    private shouldRevalidateCache;
+    private isCacheStale;
+    private metaKey;
 }
 
 declare class DictLocalStore<Type extends AnyDict> {
@@ -1099,5 +1216,5 @@ declare const STATUM_CONFIG: InjectionToken<StatumConfig>;
 declare const provideStatum: (config: StatumConfig) => EnvironmentProviders;
 
 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 };
+export type { DataType, DictLocalConfig, DictStoreConfig, DictStoreProviderConfig, EntityId, EntityStoreConfig, FetchInput, FetchParams, FieldConfig, OffsetPaginationType, PagedQueryStoreConfig, PagedQueryStoreProviderConfig, QuerySortInput, QuerySortOrder, QuerySortRule, RefetchWithInput, ResourceProfileName, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, ResourceTraceEvent, RetryConfig, SerializedType, SerializerConfig, SetRouteParamsOptions, StatumConfig, StorageInterface, StorageStrategy, StorageStrategyOptions, Types, UpdateByOffsetOptions, UpdatePageInput, UpdatePageOptions };
 //# sourceMappingURL=reforgium-statum.d.ts.map