memorio 4.1.0 → 4.1.5

package/index.cjs

@@ -1,5 +1,3 @@
-"use strict";
-
 var e = Object.getOwnPropertyNames, t = (t, o) => function() {
     return t && (o = (0, t[e(t)[0]])(t = 0)), o;
 }, o = {}, r = t({
@@ -323,7 +321,7 @@ Object.defineProperty(globalThis, "memorio", {
 }), Object.defineProperty(memorio, "version", {
     writable: !1,
     enumerable: !1,
-    value: "4.1.0"
+    value: "4.1.5"
 }), Object.defineProperty(memorio, "debug", {
     writable: !0,
     enumerable: !1,
@@ -392,7 +390,10 @@ Object.defineProperty(memorio, "_sessionId", {
         },
         listen: (e, t = null, o = !1) => {
             globalThis.observer?.list?.[e]?.length > 0 && globalThis.observer?.remove?.(e);
-            const r = t ? e => setTimeout(() => t(e), 1) : void 0;
+            const r = t ? e => {
+                const o = e;
+                return globalThis.queueMicrotask ? globalThis.queueMicrotask(() => t(o)) : Promise.resolve().then(() => t(o));
+            } : void 0;
             r && globalThis.addEventListener(e, r), r && (globalThis.events[e] = r);
         },
         remove: e => {
@@ -621,7 +622,7 @@ globalThis.observer = (e, t = null, o = !0) => {
 
 var W = x(), R = new Map, U = null !== W, K = "memorio_store_";
 
-function F(e) {
+function q(e) {
     return e && "string" == typeof e ? e.length > 512 ? (memorio.message("Key too long (max 512 characters)"), 
     "") : /^[a-zA-Z0-9_.-]+$/.test(e) ? K + e : (memorio.message("Key contains invalid characters (only a-z, A-Z, 0-9, _, ., - allowed)"), 
     "") : "";
@@ -635,7 +636,7 @@ Object.defineProperty(globalThis, "store", {
     get: {
         value: e => {
             if (!e) return;
-            const t = F(e);
+            const t = q(e);
             try {
                 if (U) {
                     const e = W.getItem(t);
@@ -654,7 +655,7 @@ Object.defineProperty(globalThis, "store", {
     set: {
         value: (e, t) => {
             if (!e) return;
-            const o = F(e);
+            const o = q(e);
             try {
                 if (U) {
                     if (null == t) W.setItem(o, JSON.stringify(null)); else if ("object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t) W.setItem(o, JSON.stringify(t)); else if ("function" == typeof t) return void memorio.message("Storing functions is not secure and is blocked for safety.");
@@ -668,7 +669,7 @@ Object.defineProperty(globalThis, "store", {
     remove: {
         value: e => {
             if (!e) return;
-            const t = F(e);
+            const t = q(e);
             try {
                 if (U) {
                     if (W.getItem(t)) return W.removeItem(t), !0;
@@ -749,7 +750,7 @@ Object.defineProperty(globalThis, "store", {
     }
 }), Object.freeze(store);
 
-var q = D(), L = new Map, H = null !== q, V = "memorio_session_";
+var F = D(), L = new Map, H = null !== F, V = "memorio_session_";
 
 function Y(e) {
     return e && "string" == typeof e ? e.length > 512 ? (memorio.message("Key too long (max 512 characters)"), 
@@ -768,7 +769,7 @@ Object.defineProperty(globalThis, "session", {
             const t = Y(e);
             try {
                 if (H) {
-                    const e = q.getItem(t);
+                    const e = F.getItem(t);
                     return e ? JSON.parse(e) : e;
                 }
                 {
@@ -785,7 +786,7 @@ Object.defineProperty(globalThis, "session", {
             if (!e) return;
             const o = Y(e);
             try {
-                H ? null == t ? q.setItem(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? q.setItem(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.") : null == t ? L.set(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? L.set(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.");
+                H ? null == t ? F.setItem(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? F.setItem(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.") : null == t ? L.set(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? L.set(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.");
             } catch (t) {
                 memorio.message(`Error setting session item '${e}': ${t}`);
             }
@@ -797,7 +798,7 @@ Object.defineProperty(globalThis, "session", {
             const t = Y(e);
             try {
                 if (H) {
-                    if (q.getItem(t)) return q.removeItem(t), !0;
+                    if (F.getItem(t)) return F.removeItem(t), !0;
                 } else if (L.has(t)) return L.delete(t), !0;
             } catch (t) {
                 memorio.message(`Error removing session item '${e}': ${t}`);
@@ -811,11 +812,11 @@ Object.defineProperty(globalThis, "session", {
         value: () => {
             if (H) {
                 const e = [];
-                for (let t = 0; t < q.length; t++) {
-                    const o = q.key(t);
+                for (let t = 0; t < F.length; t++) {
+                    const o = F.key(t);
                     o?.startsWith(V) && e.push(o);
                 }
-                e.forEach(e => q.removeItem(e));
+                e.forEach(e => F.removeItem(e));
             } else L.clear();
             return !0;
         }
@@ -829,9 +830,9 @@ Object.defineProperty(globalThis, "session", {
     size: {
         value: () => {
             let e = 0;
-            return H ? Object.keys(q).forEach(t => {
+            return H ? Object.keys(F).forEach(t => {
                 if (t.startsWith(V)) {
-                    const o = q.getItem(t);
+                    const o = F.getItem(t);
                     o && (e += o.length);
                 }
             }) : L.forEach(t => {
@@ -846,10 +847,10 @@ Object.defineProperty(globalThis, "session", {
         value: () => {
             const e = {};
             try {
-                if (H) for (let t = 0; t < q.length; t++) {
-                    const o = q.key(t);
+                if (H) for (let t = 0; t < F.length; t++) {
+                    const o = F.key(t);
                     if (o?.startsWith(V)) {
-                        const t = o.replace(V, ""), r = q.getItem(o);
+                        const t = o.replace(V, ""), r = F.getItem(o);
                         if (null !== r) try {
                             e[t] = JSON.parse(r);
                         } catch {

package/index.js

@@ -321,7 +321,7 @@ Object.defineProperty(globalThis, "memorio", {
 }), Object.defineProperty(memorio, "version", {
     writable: !1,
     enumerable: !1,
-    value: "4.1.0"
+    value: "4.1.5"
 }), Object.defineProperty(memorio, "debug", {
     writable: !0,
     enumerable: !1,
@@ -390,7 +390,10 @@ Object.defineProperty(memorio, "_sessionId", {
         },
         listen: (e, t = null, o = !1) => {
             globalThis.observer?.list?.[e]?.length > 0 && globalThis.observer?.remove?.(e);
-            const r = t ? e => setTimeout(() => t(e), 1) : void 0;
+            const r = t ? e => {
+                const o = e;
+                return globalThis.queueMicrotask ? globalThis.queueMicrotask(() => t(o)) : Promise.resolve().then(() => t(o));
+            } : void 0;
             r && globalThis.addEventListener(e, r), r && (globalThis.events[e] = r);
         },
         remove: e => {
@@ -619,7 +622,7 @@ globalThis.observer = (e, t = null, o = !0) => {
 
 var W = x(), R = new Map, U = null !== W, K = "memorio_store_";
 
-function F(e) {
+function q(e) {
     return e && "string" == typeof e ? e.length > 512 ? (memorio.message("Key too long (max 512 characters)"), 
     "") : /^[a-zA-Z0-9_.-]+$/.test(e) ? K + e : (memorio.message("Key contains invalid characters (only a-z, A-Z, 0-9, _, ., - allowed)"), 
     "") : "";
@@ -633,7 +636,7 @@ Object.defineProperty(globalThis, "store", {
     get: {
         value: e => {
             if (!e) return;
-            const t = F(e);
+            const t = q(e);
             try {
                 if (U) {
                     const e = W.getItem(t);
@@ -652,7 +655,7 @@ Object.defineProperty(globalThis, "store", {
     set: {
         value: (e, t) => {
             if (!e) return;
-            const o = F(e);
+            const o = q(e);
             try {
                 if (U) {
                     if (null == t) W.setItem(o, JSON.stringify(null)); else if ("object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t) W.setItem(o, JSON.stringify(t)); else if ("function" == typeof t) return void memorio.message("Storing functions is not secure and is blocked for safety.");
@@ -666,7 +669,7 @@ Object.defineProperty(globalThis, "store", {
     remove: {
         value: e => {
             if (!e) return;
-            const t = F(e);
+            const t = q(e);
             try {
                 if (U) {
                     if (W.getItem(t)) return W.removeItem(t), !0;
@@ -747,7 +750,7 @@ Object.defineProperty(globalThis, "store", {
     }
 }), Object.freeze(store);
 
-var q = D(), L = new Map, H = null !== q, V = "memorio_session_";
+var F = D(), L = new Map, H = null !== F, V = "memorio_session_";
 
 function Y(e) {
     return e && "string" == typeof e ? e.length > 512 ? (memorio.message("Key too long (max 512 characters)"), 
@@ -766,7 +769,7 @@ Object.defineProperty(globalThis, "session", {
             const t = Y(e);
             try {
                 if (H) {
-                    const e = q.getItem(t);
+                    const e = F.getItem(t);
                     return e ? JSON.parse(e) : e;
                 }
                 {
@@ -783,7 +786,7 @@ Object.defineProperty(globalThis, "session", {
             if (!e) return;
             const o = Y(e);
             try {
-                H ? null == t ? q.setItem(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? q.setItem(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.") : null == t ? L.set(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? L.set(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.");
+                H ? null == t ? F.setItem(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? F.setItem(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.") : null == t ? L.set(o, JSON.stringify(null)) : "object" == typeof t || "number" == typeof t || "boolean" == typeof t || "string" == typeof t ? L.set(o, JSON.stringify(t)) : "function" == typeof t && memorio.message("It's not secure to session functions.");
             } catch (t) {
                 memorio.message(`Error setting session item '${e}': ${t}`);
             }
@@ -795,7 +798,7 @@ Object.defineProperty(globalThis, "session", {
             const t = Y(e);
             try {
                 if (H) {
-                    if (q.getItem(t)) return q.removeItem(t), !0;
+                    if (F.getItem(t)) return F.removeItem(t), !0;
                 } else if (L.has(t)) return L.delete(t), !0;
             } catch (t) {
                 memorio.message(`Error removing session item '${e}': ${t}`);
@@ -809,11 +812,11 @@ Object.defineProperty(globalThis, "session", {
         value: () => {
             if (H) {
                 const e = [];
-                for (let t = 0; t < q.length; t++) {
-                    const o = q.key(t);
+                for (let t = 0; t < F.length; t++) {
+                    const o = F.key(t);
                     o?.startsWith(V) && e.push(o);
                 }
-                e.forEach(e => q.removeItem(e));
+                e.forEach(e => F.removeItem(e));
             } else L.clear();
             return !0;
         }
@@ -827,9 +830,9 @@ Object.defineProperty(globalThis, "session", {
     size: {
         value: () => {
             let e = 0;
-            return H ? Object.keys(q).forEach(t => {
+            return H ? Object.keys(F).forEach(t => {
                 if (t.startsWith(V)) {
-                    const o = q.getItem(t);
+                    const o = F.getItem(t);
                     o && (e += o.length);
                 }
             }) : L.forEach(t => {
@@ -844,10 +847,10 @@ Object.defineProperty(globalThis, "session", {
         value: () => {
             const e = {};
             try {
-                if (H) for (let t = 0; t < q.length; t++) {
-                    const o = q.key(t);
+                if (H) for (let t = 0; t < F.length; t++) {
+                    const o = F.key(t);
                     if (o?.startsWith(V)) {
-                        const t = o.replace(V, ""), r = q.getItem(o);
+                        const t = o.replace(V, ""), r = F.getItem(o);
                         if (null !== r) try {
                             e[t] = JSON.parse(r);
                         } catch {

package/llms.txt

@@ -0,0 +1,405 @@
+# Memorio - LLM Documentation
+
+## Overview
+
+**Memorio** is a cross-platform state management library that provides reactive state, persistence, and observation capabilities with zero dependencies. It works in Node.js, Deno, browsers, and edge environments.
+
+```
+npm i memorio
+```
+
+## Core Concepts
+
+Memorio provides 6 storage modules plus utilities:
+
+| Module | Purpose | Persistence |
+|--------|---------|-------------|
+| `state` | Reactive, volatile state | In-memory (resets on refresh) |
+| `store` | localStorage persistence | Survives browser refresh |
+| `session` | sessionStorage | Dies with browser tab |
+| `cache` | In-memory cache | Fastest read, no persistence |
+| `idb` | IndexedDB | Structured, async, persistent (browser-only) |
+| `observer` | Object watcher | Legacy, deprecated |
+| `useObserver` | React hook | Auto-discovery of state paths |
+
+## Quick Start
+
+```javascript
+import 'memorio'
+
+// Set reactive state
+state.user = { name: 'Sara', role: 'admin' }
+state.counter = 0
+
+// Observe changes (React hook)
+useObserver(
+  () => { console.log('counter:', state.counter) },
+  [state.counter]
+)
+```
+
+## API Reference
+
+### `state` — Reactive State
+
+Global, Proxy-based, reactive state management.
+
+```javascript
+// Set values
+state.user = { name: 'Sara', role: 'admin' }
+state.items = [1, 2, 3]
+state.counter = 0
+
+// Get values
+const name = state.user.name    // 'Sara'
+
+// List all keys
+console.log(state.list)         // ['user', 'items', 'counter']
+
+// Remove one key
+state.remove('items')
+
+// Clear all
+state.removeAll()
+
+// Lock/unlock for frozen objects
+state.lock()    // freeze everything
+state.unlock()  // unfreeze
+```
+
+**Features:**
+- Automatic path tracking via `__path` property
+- Nested proxy support
+- Lock/unlock per-key or globally
+- Auto-dispatches events on changes
+
+### `store` — localStorage Persistence
+
+Persistent storage that survives browser refresh.
+
+```javascript
+// Set
+store.set('preferences', { theme: 'dark' })
+
+// Get
+const prefs = store.get('preferences')  // { theme: 'dark' } or null
+
+// List all keys
+store.list()  // { preferences: { theme: 'dark' } }
+
+// Remove
+store.remove('preferences')
+
+// Delete (alias for remove)
+store.delete('preferences')
+
+// Clear all memorio items
+store.removeAll()
+
+// Clear all (alias for removeAll)
+store.clearAll()
+
+// Check size
+console.log(store.size(), 'chars stored')
+
+// Check if persistent (real localStorage vs memory fallback)
+console.log(store.isPersistent)  // true → real localStorage
+
+// Estimate quota usage (returns [0, 0] for localStorage)
+await store.quota()  // [usage, quota] in KB
+```
+
+### `session` — sessionStorage
+
+Storage that dies when browser tab closes.
+
+```javascript
+// Set
+session.set('token', 'user-abc-123')
+
+// Get
+const token = session.get('token')  // 'user-abc-123' or null
+
+// List all keys
+session.list()  // { token: 'user-abc-123' }
+
+// Remove
+session.remove('token')
+
+// Delete (alias for remove)
+session.delete('token')
+
+// Clear all
+session.removeAll()
+
+// Clear all (alias for removeAll)
+session.clearAll()
+
+// Check size
+console.log(session.size(), 'chars stored')
+
+// Check if persistent
+console.log(session.isPersistent)
+```
+
+### `cache` — In-Memory Cache
+
+Fastest possible read, data lost on refresh.
+
+```javascript
+// Set
+cache.set('temp', computeExpensiveResult())
+
+// Get
+const result = cache.get('temp')  // undefined or the value
+
+// List all keys
+cache.list()  // { temp: <value> }
+
+// Remove
+cache.remove('temp')
+
+// Clear all
+cache.clear()
+
+// Remove all (alias for clear)
+cache.removeAll()
+
+// Direct access (also works)
+cache['myKey'] = value
+const value = cache['myKey']
+delete cache['myKey']
+```
+
+### `idb` — IndexedDB
+
+Structured, persistent, async database (browser-only).
+
+```javascript
+// Create database
+await idb.db.create('my-db', 1)  // version defaults to 1
+
+// Create table (object store)
+await idb.table.create('my-db', 'users')
+
+// Set data
+await idb.data.set('my-db', 'users', { id: 1, name: 'Sara' })
+
+// Get data by key
+const user = await idb.data.get('my-db', 'users', 1)
+
+// Delete data
+await idb.data.delete('my-db', 'users', 1)
+
+// List databases
+const dbs = await idb.db.list()
+
+// Check if database exists
+const exists = await idb.db.exist('my-db')
+
+// Delete database
+await idb.db.delete('my-db')
+
+// Get database size
+const size = await idb.db.size('my-db')
+
+// Get table size
+const tableSize = await idb.table.size('my-db', 'users')
+
+// Check support
+idb.db.support()  // true if IndexedDB available
+
+// Check quota
+const [usage, quota] = await idb.db.quota()
+```
+
+**Note:** In Node.js/Deno, `idb` is disabled with a warning. Use `store` or `session` instead.
+
+### `observer` — Object Watcher (DEPRECATED)
+
+Legacy observer API. Use `useObserver` instead.
+
+```javascript
+// Listen to state changes
+observer('state.user', (newVal, oldVal) => {
+  console.log('user changed:', newVal, oldVal)
+})
+
+// Toggle listening (no callback)
+observer('state.counter')
+
+// Remove observer
+observer.remove('state.user')
+
+// List all observers
+console.log(observer.list)
+
+// Remove all observers
+observer.removeAll()
+```
+
+### `useObserver` — React Hook
+
+Primary way to observe state changes in React components.
+
+```jsx
+import 'memorio'
+import { useReducer } from 'react'
+
+function Counter() {
+  const [, forceUpdate] = useReducer(x => x + 1, 0)
+
+  // Auto-discovery mode (no deps)
+  useObserver(() => {
+    console.log('counter:', state.counter)
+  }, state.counter)
+
+  // Explicit deps mode
+  useObserver(
+    () => { console.log('user:', state.user) },
+    [state.user]
+  )
+
+  return <div>Count: {state.counter}</div>
+}
+```
+
+**Features:**
+- Auto-discovery of state paths during render
+- Returns cleanup function to stop monitoring
+- Supports both Proxy objects and string paths
+
+### `devtools` — Inspection Tools
+
+Inspect all memorio data in console.
+
+```javascript
+// Pretty-print state, store, session, cache
+memorio.devtools.inspect()
+
+// Get stats
+memorio.devtools.stats()  // { stateKeys, storeKeys, sessionKeys, ... }
+
+// Clear specific module
+memorio.devtools.clear('state')
+
+// Clear all modules
+memorio.devtools.clearAll()
+
+// Export all data as JSON
+memorio.devtools.exportData()
+
+// Import data from JSON
+memorio.devtools.importData(jsonString)
+
+// Show help
+memorio.devtools.help()
+
+// Console shortcuts
+$state    // same as globalThis.state
+$store    // same as globalThis.store
+$session  // same as globalThis.session
+$cache    // same as globalThis.cache
+```
+
+### `logger` — Change Tracking
+
+Track every state change with timestamps.
+
+```javascript
+// Configure logger
+memorio.logger.configure({ 
+  enabled: true, 
+  logToConsole: true,
+  modules: ['state', 'store', 'session', 'cache', 'idb']
+})
+
+// Get history
+memorio.logger.getHistory()  // [{ timestamp, module, action, path, value }, ...]
+
+// Get stats
+memorio.logger.getStats()    // { total, state, store, session, cache, idb, set, get, ... }
+
+// Clear history
+memorio.logger.clearHistory()
+
+// Export logs
+memorio.logger.exportLogs()  // JSON string of all history
+```
+
+## Platform Detection
+
+Access via `memorio.*` after `import 'memorio'`:
+
+```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
+
+const caps = memorio.getCapabilities()
+// { platform: 'browser', hasLocalStorage: true, hasIndexedDB: true, sessionId: 'uuid', ... }
+
+// Create isolated context
+memorio.createContext('tenant-name')
+memorio.listContexts()
+memorio.deleteContext('context-id')
+memorio.isolate('tenant-name')  // alias for createContext
+```
+
+## Cross-Platform Support
+
+| Module | Browser | Node.js | Deno | Edge/Workers |
+|--------|---------|---------|------|--------------|
+| `state` | ✅ | ✅ | ✅ | ✅ |
+| `observer` / `useObserver` | ✅ | ✅ | ✅ | ✅ |
+| `cache` | ✅ | ✅ | ✅ | ✅ |
+| `store` | ✅ localStorage | ⚠️ memory | ⚠️ memory | ✅ localStorage |
+| `session` | ✅ sessionStorage | ⚠️ memory | ⚠️ memory | ✅ sessionStorage |
+| `idb` | ✅ IndexedDB | ❌ | ❌ | ⚠️ |
+| `devtools` | ✅ | ❌ | ❌ | ⚠️ |
+
+**Note:** `store` and `session` fall back to in-memory `Map` in Node.js/Deno.
+
+## Session Isolation
+
+Each browser tab and server request gets an isolated namespace automatically via session IDs.
+
+```javascript
+// Create isolated context
+memorio.createContext('tenant-name')
+memorio.listContexts()
+memorio.deleteContext('context-id')
+memorio.isolate('tenant-name')  // alias for createContext
+```
+
+## Security
+
+- Zero production dependencies
+- NIST & NSA aligned security standards
+- No `eval`, no obfuscation, no hardcoded secrets
+- All inputs validated, keys sanitized
+- Secure random session IDs via `crypto.randomUUID`
+
+## License
+
+MIT © Dario Passariello (BigLogic Inc Canada)
+
+## Utilities
+
+### `memorio.dispatch` — Event Dispatch System
+
+Internal event system used by state changes.
+
+```javascript
+// Dispatch a custom event
+memorio.dispatch.set('custom:event', { detail: { data: 'value' } })
+
+// Listen for an event
+memorio.dispatch.listen('custom:event', (e) => {
+  console.log('Event triggered:', e.detail)
+})
+
+// Remove listener
+memorio.dispatch.remove('custom:event')
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorio",
   "codeName": "memorio",
-  "version": "4.1.0",
+  "version": "4.1.5",
   "description": "Memorio, State + Observer, Store and iDB for an easy life - Cross-platform compatible",
   "main": "./index.cjs",
   "browser": "./index.cjs",

package/types/observer.d.ts

@@ -54,7 +54,7 @@ interface _observer {
 
 }
 
-declare var observer: _observer | null
+declare var observer: _observer
 type observer = _observer
 
 // Extend globalThis to include observer