@reforgium/statum 1.1.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +57 -55
  2. package/fesm2022/reforgium-statum.mjs +173 -50
  3. package/fesm2022/reforgium-statum.mjs.map +1 -1
  4. package/package.json +1 -1
  5. package/types/reforgium-statum.d.ts +137 -26
  6. package/types/reforgium-statum.d.ts.map +1 -1
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  [![npm version](https://badge.fury.io/js/%40reforgium%2Fstatum.svg)](https://www.npmjs.com/package/@reforgium/statum)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
5
 
6
- **Signals-first state stores and caching utilities for Angular (20+).**
6
+ **Signals-first state stores and caching utilities for Angular (18+).**
7
7
 
8
8
  `@reforgium/statum` provides a set of **API-oriented stores**, **cache strategies**, and a
9
9
  **serialization layer** for building predictable data flows in Angular applications.
@@ -33,9 +33,9 @@ npm install @reforgium/statum
33
33
 
34
34
  ## Package Structure
35
35
 
36
- - **Cache** — storage strategies for caching
37
- - **Stores** — reusable state containers over HttpClient
38
- - **Serializer** — configurable data transformation utility
36
+ - **Cache** - storage strategies for caching
37
+ - **Stores** - reusable state containers over HttpClient
38
+ - **Serializer** - configurable data transformation utility
39
39
 
40
40
  ---
41
41
 
@@ -47,10 +47,10 @@ npm install @reforgium/statum
47
47
 
48
48
  Available strategies:
49
49
 
50
- - `persist` — browser localStorage
51
- - `session` — browser sessionStorage
52
- - `memory` — in-memory storage
53
- - `lru` — size-limited in-memory cache
50
+ - `persist` - browser localStorage
51
+ - `session` - browser sessionStorage
52
+ - `memory` - in-memory storage
53
+ - `lru` - size-limited in-memory cache
54
54
 
55
55
  ### StorageInterface
56
56
 
@@ -58,6 +58,7 @@ All cache strategies implement the same contract.
58
58
 
59
59
  ```ts
60
60
  interface StorageInterface<T> {
61
+ prefix?: string;
61
62
  get(key: string): T | null;
62
63
  set(key: string, value: T): void;
63
64
  remove(key: string): void;
@@ -88,7 +89,7 @@ Transport-level store over HttpClient with cache strategies, deduplication, abor
88
89
 
89
90
  ### When to use
90
91
 
91
- - CRUD and “resource” endpoints
92
+ - CRUD and "resource" endpoints
92
93
  - Centralized debounce/throttle
93
94
  - Abort in-flight / delayed requests (latest-wins)
94
95
  - Dedupe identical calls to one HTTP request
@@ -96,24 +97,24 @@ Transport-level store over HttpClient with cache strategies, deduplication, abor
96
97
 
97
98
  ### Signals
98
99
 
99
- | Signal | Type | Description |
100
- |---------|-------------------|---------------------|
101
- | value | `Signal<T | null>` | Last successful value |
102
- | status | `'idle' | 'loading' | 'success' | 'error' | 'stale'` | Resource status |
103
- | error | `Signal<unknown | null>` | Last error |
104
- | loading | `Signal<boolean>` | Request in progress |
100
+ | Signal | Type | Description |
101
+ |---------|---------------------------|-------------------------|
102
+ | value | `Signal<T \| null>` | Last successful value |
103
+ | status | `Signal<ResourceStatus>` | Resource status |
104
+ | error | `Signal<unknown \| null>` | Last error |
105
+ | loading | `Signal<boolean>` | Request in progress |
105
106
 
106
107
  ### Methods
107
108
 
108
- | Method | Description |
109
- |------|-------------|
110
- | get | GET request |
111
- | post | POST request |
112
- | put | PUT request |
113
- | patch | PATCH request |
114
- | delete | DELETE request |
115
- | abort | Abort a specific request |
116
- | abortAll | Abort all requests |
109
+ | Method | Description |
110
+ |----------|--------------------------|
111
+ | get | GET request |
112
+ | post | POST request |
113
+ | put | PUT request |
114
+ | patch | PATCH request |
115
+ | delete | DELETE request |
116
+ | abort | Abort a specific request |
117
+ | abortAll | Abort all requests |
117
118
 
118
119
  Example:
119
120
 
@@ -137,7 +138,7 @@ const user = await userStore.get(
137
138
 
138
139
  ## PaginatedDataStore
139
140
 
140
- Lightweight store for server-side pagination with sorting, filtering and page cache.
141
+ Lightweight store for server-side pagination with sorting, filtering, and page cache.
141
142
 
142
143
  ### When to use
143
144
 
@@ -148,16 +149,16 @@ Lightweight store for server-side pagination with sorting, filtering and page ca
148
149
 
149
150
  ### State
150
151
 
151
- | Field / Signal | Type | Description |
152
- |---|---|---|
153
- | items | `WritableSignal<T[]>` | Current page items |
154
- | cached | `WritableSignal<T[]>` | Flattened cache of cached pages |
155
- | loading | `WritableSignal<boolean>` | Loading indicator |
156
- | page | `number` | Current page (0-based) |
157
- | pageSize | `number` | Page size |
158
- | totalElements | `number` | Total items on server |
159
- | filters | `Partial<F>` | Active filters |
160
- | sort | `string \| undefined` | Sort as `"field,asc|desc"` |
152
+ | Field / Signal | Type | Description |
153
+ |----------------|---------------------------|----------------------------------------|
154
+ | items | `WritableSignal<T[]>` | Current page items |
155
+ | cached | `WritableSignal<T[]>` | Flattened cache of cached pages |
156
+ | loading | `WritableSignal<boolean>` | Loading indicator |
157
+ | page | `number` | Current page (0-based) |
158
+ | pageSize | `number` | Page size |
159
+ | totalElements | `number` | Total items on server |
160
+ | filters | `Partial<F>` | Active filters |
161
+ | sort | `string \| undefined` | Sort as `"field,asc"` / `"field,desc"` |
161
162
 
162
163
  ### Methods
163
164
 
@@ -170,6 +171,7 @@ Lightweight store for server-side pagination with sorting, filtering and page ca
170
171
  | setFilters | Replace filters, reset cache + sort, go to page 0 |
171
172
  | updateQuery | Map table events to `page`/`sort` |
172
173
  | updateRoute | Change endpoint, reset meta/cache |
174
+ | setRouteParams | Fill route url with params |
173
175
  | updateConfig | Patch config and apply presets |
174
176
  | copy | Copy config/meta from another store |
175
177
  | destroy | Manual destroying of caches and abort requests |
@@ -206,8 +208,8 @@ Helper for dictionaries/options (select/autocomplete) on top of PaginatedDataSto
206
208
  ### Key behavior
207
209
 
208
210
  - Two modes:
209
- - `fixed: true` — first load fills local cache; search happens locally
210
- - `fixed: false` — search goes to server (passes filter `name`)
211
+ - `fixed: true` - first load fills local cache; search happens locally
212
+ - `fixed: false` - search goes to server (passes filter `name`)
211
213
  - Local cache merges without duplicates and is size-limited
212
214
 
213
215
  ### Public API
@@ -231,17 +233,17 @@ Methods:
231
233
 
232
234
  Config:
233
235
 
234
- | Option | Type | Default | Description |
235
- |---------------|-----------------------------------------------|------------|---------------------------------------------|
236
- | labelKey | `string` | `'label'` | Property name to use as option label |
237
- | valueKey | `string` | `'value'` | Property name to use as option value |
238
- | fixed | `boolean` | `false` | Use local search instead of server requests |
239
- | method | `'GET' \| 'POST'` | `'GET'` | HTTP method for requests |
240
- | cacheKey | `string \| null` | `null` | Storage key for persisting cache |
241
- | debounceTime | `number` | `200` | Debounce time for search requests |
242
- | pageSize | `number` | `50` | Page size for server requests |
243
- | cacheLimit | `number` | `1000` | Maximum items in local cache |
244
- | cacheStrategy | `'persist' \| 'session' \| 'memory' \| 'lru'` | `'memory'` | Cache storage strategy |
236
+ | Option | Type | Default | Description |
237
+ |----------------|--------------------------------------|-------------|---------------------------------------------|
238
+ | labelKey | `string` | `'name'` | Property name to use as option label |
239
+ | valueKey | `string` | `'code'` | Property name to use as option value |
240
+ | fixed | `boolean` | `true` | Use local search instead of server requests |
241
+ | method | `'GET' \| 'POST'` | `'POST'` | HTTP method for requests |
242
+ | debounceTime | `number` | `0` | Debounce time for search requests |
243
+ | maxOptionsSize | `number` | `undefined` | Maximum items exposed in `options` |
244
+ | cacheStrategy | `'persist' \| 'session' \| 'memory'` | `'persist'` | Cache storage strategy |
245
+ | keyPrefix | `string` | `'re'` | Prefix for storage keys |
246
+ | presetFilters | `Record<string, string>` | `{}` | Filters merged into each request |
245
247
 
246
248
  Example:
247
249
 
@@ -266,16 +268,16 @@ dict.search('kir'); // local search over cache
266
268
 
267
269
  ### Serializer
268
270
 
269
- Utility for serialization/deserialization between layers (UI ↔ API, objects ↔ query string).
271
+ Utility for serialization/deserialization between layers (UI -> API, objects -> query string).
270
272
 
271
273
  Core API:
272
274
 
273
- | Method | Description |
274
- |---|---|
275
- | serialize | Prepare data for transport |
276
- | deserialize | Parse incoming data / query string |
277
- | toQuery | Build query string |
278
- | withConfig | Clone serializer with partial config overrides |
275
+ | Method | Description |
276
+ |-------------|------------------------------------------------|
277
+ | serialize | Prepare data for transport |
278
+ | deserialize | Parse incoming data / query string |
279
+ | toQuery | Build query string |
280
+ | withConfig | Clone serializer with partial config overrides |
279
281
 
280
282
  Config:
281
283