npm - memorio - Versions diffs - 4.7.3 → 4.9.5 - Mend

memorio 4.7.3 → 4.9.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/markdown/OBSERVER.md DELETED Viewed

@@ -1,200 +0,0 @@
-# Observer - Memorio
-Observer lets you react to state changes. When a state key changes, your callback function runs.
-## Installation
-```bash
-npm install memorio
-```
-```javascript
-import 'memorio';
-```
----
-## Quick Examples
-### Example 1: Basic Usage
-```javascript
-observer('state.counter', (newValue) => {
-  console.debug('Counter is now:', newValue);
-});
-state.counter = 1;
-// Output: "Counter is now: 1"
-state.counter = 5;
-// Output: "Counter is now: 5"
-```
-### Example 2: Intermediate
-```javascript
-// Observer with old value
-observer('state.user', (newValue, oldValue) => {
-  console.debug(`User changed from ${oldValue?.name} to ${newValue?.name}`);
-});
-state.user = { name: 'Mario' };
-// Output: "User changed from undefined to Mario"
-state.user = { name: 'Luigi' };
-// Output: "User changed from Mario to Luigi"
-```
-### Example 3: Advanced
-```javascript
-// Multiple callbacks for same path
-observer('state.data', [handler1, handler2]);
-// List all observers
-console.debug(observer.list);
-// Output: [{ name: 'state.data', id: '...' }, ...]
-// Remove specific observer
-observer.remove('state.data');
-// Remove all observers
-observer.removeAll();
-// Check if observer exists
-if (observer.has('state.counter')) {
-  console.debug('Observer exists for counter');
-}
-```
----
-## Direct Values (Vanilla JS)
-Observer supports direct state values, not just string paths:
-```javascript
-// Direct value - no string needed!
-observer(state.counter, (newValue) => {
-  console.debug('Counter:', newValue);
-});
-// Works with objects too
-observer(state.user, (newValue) => {
-  console.debug('User:', newValue?.name);
-});
-// Multiple callbacks as array
-observer('state.data', [cb1, cb2, cb3]);
-```
----
-## API Reference
-### observer(path, callback, option)
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `path` | `string \| object` | State path (e.g., `'state.counter'`) or direct state value |
-| `callback` | `function \| array` | Function(s) called on change. Can be a single function or array of functions |
-| `option` | `boolean` | Listen continuously (default: `true`) |
-### Callback Parameters
-```javascript
-observer('state.key', (newValue, oldValue) => {
-  // newValue: the new value
-  // oldValue: the previous value
-});
-```
-### Properties
-| Property | Type | Description |
-|----------|------|-------------|
-| `observer.list` | `Array` | Get all active observers |
-### Methods
-| Method | Parameters | Description |
-|--------|------------|-------------|
-| `observer.remove(name)` | `string` | Remove observer for specific path |
-| `observer.removeAll()` | none | Remove all observers |
-| `observer.has(name)` | `string` | Check if observer exists for path (returns boolean) |
----
-## React Integration
-### With useState
-```javascript
-const [count, setCount] = useState(0);
-observer('state.counter', () => {
-  setCount(state.counter);
-});
-```
-### With useEffect
-```javascript
-useEffect(() => {
-  const handleChange = (newVal) => {
-    console.debug('Changed:', newVal);
-  };
-  observer('state.data', handleChange);
-  // Cleanup
-  return () => observer.remove('state.data');
-}, []);
-```
----
-## How It Works
-Observer subscribes to state changes via the Proxy's set trap. When `state.key = value` is called:
-1. The Proxy intercepts the set
-2. Fires all callbacks registered for that path
-3. Callbacks receive newValue and oldValue
----
-## Best Practices
-1. Clean up observers in React `useEffect` return
-2. Use specific paths: `'state.user.name'` not `'state'`
-3. Remove observers when components unmount
-4. Use `observer.removeAll()` on page navigation
----
-## Common Patterns
-### Form Validation
-```javascript
-observer('state.form.email', (email) => {
-  const isValid = email.includes('@');
-  state.form.isValid = isValid;
-});
-```
-### Analytics
-```javascript
-observer('state.page', (page) => {
-  analytics.track('page_view', { page });
-});
-```
-### Auto-save
-```javascript
-observer('state.draft', (content) => {
-  store.set('autosave', content);
-});
-```

