@reforgium/statum 2.0.0 → 2.1.0

package/fesm2022/reforgium-statum.mjs

@@ -9,6 +9,19 @@ const serializeNumber = (config, value) => config.mapNumber.format?.(value) ?? N
 const serializeBoolean = (config, value) => config.mapBoolean.format?.(value) ?? (value ? (config.mapBoolean.true ?? true) : (config.mapBoolean.false ?? false));
 const serializeDate = (config, value) => config.mapDate.format?.(value) ?? formatDate(value, config.mapDate.dateFormat);
 
+class SerializerFieldError extends Error {
+    field;
+    stage;
+    originalError;
+    constructor(field, stage, originalError) {
+        const originalMessage = originalError instanceof Error ? originalError.message : String(originalError);
+        super(`Serializer ${stage} error for field "${field}": ${originalMessage}`);
+        this.field = field;
+        this.stage = stage;
+        this.originalError = originalError;
+        this.name = 'SerializerFieldError';
+    }
+}
 /**
  * Universal serializer/deserializer for values used in forms, filters, and DTOs.
  *
@@ -47,8 +60,8 @@ class Serializer {
      *
      * @param config partial transformation configuration
      */
-    constructor(config) {
-        this.config = {
+    constructor(config = {}) {
+        this.config = this.mergeConfig({
             mapString: { trim: true },
             mapNumber: { fromString: false },
             mapBoolean: {},
@@ -60,8 +73,7 @@ class Serializer {
                 transformMode: { mode: 'split', dateFromKeyPostfix: 'From', dateToKeyPostfix: 'To' },
             },
             mapNullable: { remove: true, includeEmptyString: false },
-            ...config,
-        };
+        }, config);
     }
     /**
      * Converts a domain object into a flat serialized representation
@@ -83,7 +95,12 @@ class Serializer {
         for (const [key, value] of Object.entries(obj ?? {})) {
             const fields = this.config.mapFields?.[key];
             if (fields && 'format' in fields) {
-                result[key] = fields.format(value, obj);
+                try {
+                    result[key] = fields.format(value, obj);
+                }
+                catch (error) {
+                    throw new SerializerFieldError(key, 'format', error);
+                }
                 continue;
             }
             if (fields?.type === 'nullable' || isNullable(value, this.config.mapNullable?.includeEmptyString)) {
@@ -118,12 +135,17 @@ class Serializer {
      * @returns a domain object of the specified type
      */
     deserialize = (val) => {
-        const data = typeof val === 'string' ? this.parseQuery(val) : val;
+        const data = typeof val === 'string' ? this.parseInputString(val) : val;
         const result = {};
         for (const [key, value] of Object.entries(data ?? {})) {
             const field = this.config.mapFields?.[key];
             if (field && 'parse' in field) {
-                result[key] = field.parse(value, data);
+                try {
+                    result[key] = field.parse(value, data);
+                }
+                catch (error) {
+                    throw new SerializerFieldError(key, 'parse', error);
+                }
                 continue;
             }
             if (field?.type === 'nullable' ||
@@ -156,6 +178,14 @@ class Serializer {
         }
         return result;
     };
+    /** Parse only query-string input. */
+    deserializeQuery = (query) => {
+        return this.deserialize(this.parseQuery(query));
+    };
+    /** Parse only JSON object input. */
+    deserializeJson = (json) => {
+        return this.deserialize(this.parseJsonObject(json));
+    };
     /**
      * Build a query string from a domain object using `serialize` rules
      * and the array joining strategy (`concatType`).
@@ -174,7 +204,7 @@ class Serializer {
      * @returns new `Serializer` with the provided `config` applied
      */
     withConfig(config) {
-        return new Serializer({ ...this.config, ...config });
+        return new Serializer(this.mergeConfig(this.config, config));
     }
     serializeElement(value, key) {
         const fields = this.config.mapFields?.[key || ''];
@@ -182,7 +212,7 @@ class Serializer {
             return;
         }
         if (fields?.type === 'nullable' || isNullable(value, this.config.mapNullable?.includeEmptyString)) {
-            const nullableVal = value || null;
+            const nullableVal = value ?? null;
             return this.config.mapNullable.format?.(nullableVal) || this.config.mapNullable.replaceWith || nullableVal;
         }
         if (fields?.type === 'string') {
@@ -247,8 +277,7 @@ class Serializer {
         if (field?.type === 'object') {
             try {
                 if (this.config.mapObject.deep) {
-                    // @ts-ignore
-                    return this.deserializeElement(value);
+                    return isObject(value) ? this.deserialize(value) : value;
                 }
                 else {
                     // @ts-ignore
@@ -283,40 +312,112 @@ class Serializer {
             return this.config.mapNumber.parse?.(value) || Number(String(value).trim());
         }
         if (field?.type === 'string' || typeof value === 'string') {
-            return this.config.mapString.parse?.(value) || this.config.mapString.trim ? String(value).trim() : value;
+            const parsed = this.config.mapString.parse?.(value);
+            if (parsed !== undefined) {
+                return parsed;
+            }
+            return this.config.mapString.trim ? String(value).trim() : value;
         }
         return value;
     }
     parseQuery(val) {
+        const params = new URLSearchParams(val);
+        const data = {};
+        params.forEach((value, key) => {
+            const field = this.config.mapFields?.[key] || {};
+            const concatType = this.config.mapArray.concatType;
+            if ('type' in field && field.type === 'array') {
+                data[key] ??= [];
+                concatType !== 'multi' && (data[key] = parseQueryArray(value, concatType, key));
+                concatType === 'multi' && data[key].push(value);
+            }
+            else {
+                data[key] = value;
+            }
+        });
+        return data;
+    }
+    parseJsonObject(val) {
+        try {
+            const parsed = JSON.parse(val);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON input: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        throw new Error('Invalid JSON input: expected a JSON object');
+    }
+    parseInputString(val) {
         try {
-            return JSON.parse(val);
+            return this.parseJsonObject(val);
         }
         catch {
-            const params = new URLSearchParams(val);
-            const data = {};
-            params.forEach((value, key) => {
-                const field = this.config.mapFields?.[key] || {};
-                const concatType = this.config.mapArray.concatType;
-                if ('type' in field && field.type === 'array') {
-                    data[key] ??= [];
-                    concatType !== 'multi' && (data[key] = parseQueryArray(value, concatType, key));
-                    concatType === 'multi' && data[key].push(value);
-                }
-                else {
-                    data[key] = value;
-                }
-            });
-            return data;
+            return this.parseQuery(val);
         }
     }
+    mergeConfig(base, override) {
+        return {
+            ...base,
+            ...override,
+            mapString: { ...base.mapString, ...override.mapString },
+            mapNumber: { ...base.mapNumber, ...override.mapNumber },
+            mapBoolean: { ...base.mapBoolean, ...override.mapBoolean },
+            mapDate: { ...base.mapDate, ...override.mapDate },
+            mapPeriod: {
+                ...base.mapPeriod,
+                ...override.mapPeriod,
+                transformMode: {
+                    ...base.mapPeriod.transformMode,
+                    ...override.mapPeriod?.transformMode,
+                },
+            },
+            mapNullable: { ...base.mapNullable, ...override.mapNullable },
+            mapArray: { ...base.mapArray, ...override.mapArray },
+            mapObject: { ...base.mapObject, ...override.mapObject },
+            mapFields: { ...(base.mapFields || {}), ...(override.mapFields || {}) },
+        };
+    }
 }
 
+const createQuerySerializer = (config = {}) => {
+    return new Serializer({
+        mapArray: { concatType: 'comma' },
+        mapNullable: { remove: true, includeEmptyString: false },
+        mapObject: { deep: false },
+        ...config,
+    });
+};
+const createBodySerializer = (config = {}) => {
+    return new Serializer({
+        mapArray: { concatType: 'json' },
+        mapNullable: { remove: false },
+        mapObject: { deep: true },
+        ...config,
+    });
+};
+const createStrictSerializer = (config = {}) => {
+    return new Serializer({
+        mapString: { trim: true },
+        mapNumber: { fromString: true },
+        mapNullable: { remove: true, includeEmptyString: true },
+        ...config,
+    });
+};
+
 class LruCache {
-    limit;
     map = new Map();
     constructor(limit = 100) {
         this.limit = limit;
     }
+    _limit = 100;
+    get limit() {
+        return this._limit;
+    }
+    set limit(value) {
+        this._limit = Math.max(1, Math.floor(value || 0));
+    }
     get length() {
         return this.map.size;
     }
@@ -333,7 +434,7 @@ class LruCache {
         if (this.map.has(key)) {
             this.map.delete(key);
         }
-        else if (this.map.size === this.limit) {
+        else if (this.map.size >= this.limit) {
             const oldest = this.map.keys().next().value;
             oldest !== undefined && this.map.delete(oldest);
         }
@@ -354,6 +455,9 @@ class LruCache {
     values() {
         return Array.from(this.map.values());
     }
+    entries() {
+        return Array.from(this.map.entries());
+    }
     toArray() {
         return Array.from(this.map.values());
     }
@@ -371,12 +475,22 @@ class LocalStorage {
         this.prefix = prefix;
     }
     get length() {
-        return Object.keys(localStorage).filter((key) => key.startsWith(this.prefix || '')).length;
+        return Object.keys(localStorage).filter((key) => key.startsWith(this.safePrefix())).length;
     }
     get(key) {
-        const raw = localStorage.getItem(this.getSafePrefix(key));
-        const parsed = JSON.parse(raw ?? 'null');
-        return parsed ?? null;
+        const storageKey = this.getSafePrefix(key);
+        const raw = localStorage.getItem(storageKey);
+        if (raw == null) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return parsed ?? null;
+        }
+        catch {
+            localStorage.removeItem(storageKey);
+            return null;
+        }
     }
     set(key, value) {
         const str = JSON.stringify(value);
@@ -386,12 +500,15 @@ class LocalStorage {
         return localStorage.removeItem(this.getSafePrefix(key));
     }
     clear() {
-        const keys = Object.keys(localStorage).filter((key) => key.startsWith(this.prefix || ''));
+        const keys = Object.keys(localStorage).filter((key) => key.startsWith(this.safePrefix()));
         keys.forEach((key) => localStorage.removeItem(key));
     }
     getSafePrefix(key) {
         return this.prefix ? `${this.prefix}:${key}` : String(key);
     }
+    safePrefix() {
+        return this.prefix ? `${this.prefix}:` : '';
+    }
 }
 
 class MemoryStorage {
@@ -419,12 +536,22 @@ class SessionStorage {
         this.prefix = prefix;
     }
     get length() {
-        return Object.keys(sessionStorage).filter((key) => key.startsWith(this.prefix || '')).length;
+        return Object.keys(sessionStorage).filter((key) => key.startsWith(this.safePrefix())).length;
     }
     get(key) {
-        const raw = sessionStorage.getItem(this.getSafePrefix(key));
-        const parsed = JSON.parse(raw ?? 'null');
-        return parsed ?? null;
+        const storageKey = this.getSafePrefix(key);
+        const raw = sessionStorage.getItem(storageKey);
+        if (raw == null) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return parsed ?? null;
+        }
+        catch {
+            sessionStorage.removeItem(storageKey);
+            return null;
+        }
     }
     set(key, value) {
         const str = JSON.stringify(value);
@@ -434,12 +561,15 @@ class SessionStorage {
         return sessionStorage.removeItem(this.getSafePrefix(key));
     }
     clear() {
-        const keys = Object.keys(sessionStorage).filter((key) => key.startsWith(this.prefix || ''));
+        const keys = Object.keys(sessionStorage).filter((key) => key.startsWith(this.safePrefix()));
         keys.forEach((key) => sessionStorage.removeItem(key));
     }
     getSafePrefix(key) {
         return this.prefix ? `${this.prefix}:${key}` : String(key);
     }
+    safePrefix() {
+        return this.prefix ? `${this.prefix}:` : '';
+    }
 }
 
 /**
@@ -457,12 +587,12 @@ class SessionStorage {
  * @param strategy storage strategy type (`memory`, `session`, `persist`, `lru`)
  * @returns instance implementing `StorageInterface<Key, Type>`
  */
-const storageStrategy = (strategy) => {
+const storageStrategy = (strategy, options = {}) => {
     const fabrics = {
         memory: () => new MemoryStorage(),
         session: () => new SessionStorage(),
         persist: () => new LocalStorage(),
-        lru: () => new LruCache(),
+        lru: () => new LruCache(options.lruLimit ?? 100),
     };
     return fabrics[strategy]();
 };
@@ -519,13 +649,32 @@ function joinUrl(base, path) {
     return base ? `${base.replace(/\/$/, '')}/${path.replace(/^\//, '')}` : 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}`;
+    const params = stableStringify(args.params || {});
+    const query = stableStringify(args.query || {});
+    const payload = stableStringify(args.payload || {});
+    return `${method}|${path}|${params}|${query}|${payload}`;
+}
+function stableStringify(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${k}:${stableStringify(v)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return String(value);
 }
 
 /**
@@ -568,6 +717,10 @@ class KeyedScheduler {
         const promise = new Promise((resolve, reject) => {
             channel.waiters.push({ resolve, reject });
         });
+        // The scheduler can reject synchronously from `cancel()`.
+        // Mark the promise as handled to avoid host-level unhandled rejection noise
+        // when consumer handlers are attached on chained promises.
+        void promise.catch(() => undefined);
         channel.lastExec = exec;
         if (delay <= 0) {
             this.startExecution(channel);
@@ -589,13 +742,9 @@ class KeyedScheduler {
         if (!ch) {
             return;
         }
-        ch.timerSub?.unsubscribe();
-        ch.inflight?.unsubscribe();
-        ch.inflight = undefined;
-        ch.subject.complete();
         const waiters = ch.waiters.splice(0);
         waiters.forEach((w) => w.reject(reason));
-        this.channels.delete(key);
+        this.cleanupChannel(ch);
     }
     /**
      * Cancels all channels and their pending tasks.
@@ -613,7 +762,7 @@ class KeyedScheduler {
             return ch;
         }
         const subject = new Subject();
-        ch = { subject, waiters: [] };
+        ch = { key, subject, waiters: [] };
         this.channels.set(key, ch);
         const debounced$ = subject.pipe(filter((t) => t.mode === 'debounce'), debounce((t) => timer(t.delay)), tap(() => this.startExecution(ch)));
         const throttled$ = subject.pipe(filter((t) => t.mode === 'throttle'), throttle((t) => timer(t.delay), { leading: false, trailing: true }), tap(() => this.startExecution(ch)));
@@ -636,10 +785,31 @@ class KeyedScheduler {
             error: (err) => {
                 const waiters = ch.waiters.splice(0);
                 waiters.forEach((w) => w.reject(err));
+                ch.inflight = undefined;
+                this.cleanupIfIdle(ch);
+            },
+            complete: () => {
+                ch.inflight = undefined;
+                this.cleanupIfIdle(ch);
             },
-            complete: () => (ch.inflight = undefined),
         });
     }
+    cleanupIfIdle(ch) {
+        if (ch.waiters.length > 0 || ch.inflight) {
+            return;
+        }
+        this.cleanupChannel(ch);
+    }
+    cleanupChannel(ch) {
+        if (this.channels.get(ch.key) !== ch) {
+            return;
+        }
+        ch.timerSub?.unsubscribe();
+        ch.inflight?.unsubscribe();
+        ch.inflight = undefined;
+        ch.subject.complete();
+        this.channels.delete(ch.key);
+    }
 }
 
 /**
@@ -689,6 +859,7 @@ class ResourceStore {
     loading = computed(() => this.#activeRequests() > 0 || this.#status() === 'stale', ...(ngDevMode ? [{ debugName: "loading" }] : []));
     routes;
     opts;
+    maxEntries;
     entries = new Map();
     scheduler = new KeyedScheduler();
     /**
@@ -698,6 +869,7 @@ class ResourceStore {
     constructor(routes, opts = {}) {
         this.routes = routes;
         this.opts = opts;
+        this.maxEntries = Math.max(1, opts.maxEntries ?? 1000);
     }
     /**
      * Perform a GET request.
@@ -713,6 +885,7 @@ class ResourceStore {
         const url = this.buildUrl('GET', args);
         const key = buildKey('GET', url, args);
         const query = this.prepareQuery(args);
+        const responseType = cfg.responseType ?? 'json';
         const entry = this.ensureEntry(key);
         const strategy = cfg.strategy ?? 'network-first';
         const ttlMs = cfg.ttlMs ?? this.opts.ttlMs ?? 0;
@@ -722,12 +895,15 @@ class ResourceStore {
         }
         if (strategy === 'cache-only') {
             if (fresh && entry.data != null) {
+                this.trace({ type: 'cache-hit', method: 'GET', key, strategy });
                 this.promoteCurrent(entry, cfg.promote);
                 return entry.data;
             }
+            this.trace({ type: 'cache-miss', method: 'GET', key, strategy });
             throw new CacheMissError(key);
         }
         if (strategy === 'cache-first' && fresh && !cfg.revalidate && entry.data != null) {
+            this.trace({ type: 'cache-hit', method: 'GET', key, strategy });
             this.promoteCurrent(entry, cfg.promote);
             return entry.data;
         }
@@ -736,19 +912,56 @@ class ResourceStore {
         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 }),
-            entry,
-            promote: cfg.promote,
-            parseFn: cfg.parseResponse,
-        }));
-        cfg.dedupe && (entry.inflight = task);
-        void task.catch((e) => {
-            if (!isAbort(e)) {
-                throw e;
+        const retry = this.resolveRetryConfig(cfg.retry);
+        const taskWithRetry = this.runWithRetry((attempt) => {
+            this.trace({ type: 'request-start', method: 'GET', key, attempt });
+            return this.scheduler.schedule(key, mode, delay, this.exec$({
+                req$: this.http.get(url, { params: query, responseType: responseType }),
+                entry,
+                promote: cfg.promote,
+                parseFn: cfg.parseResponse,
+            }));
+        }, retry, {
+            method: 'GET',
+            key,
+        });
+        const resolvedTask = taskWithRetry
+            .catch((error) => {
+            if (isAbort(error)) {
+                throw error;
             }
+            if (strategy === 'network-first' && entry.data != null) {
+                entry.status = 'success';
+                entry.error = null;
+                this.promoteCurrent(entry, cfg.promote);
+                this.trace({ type: 'cache-fallback', method: 'GET', key, strategy });
+                return entry.data;
+            }
+            throw error;
+        })
+            .then((data) => {
+            this.trace({ type: 'cache-write', method: 'GET', key, strategy });
+            this.trace({ type: 'request-success', method: 'GET', key });
+            return data;
+        })
+            .catch((error) => {
+            if (!isAbort(error)) {
+                this.trace({ type: 'request-error', method: 'GET', key, error });
+            }
+            throw error;
         });
-        return task;
+        if (cfg.dedupe) {
+            entry.inflight = resolvedTask;
+            void resolvedTask.finally(() => {
+                entry.inflight === resolvedTask && (entry.inflight = undefined);
+            });
+        }
+        void resolvedTask.catch((error) => {
+            if (isAbort(error)) {
+                return;
+            }
+        });
+        return resolvedTask;
     }
     /**
      * POST request.
@@ -800,6 +1013,7 @@ class ResourceStore {
     abort(method, args, reason) {
         const url = this.buildUrl(method, args);
         const key = buildKey(method, url, args);
+        this.trace({ type: 'abort', method, key });
         this.scheduler.cancel?.(key, reason);
     }
     /**
@@ -808,43 +1022,96 @@ class ResourceStore {
      * @param reason Cancellation reason (optional)
      */
     abortAll(reason) {
+        this.trace({ type: 'abort', method: 'GET', key: '*' });
         this.scheduler.cancelAll?.(reason);
     }
     ensureEntry(key) {
         let entry = this.entries.get(key);
         if (!entry) {
+            this.evictEntriesIfNeeded();
             entry = { data: null, status: 'idle', error: null, updatedAt: null };
             this.entries.set(key, entry);
         }
+        else {
+            // Keep hot keys at the end to approximate LRU order.
+            this.entries.delete(key);
+            this.entries.set(key, entry);
+        }
         return entry;
     }
+    evictEntriesIfNeeded() {
+        while (this.entries.size >= this.maxEntries) {
+            let keyToDelete = null;
+            for (const [key, value] of this.entries.entries()) {
+                if (!value.inflight) {
+                    keyToDelete = key;
+                    break;
+                }
+            }
+            if (keyToDelete === null) {
+                keyToDelete = this.entries.keys().next().value ?? null;
+            }
+            if (keyToDelete === null) {
+                break;
+            }
+            this.entries.delete(keyToDelete);
+        }
+    }
     async callApi(method, args, config = {}) {
         const url = this.buildUrl(method, args);
         const key = buildKey(method, url, args);
         const query = this.prepareQuery(args);
         const payload = { ...(this.opts.presetPayload || {}), ...(args.payload || {}) };
         const serializedPayload = this.serializer.serialize(payload);
+        const responseType = config.responseType ?? 'json';
         const entry = this.ensureEntry(key);
         if (config.dedupe && entry.inflight) {
             return entry.inflight;
         }
         const delay = config.delay ?? this.opts.delay ?? 0;
         const mode = config.delayMode ?? this.opts.delayMode ?? 'debounce';
+        const retry = this.resolveRetryConfig(config.retry);
         entry.status = 'loading';
         this.promoteCurrent(entry, config.promote);
         let req$;
         if (method === 'DELETE') {
-            req$ = this.http.delete(url, { body: serializedPayload, params: query });
+            req$ = this.http.delete(url, {
+                body: serializedPayload,
+                params: query,
+                responseType: responseType,
+            });
         }
         else {
             // @ts-ignore
-            req$ = this.http[method.toLowerCase()](url, serializedPayload, { params: query });
+            req$ = this.http[method.toLowerCase()](url, serializedPayload, {
+                params: query,
+                responseType: responseType,
+            });
         }
-        const task = this.scheduler.schedule(key, mode, delay, this.exec$({ req$, entry, promote: config.promote, parseFn: config.parseResponse }));
-        config.dedupe && (entry.inflight = task);
-        void task.catch((e) => {
-            if (!isAbort(e)) {
-                throw e;
+        const task = this.runWithRetry((attempt) => {
+            this.trace({ type: 'request-start', method, key, attempt });
+            return this.scheduler.schedule(key, mode, delay, this.exec$({ req$, entry, promote: config.promote, parseFn: config.parseResponse }));
+        }, retry, { method, key })
+            .then((data) => {
+            this.trace({ type: 'cache-write', method, key });
+            this.trace({ type: 'request-success', method, key });
+            return data;
+        })
+            .catch((error) => {
+            if (!isAbort(error)) {
+                this.trace({ type: 'request-error', method, key, error });
+            }
+            throw error;
+        });
+        if (config.dedupe) {
+            entry.inflight = task;
+            void task.finally(() => {
+                entry.inflight === task && (entry.inflight = undefined);
+            });
+        }
+        void task.catch((error) => {
+            if (isAbort(error)) {
+                return;
             }
         });
         return task;
@@ -861,11 +1128,59 @@ class ResourceStore {
         const mergedQuery = { ...(this.opts.presetQueries || {}), ...(args.query || {}) };
         return this.serializer.serialize(mergedQuery);
     }
+    trace(event) {
+        try {
+            this.opts.onTrace?.(event);
+        }
+        catch {
+            /* noop */
+        }
+    }
+    resolveRetryConfig(override) {
+        const source = { ...(this.opts.retry || {}), ...(override || {}) };
+        return {
+            attempts: Math.max(0, source.attempts ?? 0),
+            delayMs: Math.max(0, source.delayMs ?? 0),
+            backoff: source.backoff ?? 'constant',
+            shouldRetry: source.shouldRetry ?? this.defaultShouldRetry,
+        };
+    }
+    defaultShouldRetry(error) {
+        if (isAbort(error)) {
+            return false;
+        }
+        const maybe = error;
+        const status = maybe?.status;
+        if (status == null) {
+            return true;
+        }
+        return status === 0 || status >= 500;
+    }
+    async runWithRetry(exec, retry, context) {
+        let attempt = 1;
+        while (true) {
+            try {
+                return await exec(attempt);
+            }
+            catch (error) {
+                const canRetry = attempt <= retry.attempts && retry.shouldRetry(error, attempt);
+                if (!canRetry) {
+                    throw error;
+                }
+                const delayMs = retry.backoff === 'exponential' ? retry.delayMs * 2 ** (attempt - 1) : retry.delayMs;
+                this.trace({ type: 'request-retry', method: context.method, key: context.key, attempt, error });
+                attempt++;
+                if (delayMs > 0) {
+                    await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+        }
+    }
     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.data = data;
                 entry.status = 'success';
                 entry.updatedAt = Date.now();
                 entry.error = null;
@@ -877,7 +1192,6 @@ class ResourceStore {
                 this.promoteCurrent(entry, promote);
             },
         }), finalize(() => {
-            entry.inflight = undefined;
             promote && this.#activeRequests.update((n) => Math.max(0, n - 1));
             this.promoteCurrent(entry, promote);
         }));
@@ -939,8 +1253,8 @@ class PaginatedDataStore {
     constructor(route, config = {}) {
         this.route = route;
         this.config = config;
-        this.#cache = new LruCache(config.cacheSize);
         this.applyConfig(config);
+        this.#cache = new LruCache(this.config.cacheSize);
         this.applyPresetMeta();
         this.initTransport();
         inject(DestroyRef).onDestroy(() => this.destroy());
@@ -1019,7 +1333,7 @@ class PaginatedDataStore {
      *
      * @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.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
@@ -1059,6 +1373,7 @@ class PaginatedDataStore {
      */
     updateConfig = (config) => {
         this.config = { ...this.config, ...config };
+        this.#cache.limit = this.config.cacheSize || this.defaultConfig.defaultCacheSize || 5;
         this.applyPresetMeta();
     };
     /**
@@ -1149,10 +1464,16 @@ class PaginatedDataStore {
         return data;
     };
     updateCache = (data) => {
-        if (this.config.hasCache) {
-            this.#cache.set(this.page, data);
+        if (!this.config.hasCache) {
+            this.cached.set([...data]);
+            return;
         }
-        this.cached.set(Array.from(this.#cache.values()).flat());
+        this.#cache.set(this.page, data);
+        const flat = [];
+        for (const pageItems of this.#cache.values()) {
+            flat.push(...pageItems);
+        }
+        this.cached.set(flat);
     };
     parseFlatArray(data) {
         return { content: data, totalElements: data.length };
@@ -1167,6 +1488,9 @@ class PaginatedDataStore {
             hasCache: config.hasCache === undefined ? this.defaultConfig.defaultHasCache : config.hasCache,
             cacheSize: config.cacheSize || this.defaultConfig.defaultCacheSize || 5,
         };
+        if (this.#cache) {
+            this.#cache.limit = this.config.cacheSize;
+        }
     }
     applyPresetMeta() {
         this.filters = this.config.presetFilters || {};
@@ -1216,7 +1540,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);
+    debouncedSearchText;
     /**
      * Additional filters for server request (or presets).
      */
@@ -1252,6 +1576,8 @@ class DictStore {
     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;
+        const searchDebounce = debounceTime ?? 300;
+        this.debouncedSearchText = debounceSignal(this.searchText, searchDebounce);
         this.#helper = new PaginatedDataStore(this.apiUrl, {
             method: method,
             hasCache: false,
@@ -1313,19 +1639,22 @@ class DictStore {
      * @returns label string or `undefined` if not found
      */
     findLabel = (value) => {
-        for (const item of this.cachedItems()) {
-            if (item[this.valueKey] === value) {
-                return String(item[this.labelKey] ?? undefined);
-            }
+        if (value == null) {
+            return undefined;
         }
-        return undefined;
+        const key = typeof value === 'string' ? value : String(value);
+        if (!key) {
+            return undefined;
+        }
+        const item = this.#lru.get(key);
+        return item ? String(item[this.labelKey] ?? undefined) : undefined;
     };
     /**
      * Preload dictionary items into a local cache.
      * Useful for SSR/static lists/quick presets.
      *
      * @param items list of items
-     * @param opts  `{ replace?: true }` — completely replace current cache
+     * @param opts  `{ replace?: true }` - completely replace current cache
      */
     preload = (items, opts) => {
         opts?.replace && this.#lru.clear();
@@ -1335,9 +1664,12 @@ class DictStore {
             if (!key) {
                 continue;
             }
-            const existed = this.#lru.has(key);
+            const prev = this.#lru.get(key);
+            const existed = prev !== null;
             this.#lru.set(key, it);
-            !existed && (changed = true);
+            if (!existed || prev !== it) {
+                changed = true;
+            }
         }
         if (changed || opts?.replace) {
             const arr = this.#lru.toArray();
@@ -1358,9 +1690,12 @@ class DictStore {
         let changed = 0;
         for (const it of items) {
             const key = this.keyOf(it);
-            const before = this.#lru.has(key);
+            const prev = this.#lru.get(key);
+            const before = prev !== null;
             this.#lru.set(key, it);
-            !before && changed++;
+            if (!before || prev !== it) {
+                changed++;
+            }
         }
         if (changed > 0) {
             const arr = this.#lru.toArray();
@@ -1399,7 +1734,9 @@ class DictStore {
         const out = [];
         for (let i = 0; i < list.length; i++) {
             const val = list[i][key];
-            val.toLowerCase().includes(query) && out.push(list[i]);
+            String(val ?? '')
+                .toLowerCase()
+                .includes(query) && out.push(list[i]);
         }
         return out;
     }
@@ -1459,7 +1796,7 @@ class DictLocalStore {
     constructor(items, config) {
         this.labelKey = config?.labelKey ?? (this.defaultConfig.defaultLabelKey || 'name');
         this.valueKey = config?.valueKey ?? (this.defaultConfig.defaultValueKey || 'code');
-        this.maxOptionsSize = config?.maxOptionsSize ?? 1000;
+        this.maxOptionsSize = config?.maxOptionsSize ?? this.defaultConfig.defaultMaxOptionsSize ?? 1000;
         this.items.set(items);
         this.#draftItems.set(items);
     }
@@ -1534,9 +1871,138 @@ class DictLocalStore {
     };
 }
 
+class EntityStore {
+    idKey;
+    sortIds;
+    byId = signal({}, ...(ngDevMode ? [{ debugName: "byId" }] : []));
+    ids = signal([], ...(ngDevMode ? [{ debugName: "ids" }] : []));
+    items = computed(() => {
+        const byId = this.byId();
+        return this.ids()
+            .map((id) => byId[String(id)])
+            .filter((item) => item !== undefined);
+    }, ...(ngDevMode ? [{ debugName: "items" }] : []));
+    constructor(config) {
+        this.idKey = config.idKey;
+        this.sortIds = config.sortIds;
+    }
+    clear() {
+        this.byId.set({});
+        this.ids.set([]);
+    }
+    setAll(items) {
+        const byId = {};
+        const ids = [];
+        for (const item of items) {
+            const id = item[this.idKey];
+            if (!this.isValidId(id)) {
+                continue;
+            }
+            byId[String(id)] = item;
+            ids.push(id);
+        }
+        this.byId.set(byId);
+        this.ids.set(this.sortIds ? [...ids].sort(this.sortIds) : ids);
+    }
+    upsertOne(item) {
+        const id = item[this.idKey];
+        if (!this.isValidId(id)) {
+            return;
+        }
+        const key = String(id);
+        this.byId.update((prev) => ({ ...prev, [key]: item }));
+        this.ids.update((prev) => {
+            const has = prev.some((currentId) => currentId === id);
+            const next = has ? [...prev] : [...prev, id];
+            return this.sortIds ? next.sort(this.sortIds) : next;
+        });
+    }
+    upsertMany(items) {
+        if (!items.length) {
+            return;
+        }
+        this.byId.update((prev) => {
+            const next = { ...prev };
+            for (const item of items) {
+                const id = item[this.idKey];
+                if (!this.isValidId(id)) {
+                    continue;
+                }
+                next[String(id)] = item;
+            }
+            return next;
+        });
+        this.ids.update((prev) => {
+            const next = [...prev];
+            const keySet = new Set(next.map((id) => String(id)));
+            for (const item of items) {
+                const id = item[this.idKey];
+                if (!this.isValidId(id) || keySet.has(String(id))) {
+                    continue;
+                }
+                keySet.add(String(id));
+                next.push(id);
+            }
+            return this.sortIds ? next.sort(this.sortIds) : next;
+        });
+    }
+    removeOne(id) {
+        if (!this.isValidId(id)) {
+            return;
+        }
+        const key = String(id);
+        this.byId.update((prev) => {
+            const next = { ...prev };
+            delete next[key];
+            return next;
+        });
+        this.ids.update((prev) => prev.filter((it) => it !== id));
+    }
+    removeMany(ids) {
+        if (!ids.length) {
+            return;
+        }
+        const idSet = new Set(ids.map((id) => String(id)));
+        this.byId.update((prev) => {
+            const next = { ...prev };
+            for (const id of idSet) {
+                delete next[id];
+            }
+            return next;
+        });
+        this.ids.update((prev) => prev.filter((id) => !idSet.has(String(id))));
+    }
+    patchOne(id, patch) {
+        if (!this.isValidId(id)) {
+            return;
+        }
+        const key = String(id);
+        const current = this.byId()[key];
+        if (!current) {
+            return;
+        }
+        this.byId.update((prev) => ({
+            ...prev,
+            [key]: { ...current, ...patch },
+        }));
+    }
+    getById(id) {
+        if (!this.isValidId(id)) {
+            return null;
+        }
+        return this.byId()[String(id)] ?? null;
+    }
+    has(id) {
+        return this.getById(id) !== null;
+    }
+    isValidId(value) {
+        return typeof value === 'string' || typeof value === 'number';
+    }
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { AbortError, CacheMissError, DictLocalStore, DictStore, LruCache, PaginatedDataStore, ResourceStore, STATUM_CONFIG, Serializer, isAbort, storageStrategy };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, LruCache, PaginatedDataStore, ResourceStore, STATUM_CONFIG, Serializer, SerializerFieldError, createBodySerializer, createQuerySerializer, createStrictSerializer, isAbort, storageStrategy };
 //# sourceMappingURL=reforgium-statum.mjs.map