memorio 4.5.3 → 4.6.4

package/README.md

@@ -1,68 +1,67 @@
-# [memorio](https://npmjs.com/package/memorio)
+# 🧠 memorio
 
 ![image](https://raw.githubusercontent.com/passariello/container/refs/heads/main/memorio/banner.svg)
 
-![version](https://img.shields.io/npm/v/memorio.svg)
-![downloads](https://img.shields.io/npm/dm/memorio.svg)
+[![npm version](https://img.shields.io/npm/v/memorio.svg)](https://npmjs.com/package/memorio)
+[![npm downloads](https://img.shields.io/npm/dm/memorio.svg)](https://npmjs.com/package/memorio)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-gray?logo=node.js)](https://nodejs.org)
+![Browser](https://img.shields.io/badge/Browser-Chrome%20/%20Firefox%20/%20Safari-gray?logo=google-chrome)
+![Deno](https://img.shields.io/badge/Deno-compatible-gray?logo=deno)
+![Edge Workers](https://img.shields.io/badge/Edge%20Workers-compatible-gray)
+![TypeScript](https://img.shields.io/badge/TypeScript-native-gray?logo=typescript)
+![React](https://img.shields.io/badge/React-compatible-gray?logo=react)
+![Tests](https://img.shields.io/badge/tests-101%20passed-green)
+![License](https://img.shields.io/badge/License-MIT-gray)
 
-![Snyk](https://img.shields.io/badge/Snyk-gray?logo=Snyk)
-![Socket](https://img.shields.io/badge/Socket-gray?logo=Socket)
+**State + Observer + Store + IDB. One import. Zero config.**
 
-![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
-![Browser](https://img.shields.io/badge/Browser-gray?logo=google-chrome)
-![Deno](https://img.shields.io/badge/Deno-gray?logo=deno)
-![tsup](https://img.shields.io/badge/tsup-gray?logo=esbuild)
+Memorio is a universal, cross-platform state management library for JavaScript and TypeScript. Reactive state, persistent store, session cache, IndexedDB, observer system, React hook, devtools, and logger — all from one import, zero dependencies.
 
-![React](https://img.shields.io/badge/React-gray?logo=React)
-![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
-![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
-![Jquery](https://img.shields.io/badge/jquery-gray?logo=jquery)
-
-![Vitest](https://img.shields.io/badge/Vitest-gray?logo=vitest)
-![OXlint](https://img.shields.io/badge/Oxlint-gray?logo=oxc)
-![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
+---
 
-## Why memorio?
+## ✨ Why memorio?
 
-| | memorio | Redux | Zustand |
+| Feature | 🔥 memorio | Redux | Zustand |
 |---|---|---|---|
-| **Setup** | 1 import | Boilerplate hell | Moderate |
-| **Dependencies** | **Zero** | Many | Few |
-| **TypeScript** | ✅ Native | ✅ | ✅ |
-| **Binary storage** | ✅ Built-in IDB | ❌ Add-on | ❌ |
-| **Observer** | ✅ Built-in | ❌ Add-on | ❌ |
-| **DevTools** | ✅ Built-in + dphelper-manager extension | ❌ Extension | ❌ |
-| **Running on the edge** | ✅ Workers, Deno | ⚠️ Limited | ⚠️ Limited |
-
-If you need a `store` on the server. A `cache` in the edge worker.
-Session isolation in Next.js. IndexedDB in a Service Worker.
-All from one import, zero configuration.
+| **Setup** | ✅ **1 import** | ❌ Boilerplate hell | ⚠️ Moderate |
+| **Dependencies** | ✅ **Zero** | ❌ Many | ⚠️ Few |
+| **TypeScript** | ✅ Native | ✅ Yes | ✅ Yes |
+| **Binary storage** | ✅ Built-in IDB | ❌ Add-on | ❌ Add-on |
+| **Observer** | ✅ Built-in | ❌ Add-on | ❌ Add-on |
+| **DevTools** | ✅ Built-in + dphelper-manager | ⚠️ Extension | ⚠️ Extension |
+| **Edge runtime** | ✅ Workers, Deno | ❌ Limited | ❌ Limited |
+| **Learning curve** | ✅ **5 minutes** | ❌ Hours | ⚠️ 30 min |
+| **Boilerplate** | ✅ **None** | ❌ Tons | ⚠️ Some |
+| **React support** | ✅ `useObserver` hook | ✅ `connect` | ✅ `useSyncExternalStore` |
+| **Context isolation** | ✅ Multi-tenant | ⚠️ Manual | ⚠️ Manual |
+
+Zero dependencies. Lightweight. One import.
 
 ---
 
-## Features
+## 🚀 Features
 
 | | |
 |---|---|
-| **`state`** | Reactive, volatile state — observe with `useObserver` (React) or `dispatch.listen` (vanilla JS) |
-| **`store`** | localStorage persistence — survives refresh |
-| **`session`** | sessionStorage — dies with the tab |
-| **`cache`** | In-memory cache — fastest read possible |
-| **`idb`** | IndexedDB with typed tables — structured, persistent, async |
-| **`observer`** | Object watcher - legacy API for vanilla JS |
-| **`useObserver`** | React hook with auto-discovery — drops in |
-| **`dispatch`** | Event system for vanilla JS — listen, emit, subscribe |
-| **`devtools`** | `memorio.devtools.inspect()` — see everything in console |
+| **`state`** | Reactive, Proxy-based volatile state |
+| **`store`** | localStorage persistence (survives refresh) |
+| **`session`** | sessionStorage (dies with tab) |
+| **`cache`** | In-memory fastest cache |
+| **`idb`** | IndexedDB with typed tables, structured and async |
+| **`observer`** | Legacy object watcher for vanilla JS |
+| **`useObserver`** | React hook with auto-discovery |
+| **`dispatch`** | Event system: listen, emit, subscribe |
+| **`devtools`** | Inspect everything in console |
 | **`logger`** | Auto-log every state change with timestamps |
-| **Session Isolation** | Every browser tab, every request: isolated namespace |
-| **Platform Detection** | `isBrowser`, `isNode`, `isDeno`, `isEdge` |
+| **Context isolation** | Per-request / multi-tenant namespace |
+| **Platform detection** | `isBrowser`, `isNode`, `isDeno`, `isEdge` |
 
 No Zustand. No Redux. No provider boilerplate.
-Just import it and start storing.
+**Import → assign → done.**
 
 ---
 
-## Installation options
+## 📦 Installation
 
 ```bash
 # npm
@@ -74,20 +73,21 @@ pnpm add memorio
 # yarn
 yarn add memorio
 
-# React peer dep (optional, React ≥ 16.8)
+# React peer dep (optional, React >= 16.8)
 npm i react react-dom
 ```
 
-## **Setup**
+---
 
-```typescript
-// IMPORT ONCE AT YOUR APP ENTRY POINT
+## 🎯 Quick Start
 
-import 'memorio'
-```
+### Global style (original)
 
 ```typescript
-// Memory
+// import 'memorio' once at your app entry point
+import 'memorio'
+
+// state is now available everywhere
 state.user = { name: 'Sara', role: 'admin' }
 state.counter++
 state.settings = { theme: 'dark', lang: 'it' }
@@ -100,19 +100,55 @@ useObserver(
 
 // Vanilla JS - event system
 memorio.dispatch.listen('state.user', (event) => {
-  console.debug('user changed:', event.detail);
+  console.debug('user changed:', event.detail)
 })
 ```
 
-That is it.
-No context providers. No `<Store>` wrappers. No action creators.
-Import → assign → done.
+### Classic `import` style (new)
+
+Every module is also a named export. Same instances, explicit dependencies.
+
+```typescript
+// ESM
+import {
+  state,
+  store,
+  session,
+  cache,
+  idb,
+  observer,
+  useObserver,
+  dispatch,
+  memorio
+} from 'memorio'
+
+state.user = { name: 'Sara' }
+store.set('theme', 'dark')
+
+// CJS
+const { state, store, memorio } = require('memorio')
+```
+
+```tsx
+// React with named imports
+import { useObserver, state } from 'memorio'
+
+function Counter() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+
+  useObserver(forceUpdate, [state.counter])
+
+  return <div>Count: {state.counter}</div>
+}
+```
+
+Both styles share the exact same instances. Pick whichever fits your project.
 
 ---
 
-## API Reference
+## 📚 API Reference
 
-### `state` — Volatile reactive state
+### `state` — Reactive volatile state
 
 Global, Proxy-based, reactive. Access anywhere.
 
@@ -130,13 +166,17 @@ console.debug(state.list)         // ['user', 'items']
 // Remove one key
 state.remove('items')
 
-// Clear all — lock/unlock available for frozen objects
+// Clear all
 state.removeAll()
-state.lock()       // freeze everything
-state.unlock()     // unfreeze
+
+// Lock/unlock (prevents modifications)
+state.config = { maxUsers: 100 }
+state.config.lock()
+state.config.maxUsers = 200 // Error: state 'config' is locked
+state.config.unlock()
 ```
 
-### `store` — survives refresh
+### `store` — Survives refresh
 
 ```javascript
 store.set('preferences', { theme: 'dark' })
@@ -144,10 +184,10 @@ const prefs = store.get('preferences')     // { theme: 'dark' } or null
 store.remove('preferences')
 store.removeAll()
 console.debug(store.size(), 'chars stored')
-console.debug(store.isPersistent)         // true → real localStorage
+console.debug(store.isPersistent)         // true -> real localStorage
 ```
 
-### `session` — dies with tab
+### `session` — Dies with tab
 
 ```javascript
 session.set('token', 'user-abc-123')
@@ -163,7 +203,7 @@ const result = cache.get('temp')           // undefined or the value
 cache.clear()                              // empty it all
 ```
 
-### `idb` — structured & typed
+### `idb` — Structured & typed
 
 ```javascript
 await idb.db.create('my-db')
@@ -172,44 +212,56 @@ await idb.data.set('my-db', 'users', { id: 1, name: 'Sara' })
 const user = await idb.data.get('my-db', 'users', 1)
 ```
 
-### `observer` — Object watcher
+### `observer` — Object watcher (legacy)
 
 ```javascript
-globalThis.observer('state.user', (newVal, oldVal) => {
+observer('state.user', (newVal, oldVal) => {
   console.debug('user changed:', newVal, oldVal)
 })
 ```
 
 ### `useObserver` — React observer hook
 
-Available globally after `import 'memorio'`.
-
 ```jsx
-import 'memorio'
+import { useObserver, state } from 'memorio'
 
 function Counter() {
   const [, forceUpdate] = useReducer(x => x + 1, 0)
 
   useObserver(forceUpdate, [state.counter])
-  // State path auto-discovered during render — no manual deps needed
 
   return <div>Count: {state.counter}</div>
 }
 ```
 
-### `devtools` — inspect everything in one call
+### `dispatch` — Event system
+
+```javascript
+// Listen
+memorio.dispatch.listen('state.user', (event) => {
+  console.debug('user changed:', event.detail)
+})
+
+// Emit
+memorio.dispatch.set('state.user', { detail: { name: 'state.user' } })
+
+// Remove
+memorio.dispatch.remove('state.user')
+```
+
+### `devtools` — Inspect everything
 
 ```javascript
 memorio.devtools.inspect()   // pretty-prints state, store, session, cache
 memorio.devtools.stats()     // { stateKeys, storeKeys, sessionKeys, ... }
 memorio.devtools.clear('state')
 memorio.devtools.exportData() // JSON snapshot
-$state  // console shortcut — same as globalThis.state
+$state  // console shortcut -> globalThis.state
 ```
 
-> **Browser Extension Integration:** When used with dphelper-manager browser extension, memorio's global state namespace is automatically detected and visualized through a dedicated DevTools panel, providing time-travel debugging and structural guardrails.
+> 💡 **Browser Extension**: When used with [dphelper-manager](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk), Memorio's global state is automatically detected and visualized with time-travel debugging.
 
-### `logger` — track every change
+### `logger` — Track every change
 
 ```javascript
 memorio.logger.configure({ enabled: true, logToConsole: true })
@@ -218,9 +270,9 @@ memorio.logger.getStats()     // { total, state, set, get, ... }
 memorio.logger.exportLogs()   // JSON string of all history
 ```
 
-### Platform detection
+---
 
-Access via `memorio.*`:
+## 🌍 Platform detection
 
 ```javascript
 memorio.isBrowser()       // true in Chrome, Firefox, Safari
@@ -232,31 +284,42 @@ const caps = memorio.getCapabilities()
 // { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, ... }
 ```
 
-### Context (multi-tenant)
+Named exports work too:
 
-```javascript
-memorio.createContext('tenant-name')
-memorio.listContexts()
-memorio.deleteContext('context-id')
-memorio.isolate('tenant-name')
+```typescript
+import { isBrowser, isNode, getCapabilities } from 'memorio'
 ```
 
 ---
 
-## Browser Extension (Chrome/Edge)
+## 🏢 Context isolation (multi-tenant)
+
+```javascript
+// Create isolated context
+const ctx = memorio.createContext('tenant-123')
+
+// Use context storage (prefix: 'tenant-123-key')
+ctx.state.user = { name: 'Isolated' }
+ctx.store.set('settings', { theme: 'dark' })
+ctx.session.set('token', 'abc123')
 
-![dphelper Banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/dphelper/assets/images/screenshot.png)
+// Context is completely isolated from global state
+console.debug(state.user) // undefined
 
-Manage your `Memorio` on `dphelper Manager Browser Extension*` environment, monitor memory usage, and access documentation directly from your browser.
+// Manage contexts
+memorio.listContexts()    // ['tenant-123']
+memorio.deleteContext('tenant-123')
+```
 
-*Need to install dphelper npm
+Named exports:
 
-- [Download for Chrome](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk)
-- [Download for Edge](https://microsoftedge.microsoft.com/addons/detail/dphelper-manager-dev-to/kphabkbdpaljlfagldhojilhfammepnk)
+```typescript
+import { createContext, listContexts, deleteContext, isolate } from 'memorio'
+```
 
 ---
 
-## Cross-Platform
+## 🖥️ Cross-Platform
 
 Memorio runs in every JavaScript environment, with automatic fallbacks.
 
@@ -265,16 +328,16 @@ Memorio runs in every JavaScript environment, with automatic fallbacks.
 | `state` | ✅ | ✅ | ✅ | ✅ |
 | `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
 | `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | ✅ localStorage | ⚠️ memory | ⚠️ memory | ✅ localStorage |
-| `session` | ✅ sessionStorage | ⚠️ memory | ⚠️ memory | ✅ sessionStorage |
-| `idb` | ✅ IndexedDB | ❌ | ❌ | ⚠️ |
+| `store` | localStorage | memory | memory | localStorage |
+| `session` | sessionStorage | memory | memory | sessionStorage |
+| `idb` | IndexedDB | ❌ | ❌ | ⚠️ |
 | `devtools` | ✅ | ❌ | ❌ | ⚠️ |
 
 > **Why memory fallbacks on the server?** There is no browser. `store` and `session` gracefully fall back to `Map`. You still get the same API. Same `state`, same `cache`, same `useObserver`. No extra config required.
 
 ---
 
-## Security
+## 🔒 Security
 
 - Zero production dependencies — no supply chain surprises
 - NIST & NSA aligned — enterprise-grade security standards
@@ -284,6 +347,6 @@ Memorio runs in every JavaScript environment, with automatic fallbacks.
 
 ---
 
-## License
+## 📄 License
 
 MIT © [Dario Passariello](https://dario.passariello.ca)

package/SUMMARY.md

@@ -18,6 +18,7 @@
 * [Platform & Context Isolation](markdown/PLATFORM.md) - Cross-platform support, session isolation
 * [Security](markdown/SECURITY.md) - Security measures, vulnerability prevention
 * [Changelog](markdown/CHANGELOG.md) - Version history and migration guide
+* [Classic Import](markdown/IMPORT.md) - Named export guide for `import { state } from 'memorio'`
 
 ## Additional Resources