@reforgium/statum 1.0.2 → 2.0.0

package/README.md

@@ -58,6 +58,7 @@ All cache strategies implement the same contract.
 
 ```ts
 interface StorageInterface<T> {
+  prefix?: string;
   get(key: string): T | null;
   set(key: string, value: T): void;
   remove(key: string): void;
@@ -148,16 +149,16 @@ Lightweight store for server-side pagination with sorting, filtering and page ca
 
 ### State
 
-| Field / Signal | Type | Description |
-|---|---|---|
-| items | `WritableSignal<T[]>` | Current page items |
-| cached | `WritableSignal<T[]>` | Flattened cache of cached pages |
-| loading | `WritableSignal<boolean>` | Loading indicator |
-| 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|desc"` |
+| Field / Signal | Type                      | Description                     |
+|----------------|---------------------------|---------------------------------|
+| items          | `WritableSignal<T[]>`     | Current page items              |
+| cached         | `WritableSignal<T[]>`     | Flattened cache of cached pages |
+| loading        | `WritableSignal<boolean>` | Loading indicator               |
+| 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             |
 
 ### Methods
 
@@ -170,6 +171,7 @@ Lightweight store for server-side pagination with sorting, filtering and page ca
 | 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    |
@@ -270,12 +272,12 @@ Utility for serialization/deserialization between layers (UI ↔ API, objects
 
 Core API:
 
-| Method | Description |
-|---|---|
-| serialize | Prepare data for transport |
-| deserialize | Parse incoming data / query string |
-| toQuery | Build query string |
-| withConfig | Clone serializer with partial config overrides |
+| Method      | Description                                    |
+|-------------|------------------------------------------------|
+| serialize   | Prepare data for transport                     |
+| deserialize | Parse incoming data / query string             |
+| toQuery     | Build query string                             |
+| withConfig  | Clone serializer with partial config overrides |
 
 Config:
 

package/fesm2022/reforgium-statum.mjs

@@ -1,6 +1,6 @@
-import { formatDate, isNullable, isDatePeriod, parseToDate, makeQuery, isNumber, isObject, parseToDatePeriod, parseQueryArray, fillUrlWithParams, concatArray } from '@reforgium/internal';
-import { InjectionToken, inject, signal, computed, DestroyRef, effect, untracked } from '@angular/core';
+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 { Subject, filter, timer, merge, map } from 'rxjs';
 import { debounce, tap, throttle, finalize } from 'rxjs/operators';
 
@@ -311,8 +311,6 @@ class Serializer {
     }
 }
 