package/markdown/PLATFORM.md DELETED Viewed

@@ -1,265 +0,0 @@
-# Platform & Context Isolation - Memorio
-> ℹ️ **New in v2.7.0, expanded in v3.0.2**: Context isolation system for multi-tenant server-side applications
-Memorio automatically detects the runtime environment and adapts its behavior accordingly. This document explains platform compatibility, session isolation, and the new context system.
----
-## Quick Reference: Client vs Server
-### Which Module to Use?
-| Scenario | Recommended Module | Persistence |
-|----------|-------------------|-------------|
-| UI State (React/components) | `state` | Memory |
-| Temporary computed data | `cache` | Memory |
-| User preferences | `store` | Browser localStorage |
-| Auth tokens | `session` | Browser sessionStorage |
-| Large offline data | `idb` | IndexedDB |
-| Server request isolation | `memorio.createContext()` | Memory |
-### Module Availability
-| Module | Browser | Node.js | Deno | Edge |
-|--------|--------|---------|------|------|
-| `state` | ✅ | ✅ | ✅ | ✅ |
-| `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
-| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ |
-| `idb` | ✅ | ❌ | ❌ | ⚠️ |
-| `useObserver` | ✅ | ⚠️ | ⚠️ | ✅ |
-| `devtools` | ✅ | ❌ | ❌ | ❌ |
----
-## Platform Detection
-Memorio automatically detects the environment on import:
-```javascript
-import 'memorio';
-// Check current platform
-console.debug(memorio.getCapabilities().platform); // 'browser' | 'node' | 'deno' | 'edge'
-console.debug(store.isPersistent); // true if using real localStorage
-```
-### Available Platform APIs
-```javascript
-// Check platform
-memorio.isBrowser()    // true in browser
-memorio.isNode()      // true in Node.js
-memorio.isDeno()      // true in Deno
-memorio.isEdge()      // true in Edge Workers
-// Get capabilities
-const caps = memorio.getCapabilities();
-// caps.platform, caps.hasSessionStorage, caps.hasLocalStorage, etc.
-```
----
-## Platform Compatibility Matrix
-| Feature | Browser | Node.js | Deno | Edge Workers |
-|---------|---------|---------|------|--------------|
-| `state` | ✅ | ✅ | ✅ | ✅ |
-| `observer` | ✅ | ✅ | ✅ | ✅ |
-| `useObserver` | ✅ | ⚠️ React only | ⚠️ React only | ✅ |
-| `cache` | ✅ | ✅ | ✅ | ✅ |
-| `store` | ✅ (localStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (localStorage) |
-| `session` | ✅ (sessionStorage) | ⚠️ (memory) | ⚠️ (memory) | ✅ (sessionStorage) |
-| `idb` | ✅ | ❌ | ❌ | ⚠️ |
-- ✅ Full support
-- ⚠️ Partial support (fallback to in-memory)
-- ❌ Not available
----
-## Client vs Server Usage
-### 🖥️ Client-Side (Browser)
-All features work with real browser storage:
-```javascript
-// Store - persistent localStorage
-store.set('preferences', { theme: 'dark' });
-store.isPersistent; // true
-// Session - temporary sessionStorage
-session.set('token', 'jwt-token');
-session.isPersistent; // true (survives refresh)
-// IDB - large data storage
-idb.db.create('myApp');
-```
-### 🖥️ Server-Side (Node.js/Deno)
-Use `state` and `cache` for in-memory data. Store/session fall back to memory:
-```javascript
-// State - in-memory global state
-state.user = { name: 'Server User' };
-// Cache - in-memory temporary cache
-cache.set('apiResponse', data);
-// Store - in-memory fallback (not persistent)
-store.set('temp', data);
-store.isPersistent; // false - data lost on restart
-// Session - in-memory fallback
-session.set('requestData', data);
-session.isPersistent; // false - data lost on restart
-```
----
-## Session Isolation
-Each instance/session gets unique storage keys to prevent conflicts:
-```javascript
-// Without context: "memorio_store_[sessionId]_key"
-// With context: "[contextName]-key"
-```
-This ensures:
-- Multiple browser tabs don't share session data
-- Server-side requests are isolated
----
-## Context Isolation (Server-Side Multi-Tenancy)
-> ⚠️ **Server-Side Only**: This feature is designed for multi-tenant server environments (Node.js, Deno). Not needed for client-side applications.
-For server-side applications handling multiple tenants (e.g., different users/requests), use **contexts** to isolate data:
-### Creating a Context
-```javascript
-// Create isolated context for a user/session
-const ctx = memorio.isolate('user-123');
-// Keys in store/session are prefixed with context name
-// store: "user-123-key"
-// session: "user-123-key"
-// Use context's isolated storage
-ctx.state.user = { name: 'Isolated User' };
-ctx.store.set('settings', { theme: 'dark' });
-ctx.session.set('token', 'abc123');
-ctx.cache.set('temp', data);
-// Context is completely isolated from global state
-console.debug(state.user); // undefined - global state is separate
-```
-### Managing Contexts
-```javascript
-// List all contexts
-const contexts = memorio.listContexts();
-console.debug(contexts); // ['user-123', 'user-456', ...]
-// Delete a context (cleanup)
-memorio.deleteContext('user-123');
-```
-> **Note**: `memorio.isolate('name')` is a shorthand alias for creating isolated contexts.
-### Context Use Cases
-#### 1. Per-Request Isolation (Express/Fastify)
-```javascript
-// Middleware to isolate each request
-app.use((req, res, next) => {
-  const ctx = memorio.createContext(`req-${req.id}`);
-  req.memorioContext = ctx;
-  next();
-});
-// In route handler
-app.get('/user', (req, res) => {
-  const ctx = req.memorioContext;
-  ctx.state.user = getUserData();
-  // Each request has isolated state
-});
-```
-#### 2. Multi-Tenant SaaS
-```javascript
-// Each tenant gets isolated storage
-function handleTenant(tenantId) {
-  const ctx = memorio.createContext(tenantId);
-  ctx.state.config = getTenantConfig(tenantId);
-  ctx.store.set('data', tenantData);
-  return ctx;
-}
-```
----
-## Best Practices
-### Client-Side (Browser)
-1. Use `store` for persistent data (preferences, user settings)
-2. Use `session` for temporary data (auth tokens)
-3. Use `cache` for computed values
-4. Use `state` for reactive UI state
-### Server-Side (Node.js/Deno)
-1. Use `memorio.createContext()` for each request/tenant
-2. Don't use global `state`/`store`/`session` across requests
-3. Use `cache` for request-scoped caching
-4. Check `store.isPersistent` / `session.isPersistent` if persistence matters
-### Edge Workers
-Same as browser - localStorage and sessionStorage are available.
----
-## API Reference
-### Global Functions
-| Function | Returns | Description |
-|----------|---------|-------------|
-| `memorio.isBrowser()` | `boolean` | Check if running in browser |
-| `memorio.isNode()` | `boolean` | Check if running in Node.js |
-| `memorio.isDeno()` | `boolean` | Check if running in Deno |
-| `memorio.isEdge()` | `boolean` | Check if running in Edge |
-| `memorio.getCapabilities()` | `object` | Get platform capabilities |
-### Context Management
-| Function | Returns | Description |
-|----------|---------|-------------|
-| `memorio.isolate(name?)` | `Context` | Create isolated context |
-| `memorio.listContexts()` | `string[]` | List all context IDs |
-| `memorio.deleteContext(id)` | `boolean` | Delete a context |
-### Properties
-| Property | Type | Description |
-|----------|------|-------------|
-| `memorio.version` | `string` | Memorio version |
-| `memorio.getCapabilities().platform` | `string` | Current platform |
-| `memorio.isBrowser()` / `isNode()` / `isDeno()` / `isEdge()` | `boolean` | Platform checks |
-| `memorio._sessionId` | `string` | Unique session identifier |
-> **Classic `import`**: context APIs are also named exports.
-> `import { createContext, listContexts, deleteContext, isolate } from 'memorio'`.

package/markdown/SCHEMA.md DELETED Viewed

@@ -1,169 +0,0 @@
-# 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'
-// 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'
-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.