memorio 4.8.0 → 4.9.5

package/markdown/STATE.md

@@ -1,153 +0,0 @@
-# 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 'memorio';
-```
-
-That's it. `state` is now global.
-
-> **Classic `import`**: `state` is also a named export.
-> `import { state } from 'memorio'` returns the exact 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

@@ -1,164 +0,0 @@
-# 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 'memorio';
-```
-
-> **Classic `import`**: `store` is also a named export.
-> `import { store } from 'memorio'` returns the exact 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

package/markdown/SYNC.md

@@ -1,170 +0,0 @@
-# Synchronization & Cloud (optional)
-
-`memorio.memory` is **local-first**. Data is created and served from the device;
-the cloud is only ever a **transport/persistence provider**, never the source of
-truth. Enabling sync does not replace local storage — it *mirrors* it.
-
-```
-                    memorio
-                       │
-              ┌────────┴────────┐
-              │   Memory Engine │
-              └────────┬────────┘
-          ┌────────────┼────────────┐
-          ▼            ▼            ▼
-        local      SQLite         cloud
-        memory     durable        sync
-```
-
-## 1. The rule: the data is born local
-
-```ts
-memorio.memory.remember('user.language', 'Italian', { scope: 'local' })
-//        ↓ local first
-//   store / sessionStorage / IndexedDB / sql.js
-//        ↓ sync / push (when online)
-//   cloud provider
-```
-
-The cloud therefore does not **replace** memory: it **replicates** it. This
-gives you: offline-first, lowest latency, data available immediately,
-synchronization when online, multi-device, multi-user, centralized persistence.
-
-We deliberately do **not** provide:
-
-```ts
-// ❌ two mental models
-memory.cloud.save(...)
-```
-
-Instead:
-
-```ts
-memorio.memory.remember('user.language', 'Italian')
-// and a single configuration point:
-memorio.memory.configure({ sync: { provider: myCloudProvider, namespace: '…' } })
-```
-
-## 2. Scopes (isolation, not a security boundary)
-
-| Scope | Lifetime | Syncs by default |
-|---|---|---|
-| `'device'` | this browser/device only | no (sticky) |
-| `'user'` | follows the user across devices | yes (requires provider + namespace) |
-| `'shared'` | shared across users / tenant | yes (requires provider + namespace) |
-
-> As with `memorio.createContext`, **scoping is a naming convention, not a
-> security boundary.** Enforce real isolation server-side.
-
-## 3. SQLite as the local durable store
-
-SQLite (`sql.js`) is **in-memory by default** (volatie per page load). It becomes
-the durable journal/value store when you opt in:
-
-- `sqlite.config({ persistence: true })` / `sqlite.db.create('app', { persistence: true })`
-  snapshot the database to `store` (localStorage) and restore it on reopen.
-- Writes are snapshotted via sql.js `updateHook` (debounced).
-- `sqlite.db.persist(name)` forces an immediate save; `sqlite.db.close(name)`
-  flushes + closes; `sqlite.db.download(name, file?)` triggers a browser
-  `.sqlite` download (dev convenience).
-
-See `docs/markdown/SQLITE.md` for the full SQLite reference.
-
-## 4. The local operation journal
-
-The **sync journal** is the durable op log that drives cloud reconciliation.
-It is persisted on `store` (localStorage) — **not** on an in-memory sql.js db,
-because pending operations must survive a refresh for offline-first to work.
-
-| Method | Returns | Notes |
-|---|---|---|
-| `memory.journal.append(entry, operation)` | `Promise<MemoryEntry>` | records `remember\|update\|forget\|expire\|confirm\|supersede` with `sync:'pending'` |
-| `memory.journal.pending()` | `Promise<MemoryEntry[]>` | rows where `sync != 'synced'`, for the current namespace |
-| `memory.journal.markSynced(ids)` | `Promise<number>` | advances rows to `synced` (namespace-scoped) |
-| `memory.journal.get(id)` | `Promise<MemoryEntry \| null>` | single entry, namespace-scoped |
-| `memory.journal.clear()` | `Promise<void>` | wipes the current namespace's journal |
-| `memory.journal.replay()` | `Promise<SyncAck>` | pushes `pending()` to the provider, marks synced, optional `pull` |
-| `memory.journal.status()` | `Promise<'store'>` | the substrate in use |
-
-We sync **operations of memory**, never a raw database dump:
-
-```
-user A        device A
-remember X ─────► local ─────► sync ─────► cloud
-forget Z ──────► local ─────► sync ─────► cloud
-```
-
-## 5. Conflict resolution
-
-The cloud must not simply say "last write wins." Memorio tags every entry with:
-
-- `confidence` (0–1, user/system trust in the value)
-- `lastConfirmedAt` / `updatedAt` (epoch ms)
-- `version` (monotonic per-key counter)
-- `source` / `scope`
-
-Remote conflicts are surfaced as `sync:'conflict'` rows via
-`journal.pending()`; the provider's `resolve(op)` hint decides locally. Example:
-
-```
-Laptop:  language=Italian, confidence=0.92
-Phone:   language=English, confidence=0.61
-→ higher-confidence entry wins locally; the provider decides for shared scope.
-```
-
-## 6. Configuring a backend
-
-Sync is **opt-in**. You supply an application-owned `provider` that knows how to
-talk to your backend (REST, WebSocket, Supabase, a custom agent server, …).
-
-```ts
-memorio.memory.configure({
-  namespace: 'user:123:device:abc',   // tenant/user/device — partitions the journal
-  provider: {
-    push(ops) { return fetch('/api/sync', { method: 'POST', body: JSON.stringify(ops), headers: authHeaders }) }
-    pull(since) { return fetch(`/api/sync?since=${since}`).then(r => r.json()) }
-    resolve(op) { return op.confidence >= 0.8 ? 'local' : 'remote' }
-  },
-  auto: true                           // auto-replay on focus/online (default true)
-})
-```
-
-```ts
-interface SyncProvider {
-  push(ops: MemoryEntry[]): Promise<{ synced: string[]; conflicts?: string[]; error?: string }>
-  pull?(since?: number): Promise<MemoryEntry[]>
-  resolve?(op: MemoryEntry): Promise<'local' | 'remote' | 'merge'>
-}
-```
-
-`memorio.memory.ready` resolves once the local journal substrate is chosen.
-
-## 7. Security (NIST / OWASP / NSA posture)
-
-- **Memorio never handles credentials.** No passwords, tokens, or API keys are
-  read from or stored by memorio. Authentication/authorization live in your
-  `provider`/backend (OWASP A01: Broken Access Control).
-- **Namespace isolation.** The journal is keyed by `namespace:id` at the storage
-  layer; there is **no API** to enumerate or open another namespace's journal. A
-  client holding a forged/fake namespace simply sees its own (empty) journal.
-- **No dynamic code.** Journal entries are strictly JSON-round-tripped,
-  size-capped (10 MB/entry), and never `eval`'d. The sql.js loader never
-  `import()`s a bare specifier that could be hijacked at build time.
-- **Trust boundary:** memorio owns the local durable copy + operation log; the
-  provider/backend owns remote-side auth and conflict resolution. Memorio
-  surfaces `conflict`/`error` rows; it does not fabricate a winner.
-- **Data-at-rest (NSA/CISA).** memorio's `store`/`idb`/`sqlite` snapshots are
-  **not encrypted**. If you persist user data server-side or ship it through your
-  backend, encrypt it server-side with keys you manage — memorio treats the local
-  store as untrusted-from-the-browser and does not attest its own integrity.
-
-## 8. Where data lives
-
-| Substrate | API | Volatile? | Persistent? |
-|---|---|---|---|
-| in-memory `Proxy` | `state` | yes (per tab) | no |
-| `localStorage` / Map | `store` | no | yes (browser) |
-| `sessionStorage` / Map | `session` | no | per-tab (browser) |
-| IndexedDB | `idb`, `memory` durable | no | yes |
-| sql.js (WASM heap) | `sqlite` | **yes** | only with `persistence: true` (snapshot → `store`) |
-| sync journal | `memory.journal` | no | yes (`store`) |

