memorio 4.6.8 → 4.7.0

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 |
+| `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.debug('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.debug(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.debug(store.size(), 'chars stored')
+
+// Check if persistent (real localStorage vs memory fallback)
+console.debug(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.debug(session.size(), 'chars stored')
+
+// Check if persistent
+console.debug(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
+
+Legacy observer API. Use `useObserver` instead.
+
+```javascript
+// Listen to state changes
+observer('state.user', (newVal, oldVal) => {
+  console.debug('user changed:', newVal, oldVal)
+})
+
+// Toggle listening (no callback)
+observer('state.counter')
+
+// Remove observer
+observer.remove('state.user')
+
+// List all observers
+console.debug(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.debug('counter:', state.counter)
+  }, state.counter)
+
+  // Explicit deps mode
+  useObserver(
+    () => { console.debug('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.debug('Event triggered:', e.detail)
+})
+
+// Remove listener
+memorio.dispatch.remove('custom:event')
+```

package/markdown/CACHE.md

@@ -0,0 +1,90 @@
+# Cache - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Cache provides in-memory storage with a simple API. Data is lost on page refresh or process restart.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save data
+cache.set('username', 'Mario');
+cache.set('score', 1500);
+
+// Read data
+console.debug(cache.get('username')); // "Mario"
+console.debug(cache.get('score'));    // 1500
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+cache.set('user', { name: 'Luigi', level: 5 });
+const user = cache.get('user');
+console.debug(user.name); // "Luigi"
+
+// Remove single item
+cache.remove('username');
+
+// Clear all cache
+cache.removeAll();
+```
+
+---
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `cache.get(name)` | `name: string` | `any` | Get value from cache |
+| `cache.set(name, value)` | `name: string, value: any` | `void` | Save value to cache |
+| `cache.remove(name)` | `name: string` | `boolean` | Remove single item |
+| `cache.removeAll()` | `none` | `boolean` | Clear all cache |
+
+---
+
+## Storage Comparison
+
+| Feature | Cache | Store | Session | IDB |
+|---------|-------|-------|---------|-----|
+| Platform Support | All (universal) | Browser/Edge | Browser/Edge | Browser only |
+| Lifetime | Until refresh | Forever | Until tab closes | Forever |
+| Capacity | Unlimited | ~5-10 MB | ~5-10 MB | 50+ MB |
+| Use case | Temporary data | User preferences | Auth tokens | Large data |
+
+---
+
+## Platform Support
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| Browser | ✅ Full | In-memory, lost on refresh |
+| Node.js | ✅ Full | In-memory, lost on restart |
+| Deno | ✅ Full | In-memory, lost on restart |
+| Edge Workers | ✅ Full | In-memory, lost on function cold start |
+
+---
+
+## Best Practices
+
+1. Use for temporary data that doesn't need persistence
+2. Great for computed values or API response caching
+3. Data is lost on page refresh - don't use for important data
+4. Clear with `cache.removeAll()` when no longer needed

package/markdown/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog - Memorio
+
+All notable changes to this project will be documented in this file.
+
+---
+
+## v4.6.1 (Security Patch) - 2026-08-14 — CRITICAL Security Fix
+
+### 🔐 Security NOTICE (v4.6.0)
+
+**CRITICAL**: A Gitea Personal Access Token was accidentally committed to `.npmrc` in v4.6.0
+
+**Affected**: `v4.6.0` tag and all builds from that version
+
+**Action Required**:
+- **IMMEDIATE**: Revoke ALL tokens on Gitea Packages by admin access
+- **GENERATE**: Create new PAT with scope `write:package` only
+- **CONFIGURE**: Add as secret `PAT` in GitHub Actions or Gitea Actions
+- **UPGRADE**: Use v4.6.1 where the token is replaced with `${PAT}` environment variable
+
+The hardcoded token `2f398d5d7a734781e96108fdd0dbbabad41ef77a` has been removed in v4.6.1.
+
+### 🐛 Bug Fixes
+
+- **SECURITY**: Removed hardcoded Gitea PAT from `.npmrc` (exposed token remediated)
+- Replaced with environment variable `${PAT}` for secure authentication
+
+### 📝 Documentation Updates
+
+- `.npmrc`: Token replaced with environment variable reference
+- `.gitea/workflows/npm.yml`: Configured to use secrets `GITEA_USER` and `PAT`
+
+---
+
+## v4.6.0 (Previous - SECURITY ISSUE) - 2026-08-13 — Refactoring & Documentation
+
+**⚠️ WARNING**: This version had a hardcoded PAT token that was later remediated in v4.6.1**
+
+### 🐛 Bug Fixes
+
+- Fixed circular import in `idb/index.ts` → `core/global`
+- Fixed dead `globalThis._propertyAccessLog` reference in `observer`
+- Fixed `dispatch.remove(f)` tuple bug in `functions/dispatch.ts`
+- Fixed `logger.isDebugEnabled` using wrong module reference
+- Removed dead `propertyAccessLog` / `pushPropertyAccess` from `core/internal.ts`
+- Removed duplicate path-tracking block in `state` get handler
+- Removed redundant `?? key` fallback in `state` set handler
+
+### 🔧 Code Refactoring
+
+- **Self-contained modules**: All modules now work independently without internal `globalThis.memorio.*` reads/writes
+- **Module-local state**: Created `core/internal.ts` for module-local singletons
+- **Bootstrap-only global**: `core/global.ts` now only publishes to `globalThis.memorio` at initialization
+- **Removed dead code**: `core/constructor.ts` deleted (unused)
+- **Extracted helpers**: `_read`/`_write`/`_remove` in `store` and `session` to eliminate duplication
+- **Fixed circular imports**: `dispatch` → `observer` via `globalThis.events`
+
+### 📝 Documentation Updates
+
+- `docs/README.md`: Added Classic `import { state } from 'memorio'` section, improved badges layout, enhanced "Why memorio?" comparison table
+- `docs/markdown/STORE.md`: Added classic import note
+- `docs/markdown/IMPORT.md`: New file for named export guide
+- `docs/SUMMARY.md`: Updated to include `IMPORT.md`
+- `README.md`: Badge corrections, header cleanup, removed unverified bundle size claims
+
+### 🆕 GitHub Actions / Gitea Workflows
+
+- Added `.gitea/workflows/npm.yml` for automatic npm package publishing to Gitea Packages on `v*` tags
+- Requires `GITEA_USER` and `PAT` secrets
+
+### 🧪 Tests
+
+- **Result: 9 suites · 101 passed · 4 skipped · 1 todo**
+- All lint and typecheck clean
+
+---
+
+## v3.0.2 (Current) - 2026-05-19 — Bug Fix, Security & API Expansion
+
+### 🐛 Bug Fixes
+
+- Removed dead code: `buildPathTracker` from `functions/state/index.ts` (unused Proxy builder, exported nowhere)
+- Removed double `delete` in state `removeAll` handler (redundant null-check + delete on same key)
+- Removed unbound `globalThis.state` reference in state init (would throw `ReferenceError` in strict mode)
+- Removed `Object.freeze(observer)` referencing undeclared variable (`ReferenceError` on module load)
+- Removed `confirm()` synchronous blocking call from `idb.db.delete` (library must not block main thread)
+
+### 🔒 Security Improvements
+
+- Removed `esbuild-sass-plugin` and `esbuild-scss-modules-plugin` from `devDependencies` (unnecessary for a library with no styles)
+- Removed `injectStyle: true`, `sassPlugin()` and `.css` loader from `tsup.config.ts`
+- Deleted `tsup.plugin.injectCss.ts` (code injection vector completely removed from build pipeline)
+- `console.error`/`console.warn` → `console.debug` in `devtools` and `idb` error handlers (consistent debug-only logging policy)
+- `store.set()` now blocks function values instead of silently logging and continuing
+- All `PRIVATE License` headers in `functions/idb/` replaced with `MIT License`
+
+### 🔧 Code Quality
+
+- Added JSDoc to `observerFunction` in `functions/observer/index.ts`
+- Added JSDoc to `cache` global in `functions/cache/index.ts`
+- `lint` and `tsc` pass clean — 0 vulnerabilities from `npm audit`
+
+### 🆕 API — New in 3.0.2
+
+| Function | Description |
+|----------|-------------|
+| `memorio.isBrowser()` | Returns `true` when running in a browser |
+| `memorio.isNode()` | Returns `true` when running in Node.js |
+| `memorio.isDeno()` | Returns `true` when running in Deno |
+| `memorio.isEdge()` | Returns `true` in Cloudflare Workers, Vercel Edge, etc. |
+| `memorio.getCapabilities()` | Full capabilities object (`platform`, `hasLocalStorage`, `hasIndexedDB`, …) |
+| `memorio.createContext(name?)` | Create multi-tenant isolated context |
+| `memorio.listContexts()` | List all active isolated contexts |
+| `memorio.deleteContext(id)` | Delete isolated context by ID |
+| `memorio.isolate(name?)` | Shorthand alias for `createContext` |
+
+### 🧪 Tests
+- **Result: 8 suites · 95 passed · 3 skipped · 0 failed**
+
+### 🗑️ Dependency Changes
+
+| Removed | Reason |
+|---------|--------|
+| `esbuild-sass-plugin@3.7.0` | No SCSS in a library |
+| `esbuild-scss-modules-plugin@1.1.1` | No SCSS in a library |
+| 36 transitive packages | Removed from `node_modules` |
+
+### 📝 Documentation Updates
+
+- `docs/README.md`: replaced `console.debug` with `console.debug` in usage examples; fixed `esbuild` badge → `tsup`
+- `.github/CHANGELOG.md`: restructured with fix / security / changed sections
+- `.github/HISTORY.md`: complete rewrite through v3.0.2
+- `.github/SECURITY.md`: NIST/NSA standard + OWASP Top 10 mapping
+- `.github/CITATION.cff`: license PRIVATE → MIT to match `package.json`
+- `.project/*`: all context documents updated to v3.0.2
+
+---
+
+## v2.9.0 — 2026-05-13
+
+### Added
+- DevTools — `memorio.devtools.inspect()`, `stats()`, `exportData()`
+- Logger with full history, stats and export
+- Platform detection (`isBrowser`, `isNode`, `isDeno`, `isEdge`, `getCapabilities`)
+- Session isolation via `crypto.randomUUID()`
+
+### Changed
+- Updated dependencies to latest versions
+- Improved cross-platform support (Deno, Edge Workers, Node.js)
+
+### Security
+- Secure random session IDs replaced `Math.random()`
+- Key validation (max 512 chars + character whitelist)
+
+---
+
+## v2.5.0 — 2026-02-17
+
+- Initial release of memorio (state, store, session, cache, idb)
+- Observer pattern (`observer`)
+- `useObserver` React hook