memorio 2.7.4 → 2.9.0
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.
- package/README.md +470 -370
- package/docs/README.md +470 -0
- package/docs/SUMMARY.md +26 -0
- package/docs/_config.yml +1 -0
- package/docs/markdown/CACHE.md +90 -0
- package/docs/markdown/CHANGELOG.md +184 -0
- package/docs/markdown/DEVTOOLS.md +122 -0
- package/docs/markdown/IDB.md +169 -0
- package/docs/markdown/LOGGER.md +147 -0
- package/docs/markdown/OBSERVER.md +180 -0
- package/docs/markdown/PLATFORM.md +260 -0
- package/docs/markdown/SECURITY.md +306 -0
- package/docs/markdown/SESSION.md +154 -0
- package/docs/markdown/STATE.md +150 -0
- package/docs/markdown/STORE.md +161 -0
- package/docs/markdown/USEOBSERVER.md +158 -0
- package/examples/basic.ts +1 -1
- package/examples/cache.ts +1 -1
- package/examples/idb.ts +1 -1
- package/examples/node-server.ts +1 -1
- package/examples/observer.ts +1 -1
- package/examples/platform.ts +1 -1
- package/examples/react-app.tsx +1 -1
- package/examples/session-advanced.ts +1 -1
- package/examples/state-advanced.ts +1 -1
- package/examples/store-advanced.ts +1 -1
- package/examples/{useObserver.ts → useObserver.tsx} +35 -35
- package/index.cjs +47 -29
- package/index.js +47 -27
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,370 +1,470 @@
|
|
|
1
|
-
# [memorio](https://npmjs.com/package/memorio)
|
|
2
|
-
|
|
3
|
-
> A lightweight, type-safe state management library for JavaScript applications
|
|
4
|
-
|
|
5
|
-
[](https://npmjs.org/package/memorio)
|
|
6
|
-
[](https://packagephobia.now.sh/result?p=memorio)
|
|
7
|
-
[](https://npmjs.org/package/memorio)
|
|
8
|
-
|
|
9
|
-
|
|
2
|
+
|
|
3
|
+
> A lightweight, type-safe state management library for JavaScript applications
|
|
4
|
+
|
|
5
|
+
[](https://npmjs.org/package/memorio)
|
|
6
|
+
[](https://packagephobia.now.sh/result?p=memorio)
|
|
7
|
+
[](https://npmjs.org/package/memorio)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
[](https://a51.gitbook.io/memorio)
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Table of Contents
|
|
24
|
+
|
|
25
|
+
- [Features](#features)
|
|
26
|
+
- [Installation](#installation)
|
|
27
|
+
- [Quick Start](#quick-start)
|
|
28
|
+
- [API Reference](#api-reference)
|
|
29
|
+
- [State Management](#state-management)
|
|
30
|
+
- [Observer](#observer)
|
|
31
|
+
- [useObserver](#useobserver)
|
|
32
|
+
- [Store](#store)
|
|
33
|
+
- [Session](#session)
|
|
34
|
+
- [Cache](#cache)
|
|
35
|
+
- [idb](#idb)
|
|
36
|
+
- [DevTools](#devtools)
|
|
37
|
+
- [Logger](#logger)
|
|
38
|
+
- [Testing](#testing)
|
|
39
|
+
- [Security](#security)
|
|
40
|
+
- [License](#license)
|
|
41
|
+
- [Cross-Platform Support](#cross-platform-support)
|
|
42
|
+
- [Platform & Context Isolation](docs/markdown/PLATFORM.md)
|
|
43
|
+
|
|
44
|
+
## Features
|
|
45
|
+
|
|
46
|
+
- Reactive state management with observer pattern
|
|
47
|
+
- Persistent storage with Store API
|
|
48
|
+
- Session management for temporary data
|
|
49
|
+
- Type-safe with full TypeScript support
|
|
50
|
+
- Comprehensive test coverage
|
|
51
|
+
- Easy debugging with proxy-based state
|
|
52
|
+
- **Cross-platform**: Works in Browser, Node.js, Deno, and Edge Workers
|
|
53
|
+
- **Session Isolation**: Each session/request gets isolated state namespace
|
|
54
|
+
- **Context System**: Multi-tenant server-side isolation with `memorio.createContext()`
|
|
55
|
+
- **DevTools**: Browser console debugging tools
|
|
56
|
+
- **Logger**: Automatic logging of state changes
|
|
57
|
+
|
|
58
|
+
## Installation
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npm i -D memorio
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### All test suites are passing
|
|
65
|
+
|
|
66
|
+
- Basic functionality tests
|
|
67
|
+
- State management tests
|
|
68
|
+
- Store operations tests
|
|
69
|
+
- Cache operations tests
|
|
70
|
+
- Observer pattern tests
|
|
71
|
+
- useObserver pattern tests
|
|
72
|
+
- DevTools tests
|
|
73
|
+
- Logger tests
|
|
74
|
+
|
|
75
|
+
Total: 71 tests passed across 8 test suites
|
|
76
|
+
|
|
77
|
+
## Quick Start
|
|
78
|
+
|
|
79
|
+
```javascript
|
|
80
|
+
/*
|
|
81
|
+
IMPORTANT!
|
|
82
|
+
Add import only at first start of your SPA. Became global!.
|
|
83
|
+
You don't need to import any time you need to use memorio
|
|
84
|
+
*/
|
|
85
|
+
|
|
86
|
+
import 'memorio';
|
|
87
|
+
|
|
88
|
+
// State Management
|
|
89
|
+
state.counter = 0;
|
|
90
|
+
state.active = false;
|
|
91
|
+
state.name = "john";
|
|
92
|
+
state.user = { name: 'John', age: 30 };
|
|
93
|
+
state.hours = [2,3,10,23]
|
|
94
|
+
|
|
95
|
+
// Observer Pattern for not react app
|
|
96
|
+
// Example: if you change the state.counter you get a console.log
|
|
97
|
+
observer(
|
|
98
|
+
'state.counter',
|
|
99
|
+
(newValue, oldValue) => {
|
|
100
|
+
console.log(`Counter changed from ${oldValue} to ${newValue}`);
|
|
101
|
+
}
|
|
102
|
+
);
|
|
103
|
+
|
|
104
|
+
// useObserver Pattern for react app
|
|
105
|
+
// Example: if you change the state.counter you get a console.log
|
|
106
|
+
useObserver(
|
|
107
|
+
(newValue, oldValue) => {
|
|
108
|
+
console.log(`Counter changed from ${oldValue} to ${newValue}`);
|
|
109
|
+
},
|
|
110
|
+
[state.counter]
|
|
111
|
+
);
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
// Store (Persistent Storage)
|
|
115
|
+
store.set('preferences', { theme: 'dark' });
|
|
116
|
+
const preferences = store.get('preferences');
|
|
117
|
+
|
|
118
|
+
// Session Storage
|
|
119
|
+
session.set('token', 'user-jwt-token');
|
|
120
|
+
const token = session.get('token');
|
|
121
|
+
|
|
122
|
+
// DevTools
|
|
123
|
+
memorio.devtools.inspect();
|
|
124
|
+
|
|
125
|
+
// Logger
|
|
126
|
+
memorio.logger.configure({ enabled: true, logToConsole: true })
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## API Reference
|
|
130
|
+
|
|
131
|
+
### State Management
|
|
132
|
+
|
|
133
|
+
State in Memorio is globally accessible and reactive:
|
|
134
|
+
|
|
135
|
+
```javascript
|
|
136
|
+
// Setting state
|
|
137
|
+
state.user = { name: 'John' };
|
|
138
|
+
|
|
139
|
+
// Getting state
|
|
140
|
+
const userName = state.user.name;
|
|
141
|
+
|
|
142
|
+
// Listing all states
|
|
143
|
+
console.log(state.list);
|
|
144
|
+
|
|
145
|
+
// Removing state
|
|
146
|
+
state.remove('user');
|
|
147
|
+
|
|
148
|
+
// Clearing all states
|
|
149
|
+
state.removeAll();
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Observer
|
|
153
|
+
|
|
154
|
+
> ⚠️ **Deprecated**: For React applications, use [`useObserver`](#useobserver-pattern) instead. The `observer` function is kept for non-React contexts.
|
|
155
|
+
|
|
156
|
+
```javascript
|
|
157
|
+
// Observing a state path
|
|
158
|
+
observer(
|
|
159
|
+
'state.user.name',
|
|
160
|
+
(newValue, oldValue) => {
|
|
161
|
+
console.log(`Name changed from ${oldValue} to ${newValue}`);
|
|
162
|
+
}
|
|
163
|
+
);
|
|
164
|
+
|
|
165
|
+
// Observing with options
|
|
166
|
+
observer(
|
|
167
|
+
'state.counter',
|
|
168
|
+
(newValue, oldValue) => {
|
|
169
|
+
console.log(`Counter: ${oldValue} → ${newValue}`);
|
|
170
|
+
},
|
|
171
|
+
{ immediate: true } // Call immediately with current value
|
|
172
|
+
);
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### useObserver
|
|
176
|
+
|
|
177
|
+
useObserver is a React hook for observing Memorio state changes with auto-discovery:
|
|
178
|
+
|
|
179
|
+
```js
|
|
180
|
+
// Basic useObserver - array syntax with state path
|
|
181
|
+
useObserver(
|
|
182
|
+
() => {
|
|
183
|
+
console.log('User updated:', state.user);
|
|
184
|
+
},
|
|
185
|
+
[state.user]
|
|
186
|
+
);
|
|
187
|
+
|
|
188
|
+
// Multiple states
|
|
189
|
+
useObserver(
|
|
190
|
+
() => {
|
|
191
|
+
console.log('States changed:', state.user, state.counter, state.settings);
|
|
192
|
+
},
|
|
193
|
+
[state.user, state.counter, state.settings]
|
|
194
|
+
);
|
|
195
|
+
|
|
196
|
+
// With options
|
|
197
|
+
useObserver(
|
|
198
|
+
() => {
|
|
199
|
+
console.log('Value changed');
|
|
200
|
+
},
|
|
201
|
+
[state.value],
|
|
202
|
+
{ immediate: true }
|
|
203
|
+
);
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
**Key differences from observer:**
|
|
207
|
+
1. Uses **array syntax** `[state.property]` instead of string path `'state.property'`
|
|
208
|
+
2. Automatically cleans up on component unmount
|
|
209
|
+
3. Works only inside React components
|
|
210
|
+
4. Callback receives `(newValue, oldValue)` parameters
|
|
211
|
+
|
|
212
|
+
### Store
|
|
213
|
+
|
|
214
|
+
Persistent storage for your application:
|
|
215
|
+
|
|
216
|
+
```javascript
|
|
217
|
+
// Setting values
|
|
218
|
+
store.set('config', { theme: 'dark', language: 'en' });
|
|
219
|
+
|
|
220
|
+
// Getting values
|
|
221
|
+
const config = store.get('config');
|
|
222
|
+
|
|
223
|
+
// Removing specific value
|
|
224
|
+
store.remove('config');
|
|
225
|
+
|
|
226
|
+
// Getting store size
|
|
227
|
+
const size = store.size();
|
|
228
|
+
|
|
229
|
+
// Clearing store
|
|
230
|
+
store.removeAll();
|
|
231
|
+
|
|
232
|
+
// Check if using persistent storage
|
|
233
|
+
if (store.isPersistent) {
|
|
234
|
+
console.log('Using real localStorage');
|
|
235
|
+
} else {
|
|
236
|
+
console.log('Using memory fallback (server environment)');
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### Session
|
|
241
|
+
|
|
242
|
+
Temporary storage that persists during page sessions:
|
|
243
|
+
|
|
244
|
+
```js
|
|
245
|
+
// Setting session data
|
|
246
|
+
session.set(
|
|
247
|
+
'userSession', {
|
|
248
|
+
id: 'user123',
|
|
249
|
+
lastActive: Date.now()
|
|
250
|
+
}
|
|
251
|
+
);
|
|
252
|
+
|
|
253
|
+
// Getting session data
|
|
254
|
+
const userData = session.get('userSession');
|
|
255
|
+
|
|
256
|
+
// Checking session size
|
|
257
|
+
const activeItems = session.size();
|
|
258
|
+
|
|
259
|
+
// Removing session data
|
|
260
|
+
session.remove('userSession');
|
|
261
|
+
|
|
262
|
+
// Clearing all session data
|
|
263
|
+
session.removeAll();
|
|
264
|
+
|
|
265
|
+
// Check if using persistent storage
|
|
266
|
+
if (session.isPersistent) {
|
|
267
|
+
console.log('Using real sessionStorage');
|
|
268
|
+
} else {
|
|
269
|
+
console.log('Using memory fallback (server environment)');
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### Cache
|
|
274
|
+
|
|
275
|
+
In-memory cache for temporary data storage:
|
|
276
|
+
|
|
277
|
+
```js
|
|
278
|
+
// Setting cache data
|
|
279
|
+
cache.set('tempData', { computed: true, value: 42 });
|
|
280
|
+
|
|
281
|
+
// Getting cache data
|
|
282
|
+
const cached = cache.get('tempData');
|
|
283
|
+
|
|
284
|
+
// Checking cache size
|
|
285
|
+
const cacheSize = cache.size();
|
|
286
|
+
|
|
287
|
+
// Removing cache data
|
|
288
|
+
cache.remove('tempData');
|
|
289
|
+
|
|
290
|
+
// Clearing all cache data
|
|
291
|
+
cache.removeAll();
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
**Note:** Cache data is stored in memory and will be lost on page refresh.
|
|
295
|
+
|
|
296
|
+
### idb
|
|
297
|
+
|
|
298
|
+
Permanent storage using browser database:
|
|
299
|
+
|
|
300
|
+
#### Create database
|
|
301
|
+
|
|
302
|
+
```js
|
|
303
|
+
idb.db.create("Database");
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
#### Set data into table
|
|
307
|
+
|
|
308
|
+
```js
|
|
309
|
+
idb.data.set("Database","table", { id: 1, data:{...} } );
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
#### Get data from table
|
|
313
|
+
|
|
314
|
+
> [in development]
|
|
315
|
+
|
|
316
|
+
```js
|
|
317
|
+
idb.data.get("Database","table", 1 );
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
#### Delete database / table
|
|
321
|
+
|
|
322
|
+
> [in development]
|
|
323
|
+
|
|
324
|
+
```js
|
|
325
|
+
idb.db.delete("Database") // Remove DB
|
|
326
|
+
idb.table.delete("Database","table") // Remove only "table"
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
### DevTools
|
|
330
|
+
|
|
331
|
+
Browser console debugging tools for inspecting state, store, session, cache:
|
|
332
|
+
|
|
333
|
+
```javascript
|
|
334
|
+
// Inspect all state modules
|
|
335
|
+
memorio.devtools.inspect();
|
|
336
|
+
|
|
337
|
+
// Get statistics
|
|
338
|
+
memorio.devtools.stats();
|
|
339
|
+
|
|
340
|
+
// Clear specific module
|
|
341
|
+
memorio.devtools.clear('state');
|
|
342
|
+
|
|
343
|
+
// Clear all modules
|
|
344
|
+
memorio.devtools.clearAll();
|
|
345
|
+
|
|
346
|
+
// Watch a path for changes
|
|
347
|
+
memorio.devtools.watch('state', 'user.name');
|
|
348
|
+
|
|
349
|
+
// Export all data as JSON
|
|
350
|
+
memorio.devtools.exportData();
|
|
351
|
+
|
|
352
|
+
// Import data from JSON
|
|
353
|
+
memorio.devtools.importData(jsonString);
|
|
354
|
+
|
|
355
|
+
// Get help
|
|
356
|
+
memorio.devtools.help();
|
|
357
|
+
|
|
358
|
+
// Console shortcuts (available in browser console)
|
|
359
|
+
$state // globalThis.state
|
|
360
|
+
$store // globalThis.store
|
|
361
|
+
$session // globalThis.session
|
|
362
|
+
$cache // globalThis.cache
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
### Logger
|
|
366
|
+
|
|
367
|
+
Logging middleware for tracking all state changes:
|
|
368
|
+
|
|
369
|
+
```javascript
|
|
370
|
+
// Configure logger
|
|
371
|
+
memorio.logger.configure({ enabled: true, logToConsole: true });
|
|
372
|
+
|
|
373
|
+
// Enable/disable logging
|
|
374
|
+
memorio.logger.enable();
|
|
375
|
+
memorio.logger.disable();
|
|
376
|
+
|
|
377
|
+
// Get log history
|
|
378
|
+
memorio.logger.getHistory();
|
|
379
|
+
|
|
380
|
+
// Get statistics
|
|
381
|
+
memorio.logger.getStats();
|
|
382
|
+
|
|
383
|
+
// Clear history
|
|
384
|
+
memorio.logger.clearHistory();
|
|
385
|
+
|
|
386
|
+
// Export logs as JSON
|
|
387
|
+
memorio.logger.exportLogs();
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
## Testing
|
|
391
|
+
|
|
392
|
+
All test suites are passing:
|
|
393
|
+
|
|
394
|
+
- Basic functionality tests
|
|
395
|
+
- State management tests
|
|
396
|
+
- Store operations tests
|
|
397
|
+
- Cache operations tests
|
|
398
|
+
- Observer pattern tests
|
|
399
|
+
- useObserver pattern tests
|
|
400
|
+
- DevTools tests
|
|
401
|
+
- Logger tests
|
|
402
|
+
|
|
403
|
+
Total: 71 tests passed across 8 test suites
|
|
404
|
+
|
|
405
|
+
## Security
|
|
406
|
+
|
|
407
|
+
Security scans and reports are available at:
|
|
408
|
+
|
|
409
|
+
- [Socket.dev](https://socket.dev/npm/package/memorio)
|
|
410
|
+
- [Snyk.io](https://security.snyk.io/package/npm/memorio)
|
|
411
|
+
|
|
412
|
+
## License
|
|
413
|
+
|
|
414
|
+
MIT License
|
|
415
|
+
|
|
416
|
+
Copyright (c) [Dario Passariello](https://dario.passariello.ca/)
|
|
417
|
+
|
|
418
|
+
---
|
|
419
|
+
|
|
420
|
+
## Cross-Platform Support
|
|
421
|
+
|
|
422
|
+
Memorio is designed to work across multiple JavaScript environments:
|
|
423
|
+
|
|
424
|
+
### Platform Compatibility
|
|
425
|
+
|
|
426
|
+
| Feature | Browser | Node.js | Deno | Edge Workers |
|
|
427
|
+
|---------|---------|---------|------|---------------|
|
|
428
|
+
| `state` | ✅ | ✅ | ✅ | ✅ |
|
|
429
|
+
| `observer` | ✅ | ✅ | ✅ | ✅ |
|
|
430
|
+
| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
|
|
431
|
+
| `cache` | ✅ | ✅ | ✅ | ✅ |
|
|
432
|
+
| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
|
|
433
|
+
| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
|
|
434
|
+
| `idb` | ✅ | ❌ | ❌ | ⚠️ |
|
|
435
|
+
| `devtools` | ✅ | ❌ | ❌ | ⚠️ |
|
|
436
|
+
| `logger` | ✅ | ✅ | ✅ | ✅ |
|
|
437
|
+
|
|
438
|
+
- ✅ Full support
|
|
439
|
+
- ⚠️ Partial support (fallback to in-memory)
|
|
440
|
+
- ❌ Not available
|
|
441
|
+
|
|
442
|
+
### Session Isolation
|
|
443
|
+
|
|
444
|
+
Memorio provides automatic session isolation to prevent state leakage between different requests or contexts:
|
|
445
|
+
|
|
446
|
+
- **Unique Session IDs**: Each import gets a unique session identifier
|
|
447
|
+
- **Namespaced Storage**: `store` and `session` keys are prefixed with session ID
|
|
448
|
+
- **State Isolation**: `state` is isolated per-instance
|
|
449
|
+
|
|
450
|
+
This ensures that in server-side environments (Node.js/Deno), different requests don't share state data.
|
|
451
|
+
|
|
452
|
+
### Best Practices
|
|
453
|
+
|
|
454
|
+
1. **For Client-Side**: Use all features freely - store, session, idb work with real browser storage
|
|
455
|
+
2. **For Server-Side**: Use `state` and `cache` for in-memory data; store/session fall back to memory
|
|
456
|
+
3. **For Edge Workers**: Same as browser; localStorage/sessionStorage available
|
|
457
|
+
|
|
458
|
+
### Checking Platform
|
|
459
|
+
|
|
460
|
+
```javascript
|
|
461
|
+
import { isBrowser, isNode, isDeno, getCapabilities } from 'memorio';
|
|
462
|
+
|
|
463
|
+
console.log('Browser:', isBrowser()); // true in browser
|
|
464
|
+
console.log('Node.js:', isNode()); // true in Node.js
|
|
465
|
+
console.log('Deno:', isDeno()); // true in Deno
|
|
466
|
+
|
|
467
|
+
const caps = getCapabilities();
|
|
468
|
+
console.log('Platform:', caps.platform); // 'browser' | 'node' | 'deno' | 'edge'
|
|
469
|
+
console.log('Persistent:', store.isPersistent); // true if using real storage
|
|
470
|
+
```
|