memorio 4.9.35 → 5.1.0

package/markdown/SESSION.md

@@ -0,0 +1,164 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Session - Memorio
+
+> 🖥️ **Browser & Edge**: Uses sessionStorage for persistence
+> ⚙️ **Node.js/Deno**: Falls back to in-memory storage (not persistent)
+
+Session provides temporary storage using browser sessionStorage. Data persists until the tab or window is closed.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { session } from 'memorio';
+```
+
+> **Classic `import`**: `session` is also available via the global entrypoint.
+> `import 'memorio/global'` exposes the same instance as `globalThis.session`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save session data
+session.set('token', 'abc123');
+session.set('userId', 42);
+
+// Read session data
+console.debug(session.get('token')); // "abc123"
+
+// Check persistence
+console.debug(session.isPersistent); // true in browser, false in Node.js/Deno
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+session.set('user', { name: 'Mario', role: 'admin' });
+
+// Remove specific item
+session.remove('token');
+
+// Clear all session data
+session.removeAll();
+```
+
+### Example 3: Advanced
+
+```javascript
+// Check if session has data
+if (session.get('authToken')) {
+  // User is logged in
+}
+
+// Get storage quota (returns Promise<[usage, quota]> in KB)
+const [used, total] = await session.quota();
+console.debug(`Using ${used} out of ${total} KB`);
+
+// Get total size in characters
+const size = session.size();
+console.debug(`${size} bytes`);
+
+// Handle session expiry
+window.addEventListener('storage', (e) => {
+  if (e.key === 'session' && !e.newValue) {
+    // Session cleared
+    redirectToLogin();
+  }
+});
+```
+
+---
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `session.get(name)` | `name: string` | `any` | Get value from session |
+| `session.set(name, value)` | `name: string, value: any` | `void` | Save value to session |
+| `session.remove(name)` | `name: string` | `boolean` | Remove single item |
+| `session.delete(name)` | `name: string` | `boolean` | Alias for remove |
+| `session.removeAll()` | `none` | `boolean` | Clear all session data |
+| `session.clearAll()` | `none` | `boolean` | Alias for removeAll |
+| `session.size()` | `none` | `number` | Get total size in characters |
+| `session.quota()` | `none` | `Promise<[number, number]>` | Get storage usage/quota in KB |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `session.isPersistent` | `boolean` | `true` if using real sessionStorage, `false` if in-memory fallback |
+
+---
+
+## Store vs Session
+
+| Feature | Store | Session |
+|---------|-------|---------|
+| Storage | localStorage | sessionStorage |
+| Lifetime | Forever | Until tab closes |
+| Use case | User preferences | Temporary auth |
+| Shared across tabs | Yes | No |
+| Platform | Browser/Edge | Browser/Edge |
+| Persistence | ✅ Always | ✅ Browser only |
+
+---
+
+## Platform Notes
+
+| Platform | Behavior |
+|----------|----------|
+| Browser | Uses real sessionStorage - data persists until tab closes |
+| Edge Worker | Uses real sessionStorage |
+| Node.js | In-memory fallback - data lost on process restart |
+| Deno | In-memory fallback - data lost on process restart |
+
+---
+
+## Best Practices
+
+1. Use for auth tokens: `session.set('token', jwt)`
+2. Clear on logout: `session.removeAll()`
+3. Don't use for persistent data
+4. Check for null: `session.get('key') || defaultValue`
+
+---
+
+## Common Use Cases
+
+### Authentication
+
+```javascript
+// Login
+session.set('authToken', response.token);
+session.set('user', response.user);
+
+// Logout
+session.removeAll();
+router.push('/login');
+```
+
+### Form Progress
+
+```javascript
+// Save form draft
+session.set('formDraft', formData);
+
+// Restore on page refresh
+const draft = session.get('formDraft');
+if (draft) restoreForm(draft);
+```

package/markdown/SQLITE.md