-const SERIALIZER_CONFIG = new InjectionToken('SERIALIZER_CONFIG');
-
 class LruCache {
     limit;
     map = new Map();
@@ -368,23 +366,31 @@ class LruCache {
 }
 
 class LocalStorage {
+    prefix;
+    constructor(prefix = 're') {
+        this.prefix = prefix;
+    }
     get length() {
-        return localStorage.length;
+        return Object.keys(localStorage).filter((key) => key.startsWith(this.prefix || '')).length;
     }
     get(key) {
-        const raw = localStorage.getItem(String(key));
+        const raw = localStorage.getItem(this.getSafePrefix(key));
         const parsed = JSON.parse(raw ?? 'null');
         return parsed ?? null;
     }
     set(key, value) {
         const str = JSON.stringify(value);
-        localStorage.setItem(String(key), str);
+        localStorage.setItem(this.getSafePrefix(key), str);
     }
     remove(key) {
-        return localStorage.removeItem(String(key));
+        return localStorage.removeItem(this.getSafePrefix(key));
     }
     clear() {
-        return localStorage.clear();
+        const keys = Object.keys(localStorage).filter((key) => key.startsWith(this.prefix || ''));
+        keys.forEach((key) => localStorage.removeItem(key));
+    }
+    getSafePrefix(key) {
+        return this.prefix ? `${this.prefix}:${key}` : String(key);
     }
 }
 
@@ -408,23 +414,31 @@ class MemoryStorage {
 }
 
 class SessionStorage {
+    prefix;
+    constructor(prefix = 're') {
+        this.prefix = prefix;
+    }
     get length() {
-        return sessionStorage.length;
+        return Object.keys(sessionStorage).filter((key) => key.startsWith(this.prefix || '')).length;
     }
     get(key) {
-        const raw = sessionStorage.getItem(String(key));
+        const raw = sessionStorage.getItem(this.getSafePrefix(key));
         const parsed = JSON.parse(raw ?? 'null');
         return parsed ?? null;
     }
     set(key, value) {
         const str = JSON.stringify(value);
-        sessionStorage.setItem(String(key), str);
+        sessionStorage.setItem(this.getSafePrefix(key), str);
     }
     remove(key) {
-        return sessionStorage.removeItem(String(key));
+        return sessionStorage.removeItem(this.getSafePrefix(key));
     }
     clear() {
-        return sessionStorage.clear();
+        const keys = Object.keys(sessionStorage).filter((key) => key.startsWith(this.prefix || ''));
+        keys.forEach((key) => sessionStorage.removeItem(key));
+    }
+    getSafePrefix(key) {
+        return this.prefix ? `${this.prefix}:${key}` : String(key);
     }
 }
 
@@ -453,6 +467,9 @@ const storageStrategy = (strategy) => {
     return fabrics[strategy]();
 };
 
+// noinspection ES6PreferShortImport
+const STATUM_CONFIG = new InjectionToken('RE_STATUM_CONFIG');
+
 /**
  * Error thrown when requested data is missing in the cache.
  *
@@ -501,8 +518,14 @@ function isAbort(e) {
 function joinUrl(base, path) {
     return base ? `${base.replace(/\/$/, '')}/${path.replace(/^\//, '')}` : path;
 }
-function buildKey(method, path) {
-    return `${method}|${path}`;
+function buildKey(method, path, args) {
+    const params = Object.entries(args.params || {})
+        .map(([key, value]) => `${key}=${value}`)
+        .join('&');
+    const query = Object.entries(args.query || {})
+        .map(([key, value]) => `${key}=${value}`)
+        .join('&');
+    return `${method}|${path}|${params}|${query}`;
 }
 
 /**
@@ -641,10 +664,11 @@ class KeyedScheduler {
  */
 class ResourceStore {
     http = inject(HttpClient);
-    serializer = new Serializer(inject(SERIALIZER_CONFIG, { optional: true }) ?? {});
+    serializer = new Serializer(inject(STATUM_CONFIG, { optional: true })?.serializer ?? {});
     #value = signal(null, ...(ngDevMode ? [{ debugName: "#value" }] : []));
     #status = signal('idle', ...(ngDevMode ? [{ debugName: "#status" }] : []));
     #error = signal(null, ...(ngDevMode ? [{ debugName: "#error" }] : []));
+    #activeRequests = signal(0, ...(ngDevMode ? [{ debugName: "#activeRequests" }] : []));
     /**
      * Current resource value.
      * Returns `null` if no data yet or the request failed.
@@ -662,7 +686,7 @@ class ResourceStore {
      * Convenience loading flag: `true` when `loading` or `stale`.
      * Useful for spinners and disabling buttons.
      */
-    loading = computed(() => ['loading', 'stale'].includes(this.#status()), ...(ngDevMode ? [{ debugName: "loading" }] : []));
+    loading = computed(() => this.#activeRequests() > 0 || this.#status() === 'stale', ...(ngDevMode ? [{ debugName: "loading" }] : []));
     routes;
     opts;
     entries = new Map();
@@ -687,7 +711,7 @@ class ResourceStore {
      */
     async get(args, cfg = {}) {
         const url = this.buildUrl('GET', args);
-        const key = buildKey('GET', url);
+        const key = buildKey('GET', url, args);
         const query = this.prepareQuery(args);
         const entry = this.ensureEntry(key);
         const strategy = cfg.strategy ?? 'network-first';
@@ -709,7 +733,8 @@ class ResourceStore {
         }
         const delay = cfg.delay ?? this.opts.delay ?? 0;
         const mode = cfg.delayMode ?? this.opts.delayMode ?? 'debounce';
-        entry.status = strategy === 'cache-first' && fresh && entry.data != null ? 'stale' : 'loading';
+        const isSWR = strategy === 'cache-first' && entry.data != null;
+        entry.status = isSWR ? 'stale' : 'loading';
         this.promoteCurrent(entry, cfg.promote);
         const task = this.scheduler.schedule(key, mode, delay, this.exec$({
             req$: this.http.get(url, { params: query }),
@@ -774,7 +799,7 @@ class ResourceStore {
      */
     abort(method, args, reason) {
         const url = this.buildUrl(method, args);
-        const key = buildKey(method, url);
+        const key = buildKey(method, url, args);
         this.scheduler.cancel?.(key, reason);
     }
     /**
@@ -795,7 +820,7 @@ class ResourceStore {
     }
     async callApi(method, args, config = {}) {
         const url = this.buildUrl(method, args);
-        const key = buildKey(method, url);
+        const key = buildKey(method, url, args);
         const query = this.prepareQuery(args);
         const payload = { ...(this.opts.presetPayload || {}), ...(args.payload || {}) };
         const serializedPayload = this.serializer.serialize(payload);
@@ -836,23 +861,27 @@ class ResourceStore {
         const mergedQuery = { ...(this.opts.presetQueries || {}), ...(args.query || {}) };
         return this.serializer.serialize(mergedQuery);
     }
-    exec$ = ({ req$, entry, promote = true, parseFn }) => () => req$.pipe(map((data) => (parseFn ? parseFn(data) : data)), tap({
-        next: (data) => {
-            promote && (entry.data = data);
-            entry.status = 'success';
-            entry.updatedAt = Date.now();
-            entry.error = null;
-            this.promoteCurrent(entry, promote);
-        },
-        error: (err) => {
-            entry.error = err;
-            entry.status = 'error';
+    exec$ = ({ req$, entry, promote = true, parseFn }) => () => {
+        promote && this.#activeRequests.update((n) => n + 1);
+        return req$.pipe(map((data) => (parseFn ? parseFn(data) : data)), tap({
+            next: (data) => {
+                promote && (entry.data = data);
+                entry.status = 'success';
+                entry.updatedAt = Date.now();
+                entry.error = null;
+                this.promoteCurrent(entry, promote);
+            },
+            error: (err) => {
+                entry.error = err;
+                entry.status = 'error';
+                this.promoteCurrent(entry, promote);
+            },
+        }), finalize(() => {
+            entry.inflight = undefined;
+            promote && this.#activeRequests.update((n) => Math.max(0, n - 1));
             this.promoteCurrent(entry, promote);
-        },
-    }), finalize(() => {
-        entry.inflight = undefined;
-        this.promoteCurrent(entry, promote);
-    }));
+        }));
+    };
     promoteCurrent(entry, promote = true) {
         if (!promote) {
             return;
@@ -863,8 +892,6 @@ class ResourceStore {
     }
 }
 
-const PDS_CONFIG = new InjectionToken('RE_PDS_CONFIG');
-
 // noinspection ES6PreferShortImport
 /**
  * Store for paginated data (tables/lists) with per-page cache and unified requests.
@@ -885,7 +912,7 @@ const PDS_CONFIG = new InjectionToken('RE_PDS_CONFIG');
 class PaginatedDataStore {
     route;
     config;
-    defaultConfig = inject(PDS_CONFIG, { optional: true }) || {};
+    defaultConfig = inject(STATUM_CONFIG, { optional: true })?.paginatedData || {};
     #transport;
     #cache;
     /** Current page data (reactive). */
@@ -904,6 +931,7 @@ class PaginatedDataStore {
     pageSize = 20;
     /** Total number of elements reported by the server. */
     totalElements = 0;
+    routeParams = {};
     /**
      * @param route  Resource URL pattern (e.g., `'/users'`)
      * @param config Store behavior: method, cache, request/response parsers, debounce, presets, etc.
@@ -985,6 +1013,46 @@ class PaginatedDataStore {
         this.cached.set([]);
         this.initTransport();
     };
+    /**
+     * Set route parameters (path variables) for the resource URL.
+     * Does not trigger loading automatically — call `refresh()` or `updatePage()` after.
+     *
+     * @param params Dictionary of route parameters (e.g., `{ id: '123' }`)
+     * @param opts   Options object
+     * @param opts.reset  If `true` (default), 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
+     *
+     * // Or with options:
+     * store.setRouteParams({ userId: '42' }, { reset: false, abort: true });
+     * ```
+     */
+    setRouteParams = (params = {}, opts = {}) => {
+        const isChanged = !deepEqual(this.routeParams, params);
+        if (!isChanged) {
+            return;
+        }
+        this.routeParams = params;
+        if (opts.reset) {
+            this.page = 0;
+            this.totalElements = 0;
+            this.#cache.clear();
+            this.cached.set([]);
+            this.items.set([]);
+        }
+        if (opts?.abort) {
+            try {
+                this.#transport?.abortAll?.('Route params changed');
+            }
+            finally {
+                this.loading.set(false);
+            }
+        }
+    };
     /**
      * Update store config on the fly (without re-creation).
      * Does not trigger loading automatically.
@@ -1046,12 +1114,13 @@ class PaginatedDataStore {
         });
     }
     async runTransport(payload, query) {
+        const params = this.routeParams;
         if (this.config.method === 'GET') {
-            return this.#transport.get({ query }, { promote: false, dedupe: true });
+            return this.#transport.get({ query, params }, { promote: false, dedupe: true });
         }
         const method = this.config.method?.toLowerCase() || 'post';
         // @ts-ignore
-        return this.#transport[method]({ query, payload }, { promote: false, dedupe: true });
+        return this.#transport[method]({ query, payload, params }, { promote: false, dedupe: true });
     }
     parseQuery({ page = 0, size, sort, filters }) {
         const method = this.config.method || 'GET';
@@ -1128,6 +1197,12 @@ class DictStore {
     apiUrl;
     storageKey;
     static MAX_CACHE_SIZE = 400;
+    /**
+     * Default dictionary configuration resolved from {@link STATUM_CONFIG}.
+     *
+     * Used as a global fallback when local configuration does not explicitly
+     */
+    defaultConfig = inject(STATUM_CONFIG, { optional: true })?.dict || {};
     #helper;
     #lru = new LruCache(_a.MAX_CACHE_SIZE);
     #effectRefs = [];
@@ -1141,6 +1216,7 @@ class DictStore {
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
      */
     searchText = signal('', ...(ngDevMode ? [{ debugName: "searchText" }] : []));
+    debouncedSearchText = debounceSignal(this.searchText, 300);
     /**
      * Additional filters for server request (or presets).
      */
@@ -1153,7 +1229,7 @@ class DictStore {
     items = computed(() => {
         const cached = this.cachedItems();
         if (!this.fixed) {
-            return this.searchText() || !cached.length ? this.#helper.items() : cached;
+            return this.debouncedSearchText() || !cached.length ? this.#helper.items() : cached;
         }
         return cached.length ? this.filterLocal() : this.#helper.items();
     }, ...(ngDevMode ? [{ debugName: "items" }] : []));
@@ -1173,7 +1249,7 @@ class DictStore {
      * @param storageKey  key for saving cache in the selected strategy
      * @param cfg         behavior (fixed/search, parsers, label/value keys, cache strategy, etc.)
      */
-    constructor(apiUrl, storageKey, { method, autoLoad = true, presetFilters, parseResponse, parseRequest, debounceTime, fixed = true, maxOptionsSize, labelKey = 'name', valueKey = 'code', cacheStrategy = 'persist', }) {
+    constructor(apiUrl, storageKey, { autoLoad = true, method = this.defaultConfig.defaultRestMethod, presetFilters = this.defaultConfig.defaultPresetFilters, parseResponse, parseRequest, debounceTime = this.defaultConfig.defaultDebounceTime, fixed = true, maxOptionsSize = this.defaultConfig.defaultMaxOptionsSize, labelKey = this.defaultConfig.defaultLabelKey || 'name', valueKey = this.defaultConfig.defaultValueKey || 'code', keyPrefix = this.defaultConfig.defaultPrefix || 're', cacheStrategy = this.defaultConfig.defaultCacheStrategy || 'persist', }) {
         this.apiUrl = apiUrl;
         this.storageKey = storageKey;
         this.#helper = new PaginatedDataStore(this.apiUrl, {
@@ -1188,10 +1264,11 @@ class DictStore {
         this.labelKey = labelKey;
         this.valueKey = valueKey;
         this.maxOptionsSize = maxOptionsSize;
-        this._armed.set(autoLoad);
         if (cacheStrategy !== 'memory') {
             this.storage = storageStrategy(cacheStrategy);
+            this.storage.prefix = keyPrefix;
         }
+        this.setAutoload(autoLoad);
         this.restoreFromStorage();
         this.#effectRefs.push(effect(() => {
             const incoming = this.#helper.items();
@@ -1206,11 +1283,15 @@ class DictStore {
             }
             const rest = this.filters();
             if (!this.fixed) {
-                const query = this.searchText().trim();
-                this._lastPromise = untracked(() => this.#helper.updateFilters({ name: query, ...rest }));
+                const query = this.debouncedSearchText().trim();
+                untracked(() => {
+                    this._lastPromise = this.#helper.updateFilters({ name: query, ...rest });
+                });
             }
             else if (!this.cachedItems().length) {
-                this._lastPromise = untracked(() => this.#helper.updateFilters({ name: '', ...rest }));
+                untracked(() => {
+                    this._lastPromise = this.#helper.updateFilters({ name: '', ...rest });
+                });
             }
         }));
     }
@@ -1310,7 +1391,7 @@ class DictStore {
     }
     filterLocal() {
         const list = this.cachedItems();
-        const query = this.searchText().toLowerCase();
+        const query = (this.fixed ? this.searchText() : this.debouncedSearchText()).toLowerCase();
         if (!query) {
             return list;
         }
@@ -1329,15 +1410,41 @@ class DictStore {
         }
         return typeof raw === 'string' ? raw : String(raw);
     }
+    setAutoload(autoLoad) {
+        if (autoLoad === 'whenEmpty') {
+            const isEmpty = !this.storage?.get(this.storageKey)?.length;
+            this._armed.set(isEmpty);
+        }
+        else {
+            this._armed.set(autoLoad);
+        }
+    }
 }
 _a = DictStore;
 
 class DictLocalStore {
+    /**
+     * Default dictionary configuration resolved from {@link STATUM_CONFIG}.
+     *
+     * Used as a global fallback when local configuration does not explicitly
+     * define dictionary keys.
+     */
+    defaultConfig = inject(STATUM_CONFIG, { optional: true })?.dict || {};
+    /**
+     * Source dictionary items.
+     *
+     * Represents the full, unfiltered list of dictionary entries.
+     * Used as the base data set for search and option generation.
+     */
     items = signal([], ...(ngDevMode ? [{ debugName: "items" }] : []));
     #draftItems = signal([], ...(ngDevMode ? [{ debugName: "#draftItems" }] : []));
     /**
-     * Ready-to-use options for dropdowns: `{ label, value }`.
-     * Respects `maxOptionsSize` to truncate the list.
+     * Computed list of options in `{ label, value }` format.
+     *
+     * Based on the current draft items (after search/filtering).
+     * Respects `maxOptionsSize` to limit the number of generated options.
+     *
+     * Intended for direct use in dropdowns and select-like components.
      */
     options = computed(() => {
         const options = this.#draftItems().map((it) => ({
@@ -1350,19 +1457,30 @@ class DictLocalStore {
     valueKey;
     maxOptionsSize;
     constructor(items, config) {
-        this.labelKey = config?.labelKey ?? 'label';
-        this.valueKey = config?.valueKey ?? 'value';
+        this.labelKey = config?.labelKey ?? (this.defaultConfig.defaultLabelKey || 'name');
+        this.valueKey = config?.valueKey ?? (this.defaultConfig.defaultValueKey || 'code');
         this.maxOptionsSize = config?.maxOptionsSize ?? 1000;
         this.items.set(items);
         this.#draftItems.set(items);
     }
+    // noinspection JSUnusedGlobalSymbols
     /**
-     * No-op method for API compatibility with DictStore.
+     * Restore cached dictionary state.
+     *
+     * This implementation is a no-op and exists only for API compatibility
+     * with {@link DictStore}.
      */
     restoreCache() { }
     /**
-     * Find display label by value (usually for reverse binding).
-     * @returns label string or `undefined` if not found
+     * Resolve display label by value.
+     *
+     * Performs a linear search over dictionary items and returns
+     * the corresponding label for the given value.
+     *
+     * Commonly used for reverse binding (value → label).
+     *
+     * @param value Dictionary value to look up
+     * @returns Resolved label string, or `undefined` if not found
      */
     findLabel = (value) => {
         for (const item of this.items()) {
@@ -1372,6 +1490,16 @@ class DictLocalStore {
         }
         return undefined;
     };
+    /**
+     * Filter dictionary items by label.
+     *
+     * Applies a case-insensitive substring match against the label field
+     * and updates the internal draft items used for option generation.
+     *
+     * Passing an empty string resets the filter and restores all items.
+     *
+     * @param name Search query string
+     */
     search = (name = '') => {
         const items = this.items();
         if (name?.length) {
@@ -1381,6 +1509,18 @@ class DictLocalStore {
             this.#draftItems.set(items);
         }
     };
+    /**
+     * Preload additional dictionary items.
+     *
+     * Can either replace the current items completely or append
+     * new entries to the existing list.
+     *
+     * Updates both the source items and the current draft items.
+     *
+     * @param items Items to preload
+     * @param opts Preload options
+     * @param opts.replace When `true`, replaces existing items instead of appending
+     */
     preload = (items, opts) => {
         if (opts?.replace) {
             this.items.set(items);
@@ -1398,5 +1538,5 @@ class DictLocalStore {
  * Generated bundle index. Do not edit.
  */
 
-export { AbortError, CacheMissError, DictLocalStore, DictStore, LruCache, PDS_CONFIG, PaginatedDataStore, ResourceStore, SERIALIZER_CONFIG, Serializer, isAbort, storageStrategy };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, LruCache, PaginatedDataStore, ResourceStore, STATUM_CONFIG, Serializer, isAbort, storageStrategy };
 //# sourceMappingURL=reforgium-statum.mjs.map