@reforgium/statum 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## [3.1.2]: 2026-04-06
+
+### Fix:
+- `DictStore`: `presetFilters` were passed to the internal `PagedQueryStore` as its initial filter state, which was immediately overwritten on the first `fetch()` call; `presetFilters` are now stored directly on `DictStore` and explicitly merged into every `fetch` call as `{ name, ...presetFilters, ...runtimeFilters }`, so direction/status constraints are always included regardless of runtime filter state
+
+---
+
+## [3.1.1]: 2026-04-04
+
+### Refactor:
+- Moved `Serializer` core into `@reforgium/internal`; `statum` now keeps serializer presets and public wrappers while reusing the shared codec engine underneath.
+- Moved low-level storage implementations and `storageStrategy(...)` into `@reforgium/internal`; `statum` cache exports now act as compatibility wrappers over the shared foundation layer.
+
+### Fix:
+- Package build and workspace resolution were aligned with hidden `@reforgium/internal` usage.
+- `PagedQueryStore` transport generic ordering was corrected for package build stability.
+
+### Docs:
+- `README` now reflects `storageStrategy(...)` naming and clarifies that serializer/storage core are shared through `@reforgium/internal`.
+
+---
+
 ## [3.1.0]: 2026-04-01
 
 ### Feat:

package/README.md

@@ -5,7 +5,7 @@
 
 **Signals-first query and data stores for Angular (18+).**
 
-`@reforgium/statum` provides **API-oriented stores**, **cache strategies**, and a  
+`@reforgium/statum` provides **API-oriented stores**, **cache strategies**, and a
 **serialization layer** for Angular applications that talk to HTTP backends.
 
 Designed for **request orchestration, pagination, dictionaries, and entity state**.
@@ -94,6 +94,9 @@ The safest long-term entry points are:
 - **Stores** - reusable state containers over HttpClient
 - **Serializer** - configurable data transformation utility
 
+Low-level serializer and storage primitives are shared through hidden `@reforgium/internal`.
+`statum` remains the user-facing package; you do not need to install or reason about `@reforgium/internal` directly in normal usage.
+
 ## Behavioral Guarantees
 
 The core stores are designed around explicit, testable runtime guarantees.
@@ -151,9 +154,9 @@ Those numbers are machine-specific and should be treated as a local envelope, no
 
 ## Cache
 
-### cacheStrategy
+### storageStrategy
 
-`cacheStrategy<T>(kind)` is a factory that returns a cache storage implementing `StorageInterface<T>`
+`storageStrategy<T>(kind)` is a factory that returns a cache storage implementing `StorageInterface<T>`
 
 Available strategies:
 
