memorio 4.9.31 → 5.0.0

package/markdown/PROJECT.md

@@ -0,0 +1,311 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team, BigLogic
+> **Scope**: Project Documentation
+> **Standard**: Memorio Documentation Standard v5
+>
+---
+# Memorio - NPM Package
+
+## Versione
+
+**4.9.5** - Current: `4.9.5` branch
+
+## Chi Siamo
+
+- **Jo**: AI assistant, amico di Dario, professionale e diretto
+- **Dario Passariello**: CTO e fondatore di BigLogic
+- **BigLogic**: Azienda specializzata in soluzioni SaaS artigianali, AI e design ad alta precisione
+
+## Progetto Attuale
+
+**Memorio** è un NPM package leggero e semplice per piccoli progetti dove servono soluzioni veloci senza complessità enterprise:
+
+- **State** - memoria volatile reattiva (Proxy-based)
+- **Store** - localStorage persistenza
+- **Session** - sessionStorage
+- **IDB** - IndexedDB storage strutturato
+- **Cache** - in-memory cache
+- **Observer** - pattern observer per vanilla JS
+- **UseObserver** - React hook per observer
+- **DevTools** - Browser console debugging tools
+- **Logger** - utility di logging
+- **Dispatch** - vanilla JS event system
+- **Schema** - runtime validation per state paths
+- **Typed** - compile-time type safety su state proxy
+- **History** - time-travel (undo/redo/snapshot/diff/trace)
+- **Inspect** - introspection utilities
+- **Memory** - AI memory system con persistence e TTL
+
+**Target**: Progetti piccoli/medi
+**Confronto**: @Biglogic/rgs = enterprise, Memorio = piccoli progetti
+
+## Stack Tecnologico
+
+- TypeScript 6.0.3 (strict mode)
+- tsup 8.5.1 per build (ESM + CJS)
+- ES2022 target
+- ESM (`"type": "module"`)
+- vitest per test (browser + node)
+- Playwright per test end-to-end
+- Peer dependencies: React >=16.8.0 (opzionale)
+- Nessuna UI (è una libreria)
+- Production: dependency-free (zero runtime dependencies)
+
+## Struttura File
+
+```
+memorio/
+├── index.ts                  # Entry point (named exports + memorio namespace)
+├── core/                     # Core modules (bootstrap, platform, internal)
+│   ├── global.ts             # Bootstrap: publishes to globalThis
+│   ├── env.ts                # Runtime DEV/PROD detection
+│   ├── internal.ts           # Module-local internal state singleton
+│   ├── platform.ts           # Browser/Node/Deno/Edge detection
+│   ├── dispatch.ts           # Event dispatch system
+│   ├── hlc.ts                # Hybrid Logical Clock
+│   └── fractional.ts         # Fractional indexing
+├── types/                    # TypeScript declarations
+│   └── memorio.d.ts
+├── functions/                # Feature modules
+│   ├── state/                # Reactive state (Proxy)
+│   ├── store/                # LocalStorage
+│   ├── session/              # SessionStorage
+│   ├── cache/                # In-memory cache
+│   ├── idb/                  # IndexedDB (browser)
+│   ├── sqlite/               # SQLite (sql.js, optional)
+│   ├── observer/             # Observer pattern
+│   ├── useObserver/          # React hook
+│   ├── logger/               # Logging
+│   ├── devtools/             # DevTools (dev-only)
+│   ├── schema/               # Runtime validation
+│   ├── typed/                # Type-safe state views
+│   ├── history/              # Time-travel undo/redo
+│   ├── inspect/              # Introspection
+│   ├── memory/               # AI memory system
+│   ├── message/              # User messages
+│   └── dispatch/             # Event dispatch
+├── tests/                    # Vitest + Playwright tests
+│   ├── vitest/               # Vitest config + test files
+│   └── playwright/           # E2E test specs
+├── .project/markdown/        # Project context & documentation
+│   ├── CHANGELOG.md
+│   ├── PROJECT.md
+│   └── ... (module docs)
+├── docs/                     # Published documentation
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts
+└── .kilo/                    # Kilo AI agent memory
+```
+
+## API Pubbliche
+
+### Core Namespace
+
+```typescript
+import memorio, { state, store, session, cache, idb, sqlite, observer, useObserver, dispatch, message } from 'memorio'
+// or for global access:
+// import 'memorio/global'
+
+// Runtime environment detection
+memorio.env.isDev   // true in development, false in production
+memorio.env.isProd  // inverse of isDev
+
+// Global API (opt-in via memorio/global entry)
+memorio.global()    // Force-expose dev globals on globalThis (idempotent)
+```
+
+### State
+
+```typescript
+// Via named import (or global entrypoint if opted in)
+state.key = 'value'          // Set
+state.key                    // Get (reactive)
+state.remove('key')          // Delete
+state.removeAll()            // Clear all
+state.lock()                 // Lock all modifications
+state.unlock()               // Unlock
+state.list                   // Deep clone of all state
+state.typed<T>()             // Type-safe view
+```
+
+### Store (localStorage)
+
+```typescript
+store.set('key', { value: 42 })
+store.get('key')              // { value: 42 }
+store.remove('key')
+store.removeAll()
+store.isPersistent           // boolean
+store.size()                  // character count
+store.quota()                 // [used, quota]
+store.list()                  // all memorio keys
+```
+
+### Session (sessionStorage)
+
+```typescript
+session.set('key', 'value')
+session.get('key')
+session.remove('key')
+session.removeAll()
+session.isPersistent
+```
+
+### Cache (in-memory)
+
+```typescript
+cache.set('key', 'value')
+cache.get('key')
+cache.remove('key')
+cache.list()                  // all cached items
+cache.clear()                 // alias for removeAll
+```
+
+### Schema Validation
+
+```typescript
+memorio.registerSchema('user.name', {
+  type: 'string',
+  required: true,
+  min: 1,
+  pattern: /^[a-zA-Z]+$/
+})
+
+memorio.validate('user.name', 'Jo')     // { valid: true, errors: [] }
+memorio.listSchemas()                   // registered paths
+memorio.unregisterSchema('user.name')
+```
+
+### History / Time Travel
+
+```typescript
+memorio.enableHistory()      // Start tracking mutations
+const snap = memorio.snapshot()  // Deep clone of state
+memorio.undo()              // Revert last mutation
+memorio.redo()              // Re-apply
+memorio.canUndo()           // boolean
+memorio.canRedo()           // boolean
+memorio.rollback(snap)      // Restore to snapshot
+memorio.trace()             // List all mutations
+memorio.clearHistory()      // Clear undo/redo/trace
+```
+
+### Platform Detection
+
+```typescript
+memorio.isBrowser()          // boolean
+memorio.isNode()             // boolean
+memorio.isDeno()             // boolean
+memorio.isEdge()             // boolean
+memorio.getCapabilities()    // { platform, hasLocalStorage, hasIndexedDB, ... }
+```
+
+### Context (multi-tenant)
+
+```typescript
+memorio.createContext('tenant-name')  // Isolate state by context
+memorio.listContexts()                 // List all contexts
+memorio.deleteContext('context-id')    // Delete a context
+memorio.isolate('tenant-name')         // Shorthand for createContext
+```
+
+## NPM Scripts
+
+| Comando | Descrizione |
+|---------|-------------|
+| `npm run build` | Build con tsup (ESM + CJS) |
+| `npm run watch` | Watch mode con tsup |
+| `npm test` | Esegui vitest test suite |
+| `npm run lint` | Lint con oxlint |
+| `npm run tsc` | TypeScript type check |
+
+## Test Suite
+
+| Suite | Tests | Stato |
+|-------|-------|-------|
+| State | 24 | ✅ |
+| Store | 17 | ✅ |
+| Session | 12 | ✅ |
+| Cache | 5 | ✅ |
+| Observer | 12 | ✅ |
+| useObserver | 12 | ✅ |
+| DevTools | 8 | ✅ |
+| Schema | 10 | ✅ |
+| History | 8 | ✅ |
+| Inspect | 6 | ✅ |
+| ID | 3 | ✅ |
+| Dispatch | 5 | ✅ |
+| Message | 4 | ✅ |
+| Logger | 3 | ✅ |
+| Memory | 5 | ✅ |
+| **Totale** | **~120+** | ✅ |
+
+## Regole Importanti
+
+1. Documentazione in `.project/markdown/`, non nella root
+2. Usare `console.debug()` per il debugging
+   - Nei blocchi `catch` e codice di gestione errori operativi è consentito `console.error()` e `console.warn`
+3. Arrow functions obbligatorie
+4. JSDoc obbligatorio su tutte le funzioni pubbliche
+5. Peer dependency React >=16.8.0 opzionale
+6. Nessuno stile CSS/SCSS (è una libreria)
+7. Nessun database embedded
+8. Tutti i moduli usano singleton keys su `globalThis` per prevenire module duplication
+
+## Dipendenze
+
+### Produzione
+- Nessuna (dependency-free)
+
+### Sviluppo
+- `typescript: 6.0.3`
+- `tsup: 8.5.1`
+- `vitest: 5.0.0`
+- `playwright: chromium`
+- `@types/node: ^25.9.1`
+- `react: ^19.2.6` (peer)
+- `react-dom: ^19.2.6` (peer)
+
+### Peer
+- `react: >=16.8.0` (opzionale)
+- `react-dom: >=16.8.0` (opzionale)
+
+## Module Duplication Strategy
+
+Memorio can be imported via multiple paths (ESM `dist/index.js`, CJS `dist/index.cjs`, package name `memorio`). Each path may resolve to a separate module instance in the bundler. To prevent duplicate proxies:
+
+| Module | Singleton Key |
+|--------|--------------|
+| `state` | `__memorio_state_instance__` |
+| `store` | `__memorio_store_instance__` |
+| `session` | `__memorio_session_instance__` |
+| `cache` | `__memorio_cache_instance__` |
+| internal state | `__memorio_internal_state` |
+
+The first import path to execute creates the instance and stores it on `globalThis`. Subsequent imports find the existing instance and reuse it - guaranteeing all named exports point to the **same** proxy object.
+
+## Valutazione Attuale
+
+### Punti di Forza
+
+- Struttura NPM corretta
+- Build con tsup moderno (ESM + CJS)
+- Testing setup (vitest + Playwright)
+- Auto-detection React per reattività
+- Multi-storage support (state, store, session, idb, cache, sqlite, devtools, logger)
+- Totalmente dependency-free in produzione
+- Cross-platform: Browser, Node.js, Deno, Edge Workers
+- Session isolation e Context system per multi-tenant
+- Module duplication protection via singleton keys
+- Schema validation e typed stores per type safety
+
+### Critica
+
+- Coverage test non verificato
+- Socket.dev Supply Chain Security da monitorare
+
+---
+
+*Ultimo aggiornamento: 2026-09-06*

