memorio 2.8.0 → 2.9.0

package/README.md

@@ -1,366 +1,470 @@
-# [memorio](https://npmjs.com/package/memorio)
-
-> A lightweight, type-safe state management library for JavaScript applications
-
-[![version](https://img.shields.io/npm/v/memorio.svg)](https://npmjs.org/package/memorio)
-[![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=memorio&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.now.sh/result?p=memorio)
-[![downloads](https://img.shields.io/npm/dm/memorio.svg)](https://npmjs.org/package/memorio)
-
-![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
-![React](https://img.shields.io/badge/React-gray?logo=React)
-![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
-![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
-![esbuild](https://img.shields.io/badge/esbuild-gray?logo=esbuild)
-
-![Jest](https://img.shields.io/badge/Jest-gray?logo=jest)
-![ESLint](https://img.shields.io/badge/Eslint-gray?logo=eslint)
-![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
-
-[![GitBook](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://a51.gitbook.io/memorio)
-
----
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [API Reference](#api-reference)
-  - [State Management](#state-management)
-  - [useObserver](#useobserver)
-  - [Store](#store)
-  - [Session](#session)
-  - [Cache](#cache)
-  - [idb](#idb)
-- [Testing](#testing)
-- [Security](#security)
-- [License](#license)
-- [Cross-Platform Support](#cross-platform-support)
-  - [Platform & Context Isolation](docs/markdown/PLATFORM.md)
-
-## Features
-
-- Reactive state management with observer pattern
-- Persistent storage with Store API
-- Session management for temporary data
-- Type-safe with full TypeScript support
-- Comprehensive test coverage
-- Easy debugging with proxy-based state
-- **Cross-platform**: Works in Browser, Node.js, Deno, and Edge Workers
-- **Session Isolation**: Each session/request gets isolated state namespace
-- **Context System**: Multi-tenant server-side isolation with `memorio.createContext()`
-
-## ⚠️ Enterprise Use
-
-For **enterprise-level applications** requiring advanced state management, we recommend using **[@biglogic/rgs](https://npmjs.com/package/@biglogic/rgs)** instead of Memorio.
-
-RGS provides:
-- Enhanced scalability for large applications
-- Advanced middleware support
-- Enterprise-grade security features
-- Professional support and maintenance
-
-Memorio is ideal for small to medium projects, prototypes, and learning purposes.
-
-## Installation
-
-```bash
-npm i -D memorio
-```
-
-### All test suites are passing
-
-- Basic functionality tests
-- State management tests
-- Store operations tests
-- Cache operations tests
-- Observer pattern tests
-- useObserver pattern tests
-
-Total: 28 tests passed across 5 test suites
-
-## Quick Start
-
-```javascript
-/*
- IMPORTANT!
- Add import only at first start of your SPA. Became global!.
- You don't need to import any time you need to use memorio
-*/
-
-import 'memorio';
-
-// State Management
-state.counter = 0;
-state.active = false;
-state.name = "john";
-state.user = { name: 'John', age: 30 };
-state.hours = [2,3,10,23]
-
-// Observer Pattern
-// Example: if you change the state.counter you get a console.log
-observer(
-  'state.counter',
-    (newValue, oldValue) => {
-    console.log(`Counter changed from ${oldValue} to ${newValue}`);
-  }
-);
-
-// useObserver Pattern
-// Example: if you change the state.counter you get a console.log
-useObserver(
-    (newValue, oldValue) => {
-      console.log(`Counter changed from ${oldValue} to ${newValue}`);
-    },
-    [state.counter]
-);
-
-
-// Store (Persistent Storage)
-store.set('preferences', { theme: 'dark' });
-const preferences = store.get('preferences');
-
-// Session Storage
-session.set('token', 'user-jwt-token');
-const token = session.get('token');
-```
-
-## API Reference
-
-### State Management
-
-State in Memorio is globally accessible and reactive:
-
-```javascript
-// Setting state
-state.user = { name: 'John' };
-
-// Getting state
-const userName = state.user.name;
-
-// Listing all states
-console.log(state.list);
-
-// Removing state
-state.remove('user');
-
-// Clearing all states
-state.removeAll();
-
-```
-
-### Observer
-
-> ⚠️ **Deprecated**: For React applications, use [`useObserver`](#useobserver-pattern) instead. The `observer` function is kept for non-React contexts.
-
-## useObserver
-
-useObserver is a React hook for observing Memorio state changes with auto-discovery:
-
-```js
-
-// Basic useObserver - array syntax with state path
-useObserver(
-  (newValue, oldValue) => {
-    console.log('User updated:', newValue);
-  },
-  [state.user]
-);
-
-// Multiple states
-useObserver(
-  (newValue, oldValue) => {
-    console.log('State changed:', newValue);
-  },
-  [state.user, state.counter, state.settings]
-);
-
-```
-
-**Key differences from observer:**
-1. Uses **array syntax** `[state.property]` instead of string path `'state.property'`
-2. Automatically cleans up on component unmount
-3. Works only inside React components
-4. Callback receives `(newValue, oldValue)` parameters
-
-## Store
-
-Persistent storage for your application:
-
-```javascript
-// Setting values
-store.set('config', { theme: 'dark', language: 'en' });
-
-// Getting values
-const config = store.get('config');
-
-// Removing specific value
-store.remove('config');
-
-// Getting store size
-const size = store.size();
-
-// Clearing store
-store.removeAll();
-```
-
-## Session
-
-Temporary storage that persists during page sessions:
-
-```js
-// Setting session data
-session.set(
-  'userSession', {
-    id: 'user123',
-    lastActive: Date.now()
-  }
-);
-
-// Getting session data
-const userData = session.get('userSession');
-
-// Checking session size
-const activeItems = session.size();
-
-// Removing session data
-session.remove('userSession');
-
-// Clearing all session data
-session.removeAll();
-```
-
-## Cache
-
-In-memory cache for temporary data storage:
-
-```js
-// Setting cache data
-cache.set('tempData', { computed: true, value: 42 });
-
-// Getting cache data
-const cached = cache.get('tempData');
-
-// Checking cache size
-const cacheSize = cache.size();
-
-// Removing cache data
-cache.remove('tempData');
-
-// Clearing all cache data
-cache.removeAll();
-```
-
-**Note:** Cache data is stored in memory and will be lost on page refresh.
-
-## idb
-
-Permanent storage using browser database:
-
-### Create database
-
-```js
-idb.db.create("Database")
-```
-
-### Set data into table
-
-```js
-idb.data.set("Database","table", { id: 1, data:{...} } )
-```
-
-### Get data from table
-
-> [in development]
-
-```js
-idb.data.get("Database","table", 1 )
-```
-
-### Delete database / table
-
-> [in development]
-
-```js
-idb.db.delete("Database") // Remove DB
-idb.table.delete("Database","table") // Remove only "table"
-```
-
----
-
-## Testing
-
-## Test suites are passing
-
-- Basic functionality tests
-- State management tests
-- Store operations tests
-- Cache operations tests
-- Observer pattern tests
-
-Total: 25 tests passed across 5 test suites
-
-## Security
-
-Security scans and reports are available at:
-
-- [Socket.dev](https://socket.dev/npm/package/memorio)
-- [Snyk.io](https://security.snyk.io/package/npm/memorio)
-
-## License
-
-MIT License
-
-Copyrigth (c) [Dario Passariello](https://dario.passariello.ca/)
-
----
-
-## Cross-Platform Support
-
-Memorio is designed to work across multiple JavaScript environments:
-
-### Platform Compatibility
-
-| Feature | Browser | Node.js | Deno | Edge Workers |
-|---------|---------|---------|------|---------------|
-| `state` | ✅ | ✅ | ✅ | ✅ |
-| `observer` | ✅ | ✅ | ✅ | ✅ |
-| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
-| `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
-| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
-| `idb` | ✅ | ❌ | ❌ | ⚠️ |
-
-- ✅ Full support
-- ⚠️ Partial support (fallback to in-memory)
-- ❌ Not available
-
-### Session Isolation
-
-Memorio provides automatic session isolation to prevent state leakage between different requests or contexts:
-
-- **Unique Session IDs**: Each import gets a unique session identifier
-- **Namespaced Storage**: `store` and `session` keys are prefixed with session ID
-- **State Isolation**: `state` is isolated per-instance
-
-This ensures that in server-side environments (Node.js/Deno), different requests don't share state data.
-
-### Best Practices
-
-1. **For Client-Side**: Use all features freely - store, session, idb work with real browser storage
-2. **For Server-Side**: Use `state` and `cache` for in-memory data; store/session fall back to memory
-3. **For Edge Workers**: Same as browser; localStorage/sessionStorage available
-
-### Checking Platform
-
-```javascript
-import { isBrowser, isNode, isDeno, getCapabilities } from 'memorio';
-
-console.log('Browser:', isBrowser());      // true in browser
-console.log('Node.js:', isNode());          // true in Node.js
-console.log('Deno:', isDeno());             // true in Deno
-
-const caps = getCapabilities();
-console.log('Platform:', caps.platform);    // 'browser' | 'node' | 'deno' | 'edge'
-console.log('Persistent:', store.isPersistent); // true if using real storage
-```
+# [memorio](https://npmjs.com/package/memorio)
+
+> A lightweight, type-safe state management library for JavaScript applications
+
+[![version](https://img.shields.io/npm/v/memorio.svg)](https://npmjs.org/package/memorio)
+[![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=memorio&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.now.sh/result?p=memorio)
+[![downloads](https://img.shields.io/npm/dm/memorio.svg)](https://npmjs.org/package/memorio)
+
+![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
+![React](https://img.shields.io/badge/React-gray?logo=React)
+![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
+![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
+![esbuild](https://img.shields.io/badge/esbuild-gray?logo=esbuild)
+
+![Jest](https://img.shields.io/badge/Jest-gray?logo=jest)
+![ESLint](https://img.shields.io/badge/Eslint-gray?logo=eslint)
+![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
+
+[![GitBook](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://a51.gitbook.io/memorio)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [State Management](#state-management)
+  - [Observer](#observer)
+  - [useObserver](#useobserver)
+  - [Store](#store)
+  - [Session](#session)
+  - [Cache](#cache)
+  - [idb](#idb)
+  - [DevTools](#devtools)
+  - [Logger](#logger)
+- [Testing](#testing)
+- [Security](#security)
+- [License](#license)
+- [Cross-Platform Support](#cross-platform-support)
+  - [Platform & Context Isolation](docs/markdown/PLATFORM.md)
+
+## Features
+
+- Reactive state management with observer pattern
+- Persistent storage with Store API
+- Session management for temporary data
+- Type-safe with full TypeScript support
+- Comprehensive test coverage
+- Easy debugging with proxy-based state
+- **Cross-platform**: Works in Browser, Node.js, Deno, and Edge Workers
+- **Session Isolation**: Each session/request gets isolated state namespace
+- **Context System**: Multi-tenant server-side isolation with `memorio.createContext()`
+- **DevTools**: Browser console debugging tools
+- **Logger**: Automatic logging of state changes
+
+## Installation
+
+```bash
+npm i -D memorio
+```
+
+### All test suites are passing
+
+- Basic functionality tests
+- State management tests
+- Store operations tests
+- Cache operations tests
+- Observer pattern tests
+- useObserver pattern tests
+- DevTools tests
+- Logger tests
+
+Total: 71 tests passed across 8 test suites
+
+## Quick Start
+
+```javascript
+/*
+  IMPORTANT!
+  Add import only at first start of your SPA. Became global!.
+  You don't need to import any time you need to use memorio
+*/
+
+import 'memorio';
+
+// State Management
+state.counter = 0;
+state.active = false;
+state.name = "john";
+state.user = { name: 'John', age: 30 };
+state.hours = [2,3,10,23]
+
+// Observer Pattern for not react app
+// Example: if you change the state.counter you get a console.log
+observer(
+  'state.counter',
+    (newValue, oldValue) => {
+    console.log(`Counter changed from ${oldValue} to ${newValue}`);
+  }
+);
+
+// useObserver Pattern for react app
+// Example: if you change the state.counter you get a console.log
+useObserver(
+    (newValue, oldValue) => {
+      console.log(`Counter changed from ${oldValue} to ${newValue}`);
+    },
+    [state.counter]
+);
+
+
+// Store (Persistent Storage)
+store.set('preferences', { theme: 'dark' });
+const preferences = store.get('preferences');
+
+// Session Storage
+session.set('token', 'user-jwt-token');
+const token = session.get('token');
+
+// DevTools
+memorio.devtools.inspect();
+
+// Logger
+memorio.logger.configure({ enabled: true, logToConsole: true })
+```
+
+## API Reference
+
+### State Management
+
+State in Memorio is globally accessible and reactive:
+
+```javascript
+// Setting state
+state.user = { name: 'John' };
+
+// Getting state
+const userName = state.user.name;
+
+// Listing all states
+console.log(state.list);
+
+// Removing state
+state.remove('user');
+
+// Clearing all states
+state.removeAll();
+```
+
+### Observer
+
+> ⚠️ **Deprecated**: For React applications, use [`useObserver`](#useobserver-pattern) instead. The `observer` function is kept for non-React contexts.
+
+```javascript
+// Observing a state path
+observer(
+  'state.user.name',
+  (newValue, oldValue) => {
+    console.log(`Name changed from ${oldValue} to ${newValue}`);
+  }
+);
+
+// Observing with options
+observer(
+  'state.counter',
+  (newValue, oldValue) => {
+    console.log(`Counter: ${oldValue} → ${newValue}`);
+  },
+  { immediate: true } // Call immediately with current value
+);
+```
+
+### useObserver
+
+useObserver is a React hook for observing Memorio state changes with auto-discovery:
+
+```js
+// Basic useObserver - array syntax with state path
+useObserver(
+  () => {
+    console.log('User updated:', state.user);
+  },
+  [state.user]
+);
+
+// Multiple states
+useObserver(
+  () => {
+    console.log('States changed:', state.user, state.counter, state.settings);
+  },
+  [state.user, state.counter, state.settings]
+);
+
+// With options
+useObserver(
+  () => {
+    console.log('Value changed');
+  },
+  [state.value],
+  { immediate: true }
+);
+```
+
+**Key differences from observer:**
+1. Uses **array syntax** `[state.property]` instead of string path `'state.property'`
+2. Automatically cleans up on component unmount
+3. Works only inside React components
+4. Callback receives `(newValue, oldValue)` parameters
+
+### Store
+
+Persistent storage for your application:
+
+```javascript
+// Setting values
+store.set('config', { theme: 'dark', language: 'en' });
+
+// Getting values
+const config = store.get('config');
+
+// Removing specific value
+store.remove('config');
+
+// Getting store size
+const size = store.size();
+
+// Clearing store
+store.removeAll();
+
+// Check if using persistent storage
+if (store.isPersistent) {
+  console.log('Using real localStorage');
+} else {
+  console.log('Using memory fallback (server environment)');
+}
+```
+
+### Session
+
+Temporary storage that persists during page sessions:
+
+```js
+// Setting session data
+session.set(
+  'userSession', {
+    id: 'user123',
+    lastActive: Date.now()
+  }
+);
+
+// Getting session data
+const userData = session.get('userSession');
+
+// Checking session size
+const activeItems = session.size();
+
+// Removing session data
+session.remove('userSession');
+
+// Clearing all session data
+session.removeAll();
+
+// Check if using persistent storage
+if (session.isPersistent) {
+  console.log('Using real sessionStorage');
+} else {
+  console.log('Using memory fallback (server environment)');
+}
+```
+
+### Cache
+
+In-memory cache for temporary data storage:
+
+```js
+// Setting cache data
+cache.set('tempData', { computed: true, value: 42 });
+
+// Getting cache data
+const cached = cache.get('tempData');
+
+// Checking cache size
+const cacheSize = cache.size();
+
+// Removing cache data
+cache.remove('tempData');
+
+// Clearing all cache data
+cache.removeAll();
+```
+
+**Note:** Cache data is stored in memory and will be lost on page refresh.
+
+### idb
+
+Permanent storage using browser database:
+
+#### Create database
+
+```js
+idb.db.create("Database");
+```
+
+#### Set data into table
+
+```js
+idb.data.set("Database","table", { id: 1, data:{...} } );
+```
+
+#### Get data from table
+
+> [in development]
+
+```js
+idb.data.get("Database","table", 1 );
+```
+
+#### Delete database / table
+
+> [in development]
+
+```js
+idb.db.delete("Database") // Remove DB
+idb.table.delete("Database","table") // Remove only "table"
+```
+
+### DevTools
+
+Browser console debugging tools for inspecting state, store, session, cache:
+
+```javascript
+// Inspect all state modules
+memorio.devtools.inspect();
+
+// Get statistics
+memorio.devtools.stats();
+
+// Clear specific module
+memorio.devtools.clear('state');
+
+// Clear all modules
+memorio.devtools.clearAll();
+
+// Watch a path for changes
+memorio.devtools.watch('state', 'user.name');
+
+// Export all data as JSON
+memorio.devtools.exportData();
+
+// Import data from JSON
+memorio.devtools.importData(jsonString);
+
+// Get help
+memorio.devtools.help();
+
+// Console shortcuts (available in browser console)
+$state  // globalThis.state
+$store  // globalThis.store
+$session // globalThis.session
+$cache  // globalThis.cache
+```
+
+### Logger
+
+Logging middleware for tracking all state changes:
+
+```javascript
+// Configure logger
+memorio.logger.configure({ enabled: true, logToConsole: true });
+
+// Enable/disable logging
+memorio.logger.enable();
+memorio.logger.disable();
+
+// Get log history
+memorio.logger.getHistory();
+
+// Get statistics
+memorio.logger.getStats();
+
+// Clear history
+memorio.logger.clearHistory();
+
+// Export logs as JSON
+memorio.logger.exportLogs();
+```
+
+## Testing
+
+All test suites are passing:
+
+- Basic functionality tests
+- State management tests
+- Store operations tests
+- Cache operations tests
+- Observer pattern tests
+- useObserver pattern tests
+- DevTools tests
+- Logger tests
+
+Total: 71 tests passed across 8 test suites
+
+## Security
+
+Security scans and reports are available at:
+
+- [Socket.dev](https://socket.dev/npm/package/memorio)
+- [Snyk.io](https://security.snyk.io/package/npm/memorio)
+
+## License
+
+MIT License
+
+Copyright (c) [Dario Passariello](https://dario.passariello.ca/)
+
+---
+
+## Cross-Platform Support
+
+Memorio is designed to work across multiple JavaScript environments:
+
+### Platform Compatibility
+
+| Feature | Browser | Node.js | Deno | Edge Workers |
+|---------|---------|---------|------|---------------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `observer` | ✅ | ✅ | ✅ | ✅ |
+| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
+| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
+| `idb` | ✅ | ❌ | ❌ | ⚠️ |
+| `devtools` | ✅ | ❌ | ❌ | ⚠️ |
+| `logger` | ✅ | ✅ | ✅ | ✅ |
+
+- ✅ Full support
+- ⚠️ Partial support (fallback to in-memory)
+- ❌ Not available
+
+### Session Isolation
+
+Memorio provides automatic session isolation to prevent state leakage between different requests or contexts:
+
+- **Unique Session IDs**: Each import gets a unique session identifier
+- **Namespaced Storage**: `store` and `session` keys are prefixed with session ID
+- **State Isolation**: `state` is isolated per-instance
+
+This ensures that in server-side environments (Node.js/Deno), different requests don't share state data.
+
+### Best Practices
+
+1. **For Client-Side**: Use all features freely - store, session, idb work with real browser storage
+2. **For Server-Side**: Use `state` and `cache` for in-memory data; store/session fall back to memory
+3. **For Edge Workers**: Same as browser; localStorage/sessionStorage available
+
+### Checking Platform
+
+```javascript
+import { isBrowser, isNode, isDeno, getCapabilities } from 'memorio';
+
+console.log('Browser:', isBrowser());      // true in browser
+console.log('Node.js:', isNode());          // true in Node.js
+console.log('Deno:', isDeno());             // true in Deno
+
+const caps = getCapabilities();
+console.log('Platform:', caps.platform);    // 'browser' | 'node' | 'deno' | 'edge'
+console.log('Persistent:', store.isPersistent); // true if using real storage
+```