@@ -0,0 +1,189 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# SQLite - Memorio
+
+> The `sql.js` package is **optional** - if it is not installed, Memorio loads `sql.js` on first use by injecting the `sql-wasm-browser.js` UMD build from the jsDelivr CDN as a classic `<script>` (which exposes the `initSqlJs` factory on `globalThis`). No bare `import('sql.js')` is ever emitted, so bundlers never resolve the optional dependency at build time. Not available in Node.js/Deno.
+
+SQLite brings a full SQL engine into the browser through [`sql.js`](https://sql.js.org), a port of SQLite to JavaScript via WebAssembly. Memorio loads it **lazily** on first use, so it only affects bundles that actually use the `sqlite` module.
+
+## Installation
+
+```bash
+npm install memorio
+# Optional: install the SQLite engine locally (the default loader fetches it from the CDN)
+npm install sql.js
+```
+
+```javascript
+import { sqlite } from 'memorio';
+```
+
+> **Global API**: `import 'memorio/global'` is the opt-in entrypoint that also exposes `state`, `store`, `session`, `cache`, `idb`, `sqlite`, `observer`, and `useObserver` on `globalThis`.
+
+> The default loader injects the sql.js UMD build (`sql-wasm-browser.js`) from the jsDelivr CDN as a classic `<script>`, exposing the `initSqlJs` factory on `globalThis`. This keeps `sql.js` (and its WASM) out of your build graph entirely - it's only fetched when `sqlite` is first used. For production/self-hosted setups, install `sql.js` and configure a custom `loader` (e.g. `sqlite.config({ loader: () => import('sql.js') })` under a bundler), or set the wasm base with `sqlite.config({ wasmUrl })` / `sqlite.config({ locateFile })`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Create an in-memory database and a table
+await sqlite.db.create('myApp');
+await sqlite.query.run('myApp', 'CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+
+// Insert data
+await sqlite.query.run('myApp', 'INSERT INTO users (name) VALUES (?)', ['Mario']);
+
+// Select data
+const rows = await sqlite.query.select('myApp', 'SELECT * FROM users');
+console.debug(rows); // [{ id: 1, name: 'Mario' }]
+```
+
+### Example 2: CRUD shortcuts
+
+```javascript
+const db = 'store';
+
+await sqlite.db.create(db);
+await sqlite.query.run(db, 'CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL)');
+await sqlite.data.set(db, 'INSERT INTO products (name, price) VALUES (?, ?)', ['Apple', 1.5]);
+await sqlite.data.set(db, 'INSERT INTO products (name, price) VALUES (?, ?)', ['Banana', 0.8]);
+
+// First matching row
+const apple = await sqlite.data.get(db, 'SELECT * FROM products WHERE name = ?', ['Apple']);
+console.debug(apple); // { id: 1, name: 'Apple', price: 1.5 }
+```
+
+### Example 3: Export / Import
+
+```javascript
+await sqlite.db.create('myApp');
+await sqlite.query.run('myApp', 'CREATE TABLE todos (id INTEGER PRIMARY KEY, task TEXT)');
+await sqlite.data.set('myApp', 'INSERT INTO todos (task) VALUES (?)', ['Write docs']);
+
+// Export the in-memory database to a portable binary dump
+const dump = await sqlite.db.export('myApp');
+
+// Later... import it back
+await sqlite.db.import('restored', dump);
+const rows = await sqlite.query.select('restored', 'SELECT * FROM todos');
+```
+
+### Example 4: Engine control
+
+```javascript
+// Configure the wasm location BEFORE first use (sets the locateFile base)
+sqlite.config({ wasmUrl: '/static/sql.js/' });
+
+// Or provide a fully custom loader (e.g. a local/npm build of sql.js)
+sqlite.config({ loader: async () => {
+  return await import('sql.js');   // local install - resolves at runtime
+}});
+
+// Enable automatic persistence of one or more databases (see Example 5)
+sqlite.config({ persistence: true });
+
+// Wait until the engine is ready
+await sqlite.ready;
+console.debug('SQLite version:', sqlite.db.version());
+```
+
+### Example 5: Persistence & dev download
+
+> **Important:** sql.js databases live in **WebAssembly memory** - they are
+> in-memory and **volatile** (lost on page refresh) unless you persist them.
+
+```javascript
+// Opt into auto-persistence at create time (global config or per-create)
+await sqlite.db.create('app', { persistence: true });
+
+await sqlite.query.run('app', 'CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT)');
+// writes are snapshotted to localStorage automatically (debounced via updateHook)
+
+await sqlite.db.persist('app');          // force an immediate snapshot
+// After a refresh, reopening restores the data:
+await sqlite.db.create('app', { persistence: true });
+
+// Dev convenience: download the current db as a .sqlite file from the browser
+await sqlite.db.download('app', 'app.sqlite');
+
+// Flush + persist + release the handle
+await sqlite.db.close('app');
+```
+
+Persistence is stored on `store` (localStorage, namespaced per
+`sqlite.config({ namespace })` / memorio context) as a base64 snapshot under
+`memorio:sqlite:db:<ns>:<name>`. It is best-effort: if `store` is unavailable
+the database simply behaves as in-memory.
+
+---
+
+## API Reference
+
+### Engine Control
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `sqlite.config(opts)` | `opts: { loader?, locateFile?, wasmUrl?, persistence?, namespace? }` | `sqlite` | Configure the engine. `loader` fully replaces the initializer (default = CDN `<script>`); `locateFile` customizes wasm resolution; `wasmUrl` sets the wasm base directory; `persistence` toggles automatic db snapshots; `namespace` partitions persisted snapshots. Chainable. |
+| `sqlite.db.create(name, opts)` | `name: string, opts?: { data?, persistence? }` | `Database` | Opens/creates a named in-memory db. With `persistence: true` (or global config), a snapshot is restored if present and writes are auto-saved. |
+| `sqlite.db.persist(name)` | `name: string` | `Promise<boolean>` | Force an immediate snapshot of a persisted database to `store`. |
+| `sqlite.db.download(name, filename?)` | `name: string, filename?: string` | `Promise<boolean>` | Dev-only: trigger a browser download of the db as a `.sqlite` file. |
+| `sqlite.db.close(name)` | `name: string` | `Promise<void>` | Persist (if enabled), close, and release the handle. |
+| `sqlite.ready` | none | `Promise<void>` | Resolves once `sql.js` has been initialized. Rejects (and sets `_disabled`) if the engine can't load. |
+| `sqlite.db.version()` | none | `string \| null` | Engine version, available after initialization. |
+| `sqlite._disabled` | none | `boolean` | `true` when the module is disabled (non-browser env / load failure). |
+| `sqlite._warning` | none | `string \| undefined` | Reason text when disabled, if applicable. |
+
+### Database Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `sqlite.db.support()` | none | `boolean` | Check whether SQLite can run in this environment. |
+| `sqlite.db.create(name, opts?)` | `name: string`, `opts?: { data }` | `Promise<Database>` | Create an in-memory database (or reopen one from a binary dump). |
+| `sqlite.db.get(name)` | `name: string` | `Database` | Retrieve an open database handle. |
+| `sqlite.db.delete(name)` | `name: string` | `boolean` | Close and remove a database handle. |
+| `sqlite.db.list()` | none | `string[]` | List open database names. |
+| `sqlite.db.size(name?)` | `name?: string` | `Promise<number>` | Size in bytes of one or all databases. |
+| `sqlite.db.export(name)` | `name: string` | `Promise<Uint8Array>` | Export a database to a binary dump. |
+| `sqlite.db.import(name, data)` | `name: string`, `data` | `Promise<Database>` | Create/replace a database from a binary dump. |
+
+### Query Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `sqlite.query.run(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<number>` | Run a statement that does not return rows (INSERT / UPDATE / DELETE / CREATE). Returns modified-row count. |
+| `sqlite.query.select(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<object[]>` | Run a query and return the rows as plain objects. |
+
+### Data Methods (CRUD shortcuts)
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `sqlite.data.set(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<number>` | Alias of `sqlite.query.run`. |
+| `sqlite.data.get(name, sql, params?)` | `name: string`, `sql: string`, `params?: any[]` | `Promise<object \| null>` | Alias of `sqlite.query.select` returning the first row (or `null`). |
+
+---
+
+## Platform Support
+
+| Platform | Support | Notes |
+|----------|---------|-------|
+| Browser | ✅ Full | Requires WebAssembly + the `sql.js` package (or CDN fallback) |
+| Edge Worker | ⚠️ Limited | WebAssembly may be available; configure a `loader` manually |
+| Node.js | ❌ Not available | Use `store` or `session` instead |
+| Deno | ❌ Not available | Use `store` or `session` instead |
+
+---
+
+## Best Practices
+
+1. Configure the wasm path for production: `sqlite.config({ wasmUrl })` or `sqlite.config({ loader })`.
+2. Create one named database per feature and reuse the handle: `const db = await sqlite.db.create('app')`.
+3. Always release databases you no longer need: `sqlite.db.delete('temp')`.
+4. Use `await sqlite.ready` before running statements to ensure the engine is loaded.
+5. Use `?` placeholders and `params` to avoid SQL injection.

package/markdown/STATE.md

@@ -0,0 +1,159 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# State - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+State is a reactive global state manager using JavaScript Proxies. It's simple, powerful, and requires no setup. Data persists only in memory during the session.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { state } from 'memorio';
+```
+
+That's it. `state` is ready to use.
+
+> **Classic `import`**: `state` is also available as a named export from the global entrypoint.
+> `import 'memorio/global'` exposes the same proxy as `globalThis.state`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Set a value
+state.name = 'Mario';
+state.age = 25;
+
+// Get a value
+console.debug(state.name); // "Mario"
+
+// Simple object
+state.user = { name: 'Luigi', level: 1 };
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Array operations
+state.items = [1, 2, 3];
+state.items.push(4);
+console.debug(state.items); // [1, 2, 3, 4]
+
+// Nested objects
+state.config = { theme: 'dark', lang: 'en' };
+state.config.theme = 'light';
+
+// List all states
+console.debug(state.list);
+```
+
+### Example 3: Advanced
+
+```javascript
+// Lock state to prevent modifications
+state.frozenConfig = { maxUsers: 100 };
+state.frozenConfig.lock();
+// Now state.frozenConfig cannot be modified
+
+// Path tracking
+const path = state.user.path;
+console.debug(path.name); // "user"
+console.debug(path.profile.name); // "user.profile"
+
+// Get full path as string
+console.debug(state.user.__path); // "state.user"
+
+// Protected keys (internal use)
+console.debug(protect); // Array of protected keys
+```
+
+---
+
+## API Reference
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `state.list` | Array | Get all current state keys (deep copy) |
+| `state.path` | Object | Get path tracker for current location |
+| `state.__path` | string | Get full path as string |
+
+### Methods
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `state.remove(key)` | `key: string` | Remove a specific state |
+| `state.removeAll()` | none | Clear all states |
+
+### Lock
+
+```javascript
+// Lock an object or array
+state.myArray = [1, 2, 3];
+state.myArray.lock();
+
+// Now any modification will fail
+state.myArray.push(4); // Error: state 'myArray' is locked
+```
+
+---
+
+## How It Works
+
+Memorio uses JavaScript `Proxy` to intercept get/set operations on the global `state` object. This allows:
+
+1. **Reactivity** - Any change can trigger observers
+2. **Nested objects** - Deep path tracking
+3. **Type safety** - Full TypeScript support
+
+---
+
+## Platform Notes
+
+| 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 |
+
+**Note**: In server environments (Node.js/Deno), use `memorio.createContext()` for request isolation.
+
+---
+
+## Best Practices
+
+1. Use descriptive keys: `state.userProfile` not `state.up`
+2. Group related data: `state.cart.items` not `state.cartItems`
+3. Lock static config: `state.appConfig.lock()`
+4. Clean up on logout: `state.removeAll()`
+5. Use path tracking for debugging: `state.myData.__path`
+
+---
+
+## Common Errors
+
+```javascript
+// Error: protected key
+state._internal = 'value';
+// Output: "key _internal is protected"
+
+// Error: locked state
+state.locked = { x: 1 };
+state.locked.lock();
+state.locked.x = 2;
+// Output: "Error: state 'locked' is locked"
+```

package/markdown/STORE.md

@@ -0,0 +1,170 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Store - Memorio
+
+> 🖥️ **Browser & Edge**: Uses localStorage for persistence
+> ⚙️ **Node.js/Deno**: Falls back to in-memory storage (not persistent)
+
+Store provides persistent localStorage management with a simple API. Data survives page refreshes and browser restarts.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import { store } from 'memorio';
+```
+
+> **Classic `import`**: `store` is also available via the global entrypoint.
+> `import 'memorio/global'` exposes the same instance as `globalThis.store`.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save data
+store.set('username', 'Mario');
+store.set('score', 1500);
+
+// Read data
+console.debug(store.get('username')); // "Mario"
+console.debug(store.get('score'));    // 1500
+
+// Check if using real persistence
+console.debug(store.isPersistent); // true in browser, false in Node.js/Deno
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+store.set('user', { name: 'Luigi', level: 5 });
+const user = store.get('user');
+console.debug(user.name); // "Luigi"
+
+// Remove single item
+store.remove('username');
+
+// Check size
+const totalSize = store.size();
+console.debug(`${totalSize} bytes`);
+```
+
+### Example 3: Advanced
+
+```javascript
+// Get storage quota (returns Promise<[usage, quota]> in KB)
+const [used, total] = await store.quota();
+console.debug(`Using ${used} out of ${total} KB`);
+
+// Get total size in characters
+const size = store.size();
+console.debug(`${size} bytes`);
+
+// Clear all data
+store.removeAll();
+// or use alias
+store.clearAll();
+
+// Handle errors gracefully
+try {
+  store.set('largeData', hugeObject);
+} catch (err) {
+  console.error('Storage full:', err);
+}
+```
+
+---
+
+## API Reference
+
+### Methods
+
+| Method | Parameters | Returns | Description |
+|--------|------------|---------|-------------|
+| `store.get(name)` | `name: string` | `any` | Get value from storage |
+| `store.set(name, value)` | `name: string, value: any` | `void` | Save value to storage |
+| `store.remove(name)` | `name: string` | `boolean` | Remove single item |
+| `store.delete(name)` | `name: string` | `boolean` | Alias for remove |
+| `store.removeAll()` | none | `boolean` | Clear all storage |
+| `store.clearAll()` | none | `boolean` | Alias for removeAll |
+| `store.size()` | none | `number` | Get total size in characters |
+| `store.quota()` | none | `Promise<[number, number]>` | Get storage usage/quota in KB |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `store.isPersistent` | `boolean` | `true` if using real localStorage, `false` if in-memory fallback |
+
+### Supported Types
+
+```javascript
+// All JSON-serializable types work
+store.set('string', 'hello');
+store.set('number', 42);
+store.set('boolean', true);
+store.set('array', [1, 2, 3]);
+store.set('object', { key: 'value' });
+store.set('null', null);
+store.set('undefined', null); // converted to null
+```
+
+### Not Supported
+
+```javascript
+// Functions will log an error
+store.set('myFunc', () => {});
+// Output: "It's not secure to store functions."
+```
+
+---
+
+## Platform Comparison
+
+| Feature | Store | Session | Cache | IDB |
+|---------|-------|---------|-------|-----|
+| **Storage** | localStorage | sessionStorage | Memory | IndexedDB |
+| **Lifetime** | Forever | Until tab closes | Until refresh | Forever |
+| **Capacity** | ~5-10 MB | ~5-10 MB | Unlimited | 50+ MB |
+| **Platform** | Browser/Edge | Browser/Edge | All | Browser |
+| **Persistence** | ✅ true | N/A | ❌ false | ✅ true |
+
+---
+
+## How It Works
+
+Store wraps the browser's `localStorage` API with:
+
+- Automatic JSON serialization/deserialization
+- Error handling for parse failures
+- Size calculation
+- Quota monitoring
+
+---
+
+## Storage Limits
+
+- **Chrome/Safari**: ~5-10 MB
+- **Firefox**: ~10 MB
+- **Edge**: ~5-10 MB
+
+Use `store.quota()` to monitor usage.
+
+---
+
+## Best Practices
+
+1. Prefix keys: `store.set('app_username', '...')`
+2. Check before set: `if (store.get('key')) { ... }`
+3. Handle quota: Try/catch around large data
+4. Clean up: `store.removeAll()` on logout