memorio 4.6.9 → 4.7.1

package/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: passariello
+patreon: passariello
+ko_fi: passariello
+liberapay: passariello
+issuehunt: passariello
+custom:
+ [
+  "https://dario.passariello.ca",
+  "https://www.indiegogo.com/individuals/28513718",
+ ]

package/README.md

@@ -1,6 +1,6 @@
 # 🧠 memorio
 
-![image](https://raw.githubusercontent.com/passariello/container/refs/heads/main/memorio/banner.svg)
+![banner](https://raw.githubusercontent.com/passariello/container/refs/heads/main/memorio/banner.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)
@@ -13,197 +13,141 @@
 ![Tests](https://img.shields.io/badge/tests-101%20passed-green)
 ![License](https://img.shields.io/badge/License-MIT-gray)
 
-**State + Observer + Store + IDB. One import. Zero config.**
+### One import. Global state, persistence, and a IndexedDB layer — done.
 
-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.
+```javascript
+import 'memorio'
 
----
+state.user = { name: 'Sara' }   // reactive, everywhere, instantly
+```
 
-## ✨ Why memorio?
+No provider tree. No reducers. No actions to dispatch before you can change a number. If you've ever set up a global store for an app that just needed *"a value, shared, that updates the UI when it changes,"* memorio is the toolkit for that thirty-second job — and it keeps growing with you: session storage, a cache, typed IndexedDB tables, an observer system, a React hook, devtools, and a change logger, all sharing one mental model.
 
-| Feature | 🔥 memorio | Redux | Zustand |
-|---|---|---|---|
-| **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 |
+---
+
+## Table of Contents
 
-Zero dependencies. Lightweight. One import.
+1. [Is this for you?](#is-this-for-you)
+2. [Installation](#installation)
+3. [Quick Start](#quick-start)
+4. [API Reference](#api-reference)
+5. [Cross-Platform Behavior](#cross-platform-behavior)
+6. [Context Isolation (multi-tenant)](#context-isolation-multi-tenant)
+7. [Security](#security)
+8. [License](#license)
 
 ---
 
-## 🚀 Features
-
-| | |
-|---|---|
-| **`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 |
-| **Context isolation** | Per-request / multi-tenant namespace |
-| **Platform detection** | `isBrowser`, `isNode`, `isDeno`, `isEdge` |
-
-No Zustand. No Redux. No provider boilerplate.
-**Import → assign → done.**
+## Is this for you?
+
+memorio is built for speed of thought: you think "I need this value everywhere," you write one line, it works. That's the entire pitch — and it's a real one, not a rewritten complaint about how much Redux boilerplate you've had to write.
+
+**Reach for memorio when:**
+- You want state that's simply *there* — no store setup, no provider wrapping your app.
+- You want `localStorage`, `sessionStorage`, and `IndexedDB` behind one consistent API instead of learning three.
+- You're prototyping, building an internal tool, or shipping something small-to-medium where iteration speed matters more than architectural ceremony.
+
+**Reach for something else when:**
+- You need every state path statically type-checked against every observer — memorio's `state.foo.bar` and `observer('state.foo.bar', ...)` are connected by a string, not by the compiler, so a rename won't be caught for you.
+- You need Redux-style middleware, action logs, or time-travel debugging as a hard requirement for a large team — those tools exist because that discipline solves real problems at scale, not because their authors enjoy boilerplate.
+- Your isolation requirements are a security boundary, not a convenience — see [Context Isolation](#context-isolation-multi-tenant) before you rely on it for that.
+
+Pick the right tool. memorio is at its best when the answer to "how much state architecture do I need here?" is genuinely "not much."
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
-# npm
 npm i memorio
+# pnpm add memorio
+# yarn add memorio
 
-# pnpm
-pnpm add memorio
-
-# yarn
-yarn add memorio
-
-# React peer dep (optional, React >= 16.8)
+# Optional — only if you use the React hook
 npm i react react-dom
 ```
 
 ---
 
-## 🎯 Quick Start
+## Quick Start
 
-### Global style (original)
+### Global style — the whole point of memorio
 
 ```typescript
-// import 'memorio' once at your app entry point
-import 'memorio'
+import 'memorio' // once, at your entry point
 
-// state is now available everywhere
 state.user = { name: 'Sara', role: 'admin' }
 state.counter++
-state.settings = { theme: 'dark', lang: 'it' }
 
-// React - automatic dependency discovery
 useObserver(
-  () => { console.debug('user changed:', state.user) },
+  () => console.debug('user changed:', state.user),
   [state.user]
 )
-
-// Vanilla JS - event system
-memorio.dispatch.listen('state.user', (event) => {
-  console.debug('user changed:', event.detail)
-})
 ```
 
-### Classic `import` style (new)
-
-Every module is also a named export. Same instances, explicit dependencies.
+### Named imports — same instances, explicit about it
 
 ```typescript
-// ESM
-import {
-  state,
-  store,
-  session,
-  cache,
-  idb,
-  observer,
-  useObserver,
-  dispatch,
-  memorio
-} from 'memorio'
+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.
+Two styles, one engine underneath — use whichever reads better in your codebase.
 
 ---
 
-## 📚 API Reference
-
-### `state` — Reactive volatile state
+## API Reference
 
-Global, Proxy-based, reactive. Access anywhere.
+### `state` — reactive, volatile, Proxy-based
 
 ```javascript
-// Set
 state.user = { name: 'Sara', role: 'admin' }
-state.items = [1, 2, 3]
-
-// Get
-const name = state.user.name    // 'Sara'
-
-// List all keys
-console.debug(state.list)         // ['user', 'items']
+const name = state.user.name
 
-// Remove one key
+state.list          // ['user', 'items', ...]
 state.remove('items')
-
-// Clear all
 state.removeAll()
 
-// Lock/unlock (prevents modifications)
+// Freeze a slice of state when you need to stop guessing who mutated it
 state.config = { maxUsers: 100 }
 state.config.lock()
-state.config.maxUsers = 200 // Error: state 'config' is locked
+state.config.maxUsers = 200   // throws: state 'config' is locked
 state.config.unlock()
 ```
 
-### `store` — Survives refresh
+### `store` — the value that survives a refresh
 
 ```javascript
 store.set('preferences', { theme: 'dark' })
-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
+store.get('preferences')      // { theme: 'dark' } or null
+store.isPersistent            // true when backed by real localStorage
 ```
 
-### `session` — Dies with tab
+### `session` — lives as long as the tab does
 
 ```javascript
 session.set('token', 'user-abc-123')
-const token = session.get('token')         // 'user-abc-123' or null
-session.removeAll()
+session.get('token')
 ```
 
-### `cache` — In-memory, disappears on refresh
+### `cache` — the fastest thing you own, gone on refresh
 
 ```javascript
 cache.set('temp', computeExpensiveResult())
-const result = cache.get('temp')           // undefined or the value
-cache.clear()                              // empty it all
+cache.get('temp')
 ```
 
-### `idb` — Structured & typed
+### `idb` — typed, async, structured tables without the ceremony
 
 ```javascript
 await idb.db.create('my-db')
@@ -212,7 +156,9 @@ await idb.data.set('my-db', 'users', { id: 1, name: 'Sara' })
 const user = await idb.data.get('my-db', 'users', 1)
 ```
 
-### `observer` — Object watcher (legacy)
+> IndexedDB is a browser-only primitive — see [Cross-Platform Behavior](#cross-platform-behavior) for what happens off the browser.
+
+### `observer` / `useObserver` — watch a path, react to it
 
 ```javascript
 observer('state.user', (newVal, oldVal) => {
@@ -220,133 +166,94 @@ observer('state.user', (newVal, oldVal) => {
 })
 ```
 
-### `useObserver` — React observer hook
+> Keys here are plain strings, not statically checked against `state`'s shape. Keep the observer near the code that shapes that state, and grep before you rename.
 
-```jsx
-import { useObserver, state } from 'memorio'
-
-function Counter() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-
-  useObserver(forceUpdate, [state.counter])
-
-  return <div>Count: {state.counter}</div>
-}
-```
-
-### `dispatch` — Event system
+### `dispatch` — the event bus underneath it all
 
 ```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')
+memorio.dispatch.listen('state.user', (event) => console.debug(event.detail))
+memorio.dispatch.set('state.user', { detail: { name: 'Sara' } })
 ```
 
-### `devtools` — Inspect everything
+### `devtools` — see everything, instantly
 
 ```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 -> globalThis.state
+memorio.devtools.inspect()
+memorio.devtools.stats()
+memorio.devtools.exportData()
 ```
 
-> 💡 **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.
+Pairs with [dphelper-manager](https://chrome.google.com/webstore/detail/dphelper-manager-dev-tool/oppppldaoknfddeikfloonnialijngbk) for visual, time-travel inspection of your global state straight from devtools.
 
-### `logger` — Track every change
+### `logger` — a black box for every change
 
 ```javascript
 memorio.logger.configure({ enabled: true, logToConsole: true })
-memorio.logger.getHistory()   // [{ timestamp, module, action, path, value }, ...]
-memorio.logger.getStats()     // { total, state, set, get, ... }
-memorio.logger.exportLogs()   // JSON string of all history
+memorio.logger.getHistory()
 ```
 
+> It logs *everything* written to `state`/`store`/`session` — including anything sensitive you put there. Great for debugging, but don't leave it on unconditionally in production if secrets or PII pass through your state. See [Security](#security).
+
 ---
 
-## 🌍 Platform detection
+## Cross-Platform Behavior
+
+memorio runs everywhere JavaScript does — but "everywhere" means different guarantees in different places, and we'd rather tell you now than have you find out at 2am:
+
+| API | Browser | Node.js | Deno | Edge / Workers |
+|---|---|---|---|---|
+| `state` | Proxy in memory | Proxy in memory | Proxy in memory | Proxy in memory |
+| `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
+| `cache` | ✅ in memory | ✅ in memory | ✅ in memory | ✅ in memory |
+| `store` | `localStorage` | `Map` fallback — **not durable across restarts** | `Map` fallback — not durable | `localStorage` where available, else `Map` |
+| `session` | `sessionStorage` | `Map` fallback — not durable | `Map` fallback — not durable | `sessionStorage` where available, else `Map` |
+| `idb` | ✅ `IndexedDB` | ❌ not available | ❌ not available | ⚠️ check `getCapabilities()` |
+| `devtools` | ✅ | ❌ | ❌ | ⚠️ |
+
+Same API top to bottom — that's the promise. But if your server code leans on `store.get(...)` surviving a redeploy, know that on Node/Deno it won't; the fallback is an in-memory cache with the same shape, not durable storage.
 
 ```javascript
-memorio.isBrowser()       // true in Chrome, Firefox, Safari
-memorio.isNode()          // true in Node.js
-memorio.isDeno()          // true in Deno
-memorio.isEdge()          // true in Cloudflare Workers, Vercel Edge
+memorio.isBrowser()
+memorio.isNode()
+memorio.isDeno()
+memorio.isEdge()
 
-const caps = memorio.getCapabilities()
+memorio.getCapabilities()
 // { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, ... }
 ```
 
-Named exports work too:
-
-```typescript
-import { isBrowser, isNode, getCapabilities } from 'memorio'
-```
+Check `getCapabilities()` before leaning on `idb` or persistent `store`/`session` in code that might run on more than one platform.
 
 ---
 
-## 🏢 Context isolation (multi-tenant)
+## 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')
-
-// Context is completely isolated from global state
-console.debug(state.user) // undefined
 
-// Manage contexts
-memorio.listContexts()    // ['tenant-123']
-memorio.deleteContext('tenant-123')
+console.debug(state.user) // undefined — separate namespace
 ```
 
-Named exports:
-
-```typescript
-import { createContext, listContexts, deleteContext, isolate } from 'memorio'
-```
+Handy for keeping per-tenant or per-request state from colliding in the same process. Under the hood it's a key prefix (`tenant-123-key`) inside the same storage — a naming convention, not a hard memory boundary. Great for a browser tab; if you're running this in a shared Node.js process or an edge isolate that might be reused across requests, make sure tenant IDs can't collide or be forged, and don't treat this as your only isolation layer if the stakes are real.
 
 ---
 
-## 🖥️ Cross-Platform
+## Security
 
-Memorio runs in every JavaScript environment, with automatic fallbacks.
-
-| Tool | Browser | Node.js | Deno | Edge / Workers |
-|---|---|---|---|---|
-| `state` | ✅ | ✅ | ✅ | ✅ |
-| `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
-| `cache` | ✅ | ✅ | ✅ | ✅ |
-| `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.
-
----
+- Zero production dependencies.
+- No `eval`, no dynamic code execution, no bundled telemetry.
+- Session IDs generated via `crypto.randomUUID`.
+- Inputs validated, keys sanitized, errors caught at module boundaries.
 
-## 🔒 Security
+memorio does **not** encrypt what you put into `store`, `session`, or `idb` — they're thin, fast wrappers over `localStorage`/`sessionStorage`/`IndexedDB`, which store data in the clear on the user's device. Bring your own encryption layer for tokens, secrets, or regulated personal data.
 
-- Zero production dependencies — no supply chain surprises
-- NIST & NSA aligned — enterprise-grade security standards
-- No `eval`, no obfuscation, no hardcoded secrets
-- All inputs validated, keys sanitized, errors caught
-- Secure random session IDs via `crypto.randomUUID`
+We build with recognized engineering guidance (NIST SP 800-53 practices) as an input to how we write code — that's a design discipline, not a compliance certificate, and no third-party audit has been performed. Found an issue? Report it privately — see `SECURITY.md` — rather than opening a public issue.
 
 ---
 
-## 📄 License
+## License
 
 MIT © [Dario Passariello](https://dario.passariello.ca)