package/markdown/SCHEMA.md

@@ -0,0 +1,176 @@
+> **Status:** Published
+> **Date:** 2026-09-12
+> **Deciders:** Memorio 5.x Core Team
+> **Scope**: API Reference
+> **Standard**: Memorio API Specification v5
+>
+---
+# Schema Validation - Memorio
+
+> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers
+
+Schema validation guards your `state` against invalid writes. It runs inside the state proxy's `set` trap, so any `state.somePath = value` that violates a registered schema is rejected at runtime - before the value is ever stored.
+
+Schema validation is **opt-in** and **zero-dependency**.
+
+---
+
+## Quick Start
+
+```javascript
+import { memorio, state } from 'memorio'
+
+// Register a validator for a top-level state key
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+// Valid write - accepted
+state.user = { name: 'Sara', email: 'sara@test.com', age: 30 }
+
+// Invalid write - rejected, returns false
+state.user = { name: 'Sara' }           // missing 'email'
+state.user = { name: 42, email: 'x' }   // wrong type for 'name'
+state.user = { age: -5 }                // out of range
+```
+
+---
+
+## Schema Definition
+
+A `Schema` object supports the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'string' \| 'number' \| 'boolean' \| 'object' \| 'array' \| 'any'` | Runtime type check |
+| `required` | `string[]` | Property names that must exist (objects only) |
+| `properties` | `Record<string, Schema>` | Nested property schemas (validated recursively) |
+| `min` | `number` | Number: minimum value. String: minimum length |
+| `max` | `number` | Number: maximum value. String: maximum length |
+| `pattern` | `RegExp` | Regex the string value must match |
+| `enum` | `any[]` | Whitelist of allowed values |
+| `validator` | `(value) => boolean \| string` | Custom validator function |
+
+### Custom validator functions
+
+For logic that's hard to express declaratively, pass a function instead of a schema object:
+
+```javascript
+memorio.registerSchema('counter', (value) => {
+  if (typeof value !== 'number') return 'counter must be a number'
+  if (value < 0) return 'counter must be >= 0'
+  return true
+})
+```
+
+A custom validator receives the raw value. Return `true` to accept, or a **string** describing the error to reject.
+
+---
+
+## Path-based registration
+
+Schemas are keyed by their **state path**, relative to `state`:
+
+| API call | Catches |
+|----------|---------|
+| `registerSchema('user', schema)` | `state.user = value` |
+| `registerSchema('user.age', schema)` | `state.user.age = value` |
+| `registerSchema('items', schema)` | `state.items = value` |
+
+The full dotted path is constructed from the proxy's tree depth. Nested sets propagate the full path automatically.
+
+---
+
+## Manual validation
+
+You can validate a value without writing it to state:
+
+```javascript
+memorio.validate('user', { name: 'Sara', email: 'sara@test.com' })
+// { valid: true }
+
+memorio.validate('user', { name: 'Sara' })
+// { valid: false, errors: ["user: missing required property 'email'"] }
+```
+
+When no schema is registered for a path, `validate` returns `{ valid: true }`.
+
+---
+
+## Schema management
+
+```javascript
+memorio.listSchemas()           // ['user', 'theme', 'items', 'counter']
+memorio.unregisterSchema('counter')  // removes the schema
+```
+
+---
+
+## Full API
+
+| Method | Parameters | Returns | Description |
+|--------|-----------|---------|-------------|
+| `memorio.registerSchema(path, schema)` | `string`, `Schema \| fn` | `void` | Register a validator |
+| `memorio.validate(path, value)` | `string`, `any` | `{ valid, errors? }` | Manually validate a value |
+| `memorio.unregisterSchema(path)` | `string` | `boolean` | Remove a registered schema |
+| `memorio.listSchemas()` | none | `string[]` | List all registered paths |
+| `memorio.registerSchema()` is also importable | `registerSchema` | named export | same function |
+
+---
+
+## Combine with Typed Stores
+
+Schema validation gives you **runtime** safety; typed stores give you **compile-time** safety. Use both for full coverage:
+
+```typescript
+import { memorio, state } from 'memorio'
+
+interface AppState {
+  user: { name: string; email: string; age: number }
+  theme: 'light' | 'dark'
+}
+
+const app = memorio.typed<AppState>()
+
+memorio.registerSchema('user', {
+  type: 'object',
+  required: ['name', 'email'],
+  properties: {
+    name: { type: 'string', min: 1 },
+    email: { type: 'string', pattern: /^[^@]+@[^@]+$/ },
+    age: { type: 'number', min: 0, max: 150 }
+  }
+})
+
+app.user = { name: '', email: 'bad' }   // ❌ TypeScript: age missing
+                                         // ❌ Runtime: missing required fields
+app.user = { name: 'Sara', email: 'ok', age: 30 } // ✅ both checks pass
+```
+
+See [Typed Stores](TYPED.md) for compile-time type safety.
+
+---
+
+## How it works
+
+1. When you call `registerSchema(path, schema)`, the schema is stored in an internal `Map`.
+2. On every `state.set` operation, the proxy's `set` trap computes the full path (e.g. `'user.name'`).
+3. If a schema is registered for that path, the value is validated.
+4. If validation fails, the write is rejected (`return false`), and an error is logged via `console.error` (when `memorio.debug = true`) or `console.debug` (via the internal `message` helper).
+5. If no schema is registered, the write proceeds normally.
+
+The validation adds negligible overhead when no schemas are registered (a single `Map` lookup that returns `undefined`).
+
+---
+
+## Limitations
+
+- Schema validation hooks into the `state` proxy only. `store`, `session`, and `cache` are not validated (they use separate storage). Use `validate()` before writing to other modules.
+- Path matching is **exact**: `registerSchema('user')` guards `state.user = ...`, but does **not** recursively validate `state.user.name = 'new'`. Register schemas at each path you need to guard.
+- The schema system is not a replacement for server-side validation. It protects against accidental misuse and provides defense-in-depth in the browser.