@@ -180,11 +183,11 @@ interface StorageInterface<T> {
 Example:
 
 ```ts
-import { cacheStrategy } from '@reforgium/statum';
+import { storageStrategy } from '@reforgium/statum';
 
 type User = { id: number; name: string };
 
-const storage = cacheStrategy<User>('persist');
+const storage = storageStrategy<User>('persist');
 
 storage.set('user:1', { id: 1, name: 'John' });
 
@@ -651,6 +654,8 @@ Use this when list fetching and local item mutations need different lifecycles.
 
 Utility for serialization/deserialization between layers (UI -> API, objects -> query string).
 
+`statum` keeps the user-facing serializer API and presets, while the low-level codec engine is shared from hidden `@reforgium/internal`.
+
 Core API:
 
 | Method      | Description                                    |

package/fesm2022/reforgium-statum.mjs

@@ -1,389 +1,10 @@
-import { formatDate, isNullable, isDatePeriod, parseToDate, buildQueryParams, isNumber, isObject, parseToDatePeriod, parseQueryParamsByMode, fillUrlWithParams, mergeQueryParams, deepEqual, normalizeSortInput, sortInputToTokens, debounceSignal } from '@reforgium/internal';
+import { Serializer, fillUrlWithParams, mergeQueryParams, LruCache, deepEqual, isNullable, normalizeSortInput, sortInputToTokens, debounceSignal, storageStrategy } from '@reforgium/internal';
+export { LocalStorage, LruCache, MemoryStorage, Serializer, SerializerFieldError, SessionStorage, storageStrategy } from '@reforgium/internal';
 import { HttpClient, HttpParams } from '@angular/common/http';
 import { InjectionToken, makeEnvironmentProviders, inject, signal, computed, EnvironmentInjector, DestroyRef, runInInjectionContext, effect, untracked } from '@angular/core';
 import { Subject, filter, timer, merge, map } from 'rxjs';
 import { debounce, tap, throttle, finalize } from 'rxjs/operators';
 
-const serializeString = (config, value) => config.mapString.format?.(value) ?? (config.mapString.trim ? value.trim() : value);
-const serializeNumber = (config, value) => config.mapNumber.format?.(value) ?? Number(value);
-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.
- *
- * 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');
- * ```
- */
-class Serializer {
-    config;
-    /**
-     * 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 = {}) {
-        this.config = this.mergeConfig({
-            mapString: { trim: true },
-            mapNumber: { fromString: false },
-            mapBoolean: {},
-            mapArray: { concatType: 'comma' },
-            mapObject: { deep: true },
-            mapDate: { dateFormat: 'yyyy-MM-dd' },
-            mapPeriod: {
-                dateFormat: 'yyyy-MM-dd',
-                transformMode: { mode: 'split', dateFromKeyPostfix: 'From', dateToKeyPostfix: 'To' },
-            },
-            mapNullable: { remove: true, includeEmptyString: false },
-        }, config);
-    }
-    /**
-     * 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, _seen = new WeakSet()) {
-        const result = {};
-        if (obj != null && typeof obj === 'object') {
-            _seen.add(obj);
-        }
-        for (const [key, value] of Object.entries(obj ?? {})) {
-            const fields = this.config.mapFields?.[key];
-            if (fields && 'format' in fields) {
-                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)) {
-                if (this.config.mapNullable.remove) {
-                    continue;
-                }
-            }
-            if (fields?.type === 'period' || isDatePeriod(value)) {
-                const transform = this.config.mapPeriod.transformMode;
-                const [from, to] = value;
-                if (transform?.mode === 'split') {
-                    result[`${key}${transform.dateFromKeyPostfix}`] = formatDate(from, this.config.mapPeriod.dateFormat);
-                    result[`${key}${transform.dateToKeyPostfix}`] = formatDate(to, this.config.mapPeriod.dateFormat);
-                    continue;
-                }
-            }
-            result[key] = this.serializeElement(value, key, _seen);
-        }
-        if (obj != null && typeof obj === 'object') {
-            _seen.delete(obj);
-        }
-        return result;
-    }
-    /**
-     * 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) => {
-        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) {
-                try {
-                    result[key] = field.parse(value, data);
-                }
-                catch (error) {
-                    throw new SerializerFieldError(key, 'parse', error);
-                }
-                continue;
-            }
-            if (field?.type === 'nullable' ||
-                (field?.type !== 'array' && isNullable(value, this.config.mapNullable?.includeEmptyString))) {
-                if (this.config.mapNullable.remove) {
-                    continue;
-                }
-            }
-            const periodTransform = this.config.mapPeriod.transformMode;
-            if (periodTransform.mode === 'split') {
-                const isFrom = (key || '').endsWith(periodTransform.dateFromKeyPostfix);
-                const isTo = (key || '').endsWith(periodTransform.dateToKeyPostfix);
-                const keyJoint = (key || '')
-                    .replace(periodTransform.dateFromKeyPostfix, '')
-                    .replace(periodTransform.dateToKeyPostfix, '');
-                const field = this.config.mapFields?.[keyJoint];
-                const fieldType = field && 'type' in field ? field.type : undefined;
-                if (fieldType === 'period' && (isFrom || isTo)) {
-                    result[keyJoint] ??= [null, null];
-                    if (isFrom) {
-                        result[keyJoint][0] = parseToDate(value, this.config.mapPeriod.dateFormat);
-                    }
-                    else if (isTo) {
-                        result[keyJoint][1] = parseToDate(value, this.config.mapPeriod.dateFormat);
-                    }
-                    continue;
-                }
-            }
-            result[key] = this.deserializeElement(value, key);
-        }
-        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`).
-     *
-     * @param val domain object
-     * @returns query string (suitable for URL or history API)
-     */
-    toQuery = (val) => {
-        return buildQueryParams(this.serialize(val), this.config.mapArray.concatType, this.resolveArrayFieldModes());
-    };
-    /**
-     * 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) {
-        return new Serializer(this.mergeConfig(this.config, config));
-    }
-    serializeElement(value, key, _seen = new WeakSet()) {
-        const fields = this.config.mapFields?.[key || ''];
-        if (fields && 'format' in fields) {
-            return;
-        }
-        if (fields?.type === 'nullable' || isNullable(value, this.config.mapNullable?.includeEmptyString)) {
-            const nullableVal = value ?? null;
-            return this.config.mapNullable.format?.(nullableVal) || this.config.mapNullable.replaceWith || nullableVal;
-        }
-        if (fields?.type === 'string') {
-            return serializeString(this.config, value);
-        }
-        if (fields?.type === 'number' || isNumber(value, this.config.mapNumber.fromString)) {
-            return serializeNumber(this.config, value);
-        }
-        if (typeof value === 'string') {
-            return serializeString(this.config, value);
-        }
-        if (fields?.type === 'boolean' || typeof value === 'boolean') {
-            return serializeBoolean(this.config, value);
-        }
-        if (fields?.type === 'date' || value instanceof Date) {
-            return serializeDate(this.config, value);
-        }
-        if (fields?.type === 'period' || isDatePeriod(value)) {
-            const mapPeriod = this.config.mapPeriod;
-            if (mapPeriod.format) {
-                return mapPeriod.format(value);
-            }
-            else {
-                const [from, to] = value;
-                const transform = mapPeriod.transformMode;
-                if (transform.mode === 'join') {
-                    const period = [
-                        formatDate(from, this.config.mapPeriod.dateFormat),
-                        formatDate(to, this.config.mapPeriod.dateFormat),
-                    ];
-                    return period.join(transform.concat);
-                }
-            }
-        }
-        if (fields?.type === 'array' || Array.isArray(value)) {
-            return value.map((it) => this.serializeElement(it, undefined, _seen));
-        }
-        if (fields?.type === 'object' || isObject(value)) {
-            if (this.config.mapObject.deep && !this.config.mapObject.format && value != null && _seen.has(value)) {
-                return undefined;
-            }
-            return (this.config.mapObject.format?.(value) ??
-                (this.config.mapObject.deep ? this.serialize(value, _seen) : JSON.stringify(value)));
-        }
-    }
-    deserializeElement(value, key) {
-        const field = this.config.mapFields?.[key || ''];
-        if (field && 'format' in field) {
-            return;
-        }
-        if (field?.type === 'array' || Array.isArray(value)) {
-            const array = Array.isArray(value) ? value : [value];
-            if (this.config.mapArray.removeNullable) {
-                if (!isNullable(value, this.config.mapNullable?.includeEmptyString)) {
-                    return array.map((it) => this.deserializeElement(it));
-                }
-                else {
-                    return;
-                }
-            }
-            else {
-                return !value ? [] : array.map((it) => this.deserializeElement(it));
-            }
-        }
-        if (field?.type === 'object') {
-            try {
-                if (this.config.mapObject.deep) {
-                    return isObject(value) ? this.deserialize(value) : value;
-                }
-                else {
-                    return typeof value === 'string' ? JSON.parse(value) : value;
-                }
-            }
-            catch {
-                return value;
-            }
-        }
-        if (field?.type === 'nullable' || isNullable(value, this.config.mapNullable?.includeEmptyString)) {
-            return this.config.mapNullable.parse?.(value) || value;
-        }
-        if (field?.type === 'boolean' ||
-            typeof value === 'boolean' ||
-            value === this.config.mapBoolean.true ||
-            value === this.config.mapBoolean.false) {
-            return this.config.mapBoolean.parse?.(value) ?? (value === this.config.mapBoolean.true || value === true);
-        }
-        const maybeDate = parseToDate(value, this.config.mapDate.dateFormat);
-        if (field?.type === 'date' || maybeDate) {
-            return this.config.mapDate.parse?.(value) || maybeDate;
-        }
-        const periodTransform = this.config.mapPeriod.transformMode;
-        if (periodTransform.mode === 'join') {
-            const maybePeriod = parseToDatePeriod(value, this.config.mapPeriod.dateFormat);
-            if (field?.type === 'period' || (maybePeriod || []).some(Boolean)) {
-                return this.config.mapPeriod.parse?.(value) || maybePeriod;
-            }
-        }
-        if (field?.type === 'number' || isNumber(value, this.config.mapNumber.fromString)) {
-            return this.config.mapNumber.parse?.(value) || Number(String(value).trim());
-        }
-        if (field?.type === 'string' || typeof value === 'string') {
-            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) {
-        return parseQueryParamsByMode(val, undefined, this.resolveArrayFieldModes());
-    }
-    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 this.parseJsonObject(val);
-        }
-        catch {
-            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 || {}) },
-        };
-    }
-    resolveArrayFieldModes() {
-        const result = {};
-        Object.entries(this.config.mapFields || {}).forEach(([key, field]) => {
-            if ('type' in field && field.type === 'array') {
-                result[key] = field.concatType ?? this.config.mapArray.concatType;
-            }
-        });
-        return result;
-    }
-}
-
 const createQuerySerializer = (config = {}) => {
     return new Serializer({
         mapArray: { concatType: 'comma' },
@@ -409,197 +30,6 @@ const createStrictSerializer = (config = {}) => {
     });
 };
 
-class LruCache {
-    map = new Map();
-    _limit = 100;
-    constructor(limit = 100) {
-        this.limit = limit;
-    }
-    get limit() {
-        return this._limit;
-    }
-    get length() {
-        return this.map.size;
-    }
-    set limit(value) {
-        this._limit = Math.max(1, Math.floor(value || 0));
-    }
-    get(key) {
-        if (!this.map.has(key)) {
-            return null;
-        }
-        const val = this.map.get(key);
-        this.map.delete(key);
-        this.map.set(key, val);
-        return val;
-    }
-    set(key, value) {
-        if (this.map.has(key)) {
-            this.map.delete(key);
-        }
-        else if (this.map.size >= this.limit) {
-            const oldest = this.map.keys().next().value;
-            oldest !== undefined && this.map.delete(oldest);
-        }
-        this.map.set(key, value);
-    }
-    remove(key) {
-        return this.map.delete(key);
-    }
-    clear() {
-        this.map.clear();
-    }
-    has(key) {
-        return this.map.has(key);
-    }
-    keys() {
-        return Array.from(this.map.keys());
-    }
-    values() {
-        return Array.from(this.map.values());
-    }
-    entries() {
-        return Array.from(this.map.entries());
-    }
-    toArray() {
-        return Array.from(this.map.values());
-    }
-    fromArray(entries) {
-        this.map.clear();
-        for (const [k, v] of entries) {
-            this.set(k, v);
-        }
-    }
-}
-
-class LocalStorage {
-    prefix;
-    constructor(prefix = 're') {
-        this.prefix = prefix;
-    }
-    get length() {
-        return Object.keys(localStorage).filter((key) => key.startsWith(this.safePrefix())).length;
-    }
-    get(key) {
-        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);
-        localStorage.setItem(this.getSafePrefix(key), str);
-    }
-    remove(key) {
-        return localStorage.removeItem(this.getSafePrefix(key));
-    }
-    clear() {
-        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 {
-    cache = new Map();
-    get length() {
-        return this.cache.size;
-    }
-    get(key) {
-        return this.cache.get(key) ?? null;
-    }
-    set(key, value) {
-        this.cache.set(key, value);
-    }
-    remove(key) {
-        this.cache.delete(key);
-    }
-    clear() {
-        this.cache.clear();
-    }
-}
-
-class SessionStorage {
-    prefix;
-    constructor(prefix = 're') {
-        this.prefix = prefix;
-    }
-    get length() {
-        return Object.keys(sessionStorage).filter((key) => key.startsWith(this.safePrefix())).length;
-    }
-    get(key) {
-        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);
-        sessionStorage.setItem(this.getSafePrefix(key), str);
-    }
-    remove(key) {
-        return sessionStorage.removeItem(this.getSafePrefix(key));
-    }
-    clear() {
-        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}:` : '';
-    }
-}
-
-/**
- * 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>`
- */
-const storageStrategy = (strategy, options = {}) => {
-    const fabrics = {
-        memory: () => new MemoryStorage(),
-        session: () => new SessionStorage(),
-        persist: () => new LocalStorage(),
-        lru: () => new LruCache(options.lruLimit ?? 100),
-    };
-    return fabrics[strategy]();
-};
-
 // noinspection ES6PreferShortImport
 const STATUM_CONFIG = new InjectionToken('RE_STATUM_CONFIG');
 const provideStatum = (config) => makeEnvironmentProviders([{ provide: STATUM_CONFIG, useValue: config }]);
@@ -1389,7 +819,7 @@ const createResourceProfile = (profile, overrides = {}) => ({
  * - reactive signals: `items`, `loading`, `cached`;
  * - methods to control page/size/query;
  * - optional LRU cache by pages;
- * - configurable transport (GET/POST/PATCH/…).
+ * - configurable transport (GET/POST/PATCH/…).
  *
  * Example:
  * ```ts
@@ -1856,6 +1286,7 @@ class DictStore {
     ttlMs;
     revalidate;
     cacheUpdatedAt = signal(null, ...(ngDevMode ? [{ debugName: "cacheUpdatedAt" }] : []));
+    presetFilters = {};
     /**
      * Search text.
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
@@ -1869,7 +1300,7 @@ class DictStore {
     cachedItems = signal([], ...(ngDevMode ? [{ debugName: "cachedItems" }] : []));
     /**
      * Current list of dictionary items.
-     * Source — local cache (fixed=true) or data from `PagedQueryStore`.
+     * Source — local cache (fixed=true) or data from `PagedQueryStore`.
      */
     items = computed(() => {
         const cached = this.cachedItems();
@@ -1899,10 +1330,10 @@ class DictStore {
         this.storageKey = storageKey;
         const searchDebounce = debounceTime ?? 300;
         this.debouncedSearchText = debounceSignal(this.searchText, searchDebounce);
+        this.presetFilters = presetFilters ?? {};
         this.#helper = new PagedQueryStore(this.apiUrl, {
             method: method,
             hasCache: false,
-            presetFilters: { name: '', ...presetFilters },
             parseResponse: parseResponse,
             parseRequest: parseRequest,
             debounceTime: debounceTime,
@@ -1936,12 +1367,14 @@ class DictStore {
             if (!this.fixed) {
                 const query = this.debouncedSearchText().trim();
                 untracked(() => {
-                    this._lastPromise = this.#helper.fetch({ filters: { name: query, ...rest } });
+                    this._lastPromise = this.#helper.fetch({ filters: { name: query, ...this.presetFilters, ...rest } });
                 });
             }
             else if (this.shouldFetchFixedCache()) {
                 untracked(() => {
-                    this._lastPromise = this.#helper.fetch({ filters: { name: '', ...rest } }).then((items) => {
+                    this._lastPromise = this.#helper
+                        .fetch({ filters: { name: '', ...this.presetFilters, ...rest } })
+                        .then((items) => {
                         items?.length && this.mergeIntoCache(items);
                         return items;
                     });
@@ -1962,7 +1395,7 @@ class DictStore {
     }
     /**
      * Set a search query and filters.
-     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
+     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
      */
     search = (name = '', filters = {}) => {
         this._armed.set(true);
@@ -2372,5 +1805,5 @@ class EntityStore {
  * Generated bundle index. Do not edit.
  */
 
-export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, LruCache, PagedQueryStore, RESOURCE_PROFILES, ResourceStore, STATUM_CONFIG, Serializer, SerializerFieldError, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum, storageStrategy };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, PagedQueryStore, RESOURCE_PROFILES, ResourceStore, STATUM_CONFIG, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum };
 //# sourceMappingURL=reforgium-statum.mjs.map

package/package.json

@@ -1,7 +1,7 @@
 {
-  "version": "3.1.0",
+  "version": "3.1.2",
   "name": "@reforgium/statum",
-  "description": "Signals-first query and data stores for Angular",
+  "description": "Signals-first API state and query stores for Angular",
   "author": "rtommievich",
   "license": "MIT",
   "type": "module",
@@ -21,10 +21,21 @@
   },
   "keywords": [
     "reforgium",
-    "state",
+    "angular",
+    "angular-library",
+    "signals",
+    "signal-store",
     "store",
-    "signal",
-    "angular"
+    "data-store",
+    "resource-store",
+    "entity-store",
+    "dictionary",
+    "query",
+    "pagination",
+    "cache",
+    "http",
+    "api",
+    "serializer"
   ],
   "types": "../../dist/@reforgium/statum/index.d.ts",
   "files": [
@@ -42,7 +53,7 @@
   "peerDependencies": {
     "@angular/common": ">=18.0.0",
     "@angular/core": ">=18.0.0",
-    "@reforgium/internal": ">=1.3.0",
+    "@reforgium/internal": ">=2.0.0",
     "rxjs": ">=7.0.0"
   },
   "module": "fesm2022/reforgium-statum.mjs",

package/types/reforgium-statum.d.ts

@@ -1,286 +1,14 @@
-import { AnyType, AnyDict, RestMethods, QueryParams, PageableRequest, PageableResponse } from '@reforgium/internal';
+import { DataType, SerializerConfig, Serializer, RestMethods, AnyDict, AnyType, QueryParams, PageableRequest, PageableResponse, StorageStrategy } from '@reforgium/internal';
+export { DataType, FieldConcatType, FieldConfig, FormatConfig, LocalStorage, LruCache, MemoryStorage, ParseFormatConfig, SerializedType, Serializer, SerializerConfig, SerializerFieldError, SessionStorage, StorageInterface, StorageStrategy, StorageStrategyOptions, Types, storageStrategy } from '@reforgium/internal';
 import * as _angular_core from '@angular/core';
 import { Signal, WritableSignal, EnvironmentProviders, InjectionToken } from '@angular/core';
 import { HttpResponse } from '@angular/common/http';
 import * as _reforgium_statum from '@reforgium/statum';
 
-/**
- * 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';
-type FieldConcatType = 'comma' | 'multi' | 'json';
-/**
- * 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;
-    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;
-};
-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: FieldConcatType;
-        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;
-
-declare class SerializerFieldError extends Error {
-    readonly field: string;
-    readonly stage: 'parse' | 'format';
-    readonly originalError: unknown;
-    constructor(field: string, stage: 'parse' | 'format', originalError: unknown);
-}
-/**
- * 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, _seen?: WeakSet<object>): 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;
-    /** Parse only query-string input. */
-    deserializeQuery: (query: string) => EntityType;
-    /** Parse only JSON object input. */
-    deserializeJson: (json: string) => 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;
-    private parseJsonObject;
-    private parseInputString;
-    private mergeConfig;
-    private resolveArrayFieldModes;
-}
-
 declare const createQuerySerializer: <EntityType extends DataType = DataType>(config?: Partial<SerializerConfig>) => Serializer<EntityType>;
 declare const createBodySerializer: <EntityType extends DataType = DataType>(config?: Partial<SerializerConfig>) => Serializer<EntityType>;
 declare const createStrictSerializer: <EntityType extends DataType = DataType>(config?: Partial<SerializerConfig>) => Serializer<EntityType>;
 
-type StorageStrategy = 'memory' | 'lru' | 'session' | 'persist';
-type StorageStrategyOptions = {
-    lruLimit?: number;
-};
-
-type StorageInterface<Key, Type> = {
-    prefix?: string;
-    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> {
-    private map;
-    private _limit;
-    constructor(limit?: number);
-    get limit(): number;
-    get length(): number;
-    set limit(value: 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[];
-    entries(): [KeyT, 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, options?: StorageStrategyOptions) => StorageInterface<Key, Type>;
-
 /**
  * Object for request body (payload).
  * Commonly used with POST/PUT/PATCH/DELETE.
@@ -749,7 +477,7 @@ type PagedQueryStoreProviderConfig = {
  * - reactive signals: `items`, `loading`, `cached`;
  * - methods to control page/size/query;
  * - optional LRU cache by pages;
- * - configurable transport (GET/POST/PATCH/…).
+ * - configurable transport (GET/POST/PATCH/…).
  *
  * Example:
  * ```ts
@@ -1033,6 +761,7 @@ declare class DictStore<Type extends AnyDict> {
     private readonly ttlMs?;
     private readonly revalidate;
     private readonly cacheUpdatedAt;
+    private readonly presetFilters;
     /**
      * Search text.
      * With `fixed: true` filters the local cache; with `fixed: false` triggers server search.
@@ -1046,7 +775,7 @@ declare class DictStore<Type extends AnyDict> {
     private cachedItems;
     /**
      * Current list of dictionary items.
-     * Source — local cache (fixed=true) or data from `PagedQueryStore`.
+     * Source — local cache (fixed=true) or data from `PagedQueryStore`.
      */
     items: Signal<readonly Type[]>;
     /**
@@ -1070,7 +799,7 @@ declare class DictStore<Type extends AnyDict> {
     clearCache(): void;
     /**
      * Set a search query and filters.
-     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
+     * With `fixed: false` initiates server search; with `fixed: true` — local filtering.
      */
     search: (name?: string, filters?: AnyDict) => void;
     /**
@@ -1221,6 +950,6 @@ type StatumConfig = PagedQueryProviderConfig & SerializerProviderConfig & DictPr
 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, QuerySortInput, QuerySortOrder, QuerySortRule, RefetchWithInput, ResourceProfileName, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, ResourceTraceEvent, RetryConfig, SerializedType, SerializerConfig, SetRouteParamsOptions, StatumConfig, StorageInterface, StorageStrategy, StorageStrategyOptions, Types, UpdateByOffsetOptions, UpdatePageInput, UpdatePageOptions };
+export { AbortError, CacheMissError, DictLocalStore, DictStore, EntityStore, PagedQueryStore, RESOURCE_PROFILES, ResourceStore, STATUM_CONFIG, createBodySerializer, createQuerySerializer, createResourceProfile, createStrictSerializer, isAbort, provideStatum };
+export type { DictLocalConfig, DictStoreConfig, DictStoreProviderConfig, EntityId, EntityStoreConfig, FetchInput, FetchParams, OffsetPaginationType, PagedQueryStoreConfig, PagedQueryStoreProviderConfig, QuerySortInput, QuerySortOrder, QuerySortRule, RefetchWithInput, ResourceProfileName, ResourceRoutesMap, ResourceStatus, ResourceStoreOptions, ResourceTraceEvent, RetryConfig, SetRouteParamsOptions, StatumConfig, UpdateByOffsetOptions, UpdatePageInput, UpdatePageOptions };
 //# sourceMappingURL=reforgium-statum.d.ts.map