memorio 2.7.4 → 2.9.0

package/docs/markdown/STORE.md

@@ -0,0 +1,161 @@
+# 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';
+```
+
+---
+
+## 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
+
+// Check if using real persistence
+console.log(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.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 |
+
+### 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/docs/markdown/USEOBSERVER.md

@@ -0,0 +1,158 @@
+# useObserver - Memorio
+
+> ⚛️ **React Only**: This is a React hook and only works within React components
+
+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 '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

@@ -10,7 +10,7 @@
  * Run: npx ts-node examples/basic.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // PLATFORM DETECTION

package/examples/cache.ts

@@ -7,7 +7,7 @@
  * Run: npx ts-node examples/cache.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // BASIC CACHE OPERATIONS

package/examples/idb.ts

@@ -7,7 +7,7 @@
  * Run: npx ts-node examples/idb.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // CHECK SUPPORT

package/examples/node-server.ts

@@ -7,7 +7,7 @@
  * Run: npx ts-node examples/node-server.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // 1. BASIC USAGE

package/examples/observer.ts

@@ -7,7 +7,7 @@
  * Run: npx ts-node examples/observer.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // SIMPLE OBSERVER

package/examples/platform.ts

@@ -9,7 +9,7 @@
  * Run: npx ts-node examples/platform.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // PLATFORM DETECTION

package/examples/react-app.tsx

@@ -8,7 +8,7 @@
  */
 
 import React, { useState, useEffect } from 'react'
-import '../index'
+import 'memorio'
 
 // ============================================
 // 1. SETUP - Import once at app start

package/examples/session-advanced.ts

@@ -7,7 +7,7 @@
  * Run: npx ts-node examples/session-advanced.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // CHECK PERSISTENCE

package/examples/state-advanced.ts

@@ -6,7 +6,7 @@
  * Run: npx ts-node examples/state-advanced.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // NESTED OBJECTS

package/examples/store-advanced.ts

@@ -6,7 +6,7 @@
  * Run: npx ts-node examples/store-advanced.ts
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // CHECK PERSISTENCE

package/examples/{useObserver.ts → useObserver.tsx}

@@ -8,7 +8,7 @@
  * Run in a React environment.
  */
 
-import '../index'
+import 'memorio'
 
 // ============================================
 // BASIC USEOBSERVER
@@ -22,7 +22,7 @@ function Counter() {
     console.debug('Count changed:', state.count)
   }, [state.count])
 
-  return <div>{ state.count } </div>
+  return <div>{state.count} </div>
 }
 
 // ============================================
@@ -35,7 +35,7 @@ function UserProfile() {
     console.debug('User or theme changed')
   }, [state.user, state.theme])
 
-  return <div>{ state.user.name } </div>
+  return <div>{state.user.name} </div>
 }
 
 // ============================================
@@ -49,7 +49,7 @@ function AutoDiscovery() {
     console.debug('Changed:', state.user.name, state.items.length, state.count)
   })
 
-  return <div>{ state.user.name } </div>
+  return <div>{state.user.name} </div>
 }
 
 // ============================================
@@ -64,7 +64,7 @@ function SyncedComponent() {
     setLocalData(newValue)
   }, [state.data])
 
-  return <div>{ localData } </div>
+  return <div>{localData} </div>
 }
 
 // ============================================
@@ -72,7 +72,7 @@ function SyncedComponent() {
 // ============================================
 
 // Real-world React component example:
-import { useObserver } from 'memorio'
+import 'memorio'
 
 function TodoApp() {
   // Track todos
@@ -105,36 +105,36 @@ function TodoApp() {
 
   return (
     <div>
-    <select
-        value= { state.filter }
-  onChange = { e => state.filter = e.target.value }
-    >
-    <option value="all" > All </option>
-      < option value = "done" > Done </option>
-        < option value = "todo" > Todo </option>
-          </select>
-          <ul>
-  {
-    filteredTodos.map((todo, i) => (
-      <li
-            key= { i }
-            onClick = {() => toggleTodo(i)}
-  style = {{ textDecoration: todo.done ? 'line-through' : 'none' }
-}
-          >
-  { todo.text }
-  </li>
-        ))}
-</ul>
-  < input
-onKeyDown = { e => {
-  if (e.key === 'Enter') {
-    addTodo(e.target.value)
-    e.target.value = ''
-  }
-}}
+      <select
+        value={state.filter}
+        onChange={e => state.filter = e.target.value}
+      >
+        <option value="all" > All </option>
+        < option value="done" > Done </option>
+        < option value="todo" > Todo </option>
+      </select>
+      <ul>
+        {
+          filteredTodos.map((todo, i) => (
+            <li
+              key={i}
+              onClick={() => toggleTodo(i)}
+              style={{ textDecoration: todo.done ? 'line-through' : 'none' }
+              }
+            >
+              {todo.text}
+            </li>
+          ))}
+      </ul>
+      < input
+        onKeyDown={e => {
+          if (e.key === 'Enter') {
+            addTodo(e.target.value)
+            e.target.value = ''
+          }
+        }}
       />
-  </div>
+    </div>
   )
 }