memorio 2.5.2 → 2.5.3

package/docs/SESSION.md

@@ -0,0 +1,129 @@
+# Session - Memorio
+
+Session provides temporary storage using browser sessionStorage. Data persists until the tab or window is closed.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save session data
+session.set('token', 'abc123');
+session.set('userId', 42);
+
+// Read session data
+console.log(session.get('token')); // "abc123"
+```
+
+### 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.log(`Using ${used} out of ${total} KB`);
+
+// Get total size in characters
+const size = session.size();
+console.log(`${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 |
+
+---
+
+## 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 |
+
+---
+
+## 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/docs/STATE.md

@@ -0,0 +1,135 @@
+# State - Memorio
+
+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.
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Set a value
+state.name = 'Mario';
+state.age = 25;
+
+// Get a value
+console.log(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.log(state.items); // [1, 2, 3, 4]
+
+// Nested objects
+state.config = { theme: 'dark', lang: 'en' };
+state.config.theme = 'light';
+
+// List all states
+console.log(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.log(path.name); // "user"
+console.log(path.profile.name); // "user.profile"
+
+// Get full path as string
+console.log(state.user.__path); // "state.user"
+
+// Protected keys (internal use)
+console.log(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
+
+---
+
+## 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/docs/STORE.md

@@ -0,0 +1,137 @@
+# Store - Memorio
+
+Store provides persistent localStorage management with a simple API. Data survives page refreshes and browser restarts.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+// Save data
+store.set('username', 'Mario');
+store.set('score', 1500);
+
+// Read data
+console.log(store.get('username')); // "Mario"
+console.log(store.get('score'));    // 1500
+```
+
+### Example 2: Intermediate
+
+```javascript
+// Store objects
+store.set('user', { name: 'Luigi', level: 5 });
+const user = store.get('user');
+console.log(user.name); // "Luigi"
+
+// Remove single item
+store.remove('username');
+
+// Check size
+const totalSize = store.size();
+console.log(`${totalSize} bytes`);
+```
+
+### Example 3: Advanced
+
+```javascript
+// Get storage quota (returns Promise<[usage, quota]> in KB)
+const [used, total] = await store.quota();
+console.log(`Using ${used} out of ${total} KB`);
+
+// Get total size in characters
+const size = store.size();
+console.log(`${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 |
+
+### 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."
+```
+
+---
+
+## 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/docs/SUMMARY.md

@@ -0,0 +1,25 @@
+# Table of contents
+
+* [README](../README.md)
+
+## Core Modules
+
+* [State](STATE.md) - Reactive global state management
+* [Observer](OBSERVER.md) - ⚠️ Deprecated (use useObserver)
+* [useObserver](USEOBSERVER.md) - React hook for state observation
+* [Cache](CACHE.md) - In-memory caching (lost on refresh)
+* [Store](STORE.md) - Persistent localStorage management
+* [Session](SESSION.md) - Temporary sessionStorage management
+* [IDB](IDB.md) - IndexedDB for large data storage
+
+## Additional Resources
+
+* [License](../LICENSE.md)
+* [Contributing](../CONTRIBUTING.md)
+* [Code of Conduct](../CODE_OF_CONDUCT.md)
+* [Security](../SECURITY.md)
+
+## Changelog
+
+* [Changelog](../CHANGELOG.md)
+* [History](../HISTORY.md)

package/docs/USEOBSERVER.md

@@ -0,0 +1,156 @@
+# useObserver - Memorio
+
+useObserver is a React hook for observing state changes. It automatically subscribes to state changes and includes powerful auto-discovery features.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Usage
+
+```javascript
+import { useObserver } from 'memorio';
+
+function Counter() {
+  useObserver(() => {
+    console.debug('Counter changed:', state.counter);
+  }, [state.counter]);
+
+  return <div>{state.counter}</div>;
+}
+```
+
+### Auto-Discovery (Magic Mode)
+
+```javascript
+// Pass your callback WITHOUT dependencies - it auto-discovers!
+function MyComponent() {
+  useObserver(() => {
+    // This will automatically track ALL state properties used inside
+    console.debug('Something changed:', state.user.name, state.items.length);
+  });
+
+  return <div>{state.user.name}</div>;
+}
+```
+
+### Example 2: Intermediate
+
+```javascript
+function UserProfile() {
+  const [localState, setLocalState] = useState(null);
+
+  useObserver(() => {
+    setLocalState(state.user);
+  }, [state.user]);
+
+  return <div>{localState?.name}</div>;
+}
+```
+
+### Example 3: Advanced
+
+```javascript
+// Multiple watchers with array
+function MultiWatch() {
+  useObserver(() => {
+    console.debug('A or B changed:', state.a, state.b);
+  }, [state.a, state.b]);
+
+  return <div>{state.a} - {state.b}</div>;
+}
+```
+// With string path (for store)
+function StoreWatcher() {
+  useObserver(() => {
+    console.debug('Store changed');
+  }, 'store.userPreferences');
+
+  return <div />;
+}
+```
+
+---
+
+## API Reference
+
+### useObserver(callback, deps)
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `callback` | `function` | Function to run on change |
+| `deps` | `function \| string \| array` | State path(s) to watch |
+
+### Callback Parameters
+
+```javascript
+useObserver((newValue, oldValue) => {
+  console.debug('Changed:', newValue);
+}, [state.key]);
+```
+
+### Auto-Discovery Mode
+
+When `deps` is omitted, useObserver automatically discovers all state properties accessed inside the callback:
+
+```javascript
+// No deps needed - magic auto-discovery!
+useObserver(() => {
+  // Automatically tracks state.user, state.items, state.counter
+  console.log(state.user.name, state.items.length, state.counter);
+});
+```
+
+Returns a cleanup function:
+
+## useObserver vs observer
+
+| Feature | observer | useObserver |
+| ------- | -------- | ----------- |
+| Framework | Vanilla JS | React |
+| Auto-cleanup | Manual | Auto |
+| React lifecycle | No | Yes |
+
+---
+
+## Common Patterns
+
+### Sync with useState
+
+```javascript
+function MyComponent() {
+  const [data, setData] = useState(null);
+
+  useObserver((newVal) => {
+    setData(newVal);
+  }, [state.data]);
+
+  return <div>{data}</div>;
+}
+```
+
+### Multiple Watchers
+
+```javascript
+}, [state.a, state.b]);
+```
+
+---
+
+## Best Practices
+
+1. Always use in React components
+2. Use auto-discovery for simpler code: `useObserver(() => { ... })`
+3. No manual cleanup needed - returns cleanup function automatically
+4. Use with state for reactive UI
+5. Check console for auto-discovery logs

package/examples/basic.ts

@@ -0,0 +1,75 @@
+/**
+ * Memorio Basic Example
+ *
+ * This example shows the fundamental features of Memorio:
+ * - State management
+ * - Store (localStorage)
+ * - Session storage
+ *
+ * Run: npx ts-node examples/basic.ts
+ */
+
+import '../index'
+
+// ============================================
+// STATE - In-memory reactive state
+// ============================================
+
+// Set some state values
+state.name = 'Mario'
+state.age = 30
+state.isActive = true
+state.profile = {
+  email: 'mario@example.com',
+  avatar: 'https://example.com/mario.png'
+}
+
+// Get state values
+console.log('Name:', state.name)
+console.log('Age:', state.age)
+console.log('Profile:', state.profile)
+
+// List all states
+console.log('All states:', state.list)
+
+// ============================================
+// STORE - Persistent localStorage
+// ============================================
+
+// Save to localStorage
+store.set('username', 'mario')
+store.set('preferences', { theme: 'dark', language: 'en' })
+store.set('lastLogin', Date.now())
+
+// Read from localStorage
+console.log('Username:', store.get('username'))
+console.log('Preferences:', store.get('preferences'))
+
+// Get storage size
+console.log('Storage size:', store.size(), 'bytes')
+
+// ============================================
+// SESSION - Temporary session storage
+// ============================================
+
+// Save session data (cleared when tab closes)
+session.set('token', 'abc123xyz')
+session.set('userId', 42)
+
+// Read session data
+console.log('Token:', session.get('token'))
+console.log('User ID:', session.get('userId'))
+
+// ============================================
+// CLEANUP
+// ============================================
+
+// Clear specific items
+store.remove('username')
+session.remove('token')
+
+// Clear all
+store.removeAll()
+session.removeAll()
+
+console.log('Example complete!')