package/markdown/TYPED.md

@@ -1,158 +0,0 @@
-# Typed Stores - Memorio
-
-> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
-
-`memorio.typed<T>()` returns the global `state` proxy cast to a TypeScript type `T`, giving you **compile-time** type safety on every access and mutation.
-
-It's a **zero-runtime-cost** wrapper: the returned object is the *exact same* Proxy as `globalThis.state`, just with TypeScript types applied via a generic.
-
----
-
-## Quick Start
-
-```typescript
-import 'memorio'
-
-interface AppState {
-  user: { name: string; age: number; email: string }
-  theme: 'light' | 'dark'
-  items: string[]
-}
-
-const app = memorio.typed<AppState>()
-
-// Type-checked at compile time:
-app.user = { name: 'Sara', age: 30, email: 'sara@test.com' }
-app.theme = 'dark'
-
-// TypeScript errors:
-// app.user = { name: 42 }            // age missing, name wrong type
-// app.theme = 'purple'               // not a valid literal
-```
-
----
-
-## Why use typed stores?
-
-| Without typed | With `memorio.typed<T>()` |
-|---|---|
-| `state.user = { name: 42 }` — runs silently, bug at runtime | `app.user = { name: 42 }` — TypeScript error at compile time |
-| No autocomplete on `state.user.email` | Full IntelliSense: properties, types, method suggestions |
-| Rename `user` to `profile` — no compiler warning anywhere | Every `app.user` access flagged as an error |
-| AI-generated code lacks guardrails | AI gets autocomplete and type feedback inline |
-
----
-
-## Combine with Schema Validation
-
-Typed stores catch type errors at compile time; schema validation catches invalid values at runtime. Together they form a **defense-in-depth** strategy:
-
-```typescript
-import 'memorio'
-
-interface ProfileState {
-  profile: { bio: string; avatar?: string }
-}
-
-const app = memorio.typed<ProfileState>()
-
-memorio.registerSchema('profile', {
-  type: 'object',
-  required: ['bio'],
-  properties: {
-    bio: { type: 'string', min: 1 },
-    avatar: { type: 'string' }
-  }
-})
-
-app.profile = { bio: 'Developer', avatar: 'pic.png' } // ✅ type + schema pass
-app.profile = { avatar: 'pic.png' }                  // ❌ TypeScript: bio missing
-                                                     // ❌ Runtime: bio required
-```
-
-See [Schema Validation](SCHEMA.md) for runtime validation details.
-
----
-
-## Named import variant
-
-`typed` is also available as a named export if you prefer explicit dependencies:
-
-```typescript
-import { typed } from 'memorio'
-
-const app = typed<AppState>()
-```
-
-The `memorio` namespace object is the same — `import 'memorio'` is the recommended entry, named exports are an alternative.
-
----
-
-## Full API
-
-| Method | Parameters | Returns | Description |
-|--------|-----------|---------|-------------|
-| `memorio.typed<T>()` | Generic type `T` | `T` | Returns the global `state` proxy cast to `T` |
-
-The returned object shares the same identity as `globalThis.state`:
-
-```typescript
-const app = memorio.typed<AppState>()
-console.debug(app === state) // true — same Proxy instance
-```
-
----
-
-## React + typed stores
-
-Pair with the `useObserver` hook for type-safe, reactive React components:
-
-```tsx
-import 'memorio'
-import { useReducer } from 'react'
-
-interface AppState {
-  user: { name: string; age: number }
-  theme: 'light' | 'dark'
-}
-
-const app = memorio.typed<AppState>()
-
-function UserProfile() {
-  const [, forceUpdate] = useReducer(x => x + 1, 0)
-
-  useObserver(forceUpdate, [state.user.name])
-
-  return (
-    <div>
-      <h1>{app.user.name}</h1>
-      <span>Theme: {app.theme}</span>
-    </div>
-  )
-}
-```
-
----
-
-## Best Practices
-
-1. **Define your AppState at the root** of your app and import it everywhere:
-
-   ```typescript
-   // types/app-state.ts
-   export interface AppState {
-     user: { name: string; email: string }
-     theme: 'light' | 'dark'
-   }
-   ```
-
-   ```typescript
-   // anywhere in your app
-   import 'memorio'
-   import type { AppState } from '../types/app-state'
-   const app = memorio.typed<AppState>()
-   ```
-
-2. **Layer schema validation on top** for runtime safety, especially for data coming from APIs or user input.
-
-3. **Use alongside `memorio.help()`** to list available globals during development.