memorio 4.3.2 → 4.4.0

package/llms.txt

@@ -19,7 +19,7 @@ Memorio provides 6 storage modules plus utilities:
 | `session` | sessionStorage | Dies with browser tab |
 | `cache` | In-memory cache | Fastest read, no persistence |
 | `idb` | IndexedDB | Structured, async, persistent (browser-only) |
-| `observer` | Object watcher | Legacy, deprecated |
+| `observer` | Object watcher | Legacy |
 | `useObserver` | React hook | Auto-discovery of state paths |
 
 ## Quick Start
@@ -33,7 +33,7 @@ state.counter = 0
 
 // Observe changes (React hook)
 useObserver(
-  () => { console.log('counter:', state.counter) },
+  () => { console.debug('counter:', state.counter) },
   [state.counter]
 )
 ```
@@ -54,7 +54,7 @@ state.counter = 0
 const name = state.user.name    // 'Sara'
 
 // List all keys
-console.log(state.list)         // ['user', 'items', 'counter']
+console.debug(state.list)         // ['user', 'items', 'counter']
 
 // Remove one key
 state.remove('items')
@@ -100,10 +100,10 @@ store.removeAll()
 store.clearAll()
 
 // Check size
-console.log(store.size(), 'chars stored')
+console.debug(store.size(), 'chars stored')
 
 // Check if persistent (real localStorage vs memory fallback)
-console.log(store.isPersistent)  // true → real localStorage
+console.debug(store.isPersistent)  // true → real localStorage
 
 // Estimate quota usage (returns [0, 0] for localStorage)
 await store.quota()  // [usage, quota] in KB
@@ -136,10 +136,10 @@ session.removeAll()
 session.clearAll()
 
 // Check size
-console.log(session.size(), 'chars stored')
+console.debug(session.size(), 'chars stored')
 
 // Check if persistent
-console.log(session.isPersistent)
+console.debug(session.isPersistent)
 ```
 
 ### `cache` — In-Memory Cache
@@ -215,14 +215,14 @@ const [usage, quota] = await idb.db.quota()
 
 **Note:** In Node.js/Deno, `idb` is disabled with a warning. Use `store` or `session` instead.
 
-### `observer` — Object Watcher (DEPRECATED)
+### `observer` — Object Watcher
 
 Legacy observer API. Use `useObserver` instead.
 
 ```javascript
 // Listen to state changes
 observer('state.user', (newVal, oldVal) => {
-  console.log('user changed:', newVal, oldVal)
+  console.debug('user changed:', newVal, oldVal)
 })
 
 // Toggle listening (no callback)
@@ -232,7 +232,7 @@ observer('state.counter')
 observer.remove('state.user')
 
 // List all observers
-console.log(observer.list)
+console.debug(observer.list)
 
 // Remove all observers
 observer.removeAll()
@@ -251,12 +251,12 @@ function Counter() {
 
   // Auto-discovery mode (no deps)
   useObserver(() => {
-    console.log('counter:', state.counter)
+    console.debug('counter:', state.counter)
   }, state.counter)
 
   // Explicit deps mode
   useObserver(
-    () => { console.log('user:', state.user) },
+    () => { console.debug('user:', state.user) },
     [state.user]
   )
 
@@ -308,8 +308,8 @@ Track every state change with timestamps.
 
 ```javascript
 // Configure logger
-memorio.logger.configure({ 
-  enabled: true, 
+memorio.logger.configure({
+  enabled: true,
   logToConsole: true,
   modules: ['state', 'store', 'session', 'cache', 'idb']
 })
@@ -345,7 +345,7 @@ memorio.createContext('tenant-name')
 memorio.listContexts()
 memorio.deleteContext('context-id')
 memorio.isolate('tenant-name')  // alias for createContext
-```
+```
 
 ## Cross-Platform Support
 
@@ -397,7 +397,7 @@ memorio.dispatch.set('custom:event', { detail: { data: 'value' } })
 
 // Listen for an event
 memorio.dispatch.listen('custom:event', (e) => {
-  console.log('Event triggered:', e.detail)
+  console.debug('Event triggered:', e.detail)
 })
 
 // Remove listener

package/markdown/CHANGELOG.md

@@ -56,7 +56,7 @@ All notable changes to this project will be documented in this file.
 
 ### 📝 Documentation Updates
 
-- `docs/README.md`: replaced `console.log` with `console.debug` in usage examples; fixed `esbuild` badge → `tsup`
+- `docs/README.md`: replaced `console.debug` with `console.debug` in usage examples; fixed `esbuild` badge → `tsup`
 - `.github/CHANGELOG.md`: restructured with fix / security / changed sections
 - `.github/HISTORY.md`: complete rewrite through v3.0.2
 - `.github/SECURITY.md`: NIST/NSA standard + OWASP Top 10 mapping

package/markdown/DISPATCH.md

@@ -0,0 +1,168 @@
+# Dispatch - Memorio
+
+> ⚛️ **Vanilla JS**: This is for non-React applications. For React, use [`useObserver`](USEOBSERVER.md).
+
+`memorio.dispatch` is an event system for vanilla JavaScript applications. It enables pub/sub patterns without React hooks.
+
+## Installation
+
+```bash
+npm install memorio
+```
+
+```javascript
+import 'memorio';
+```
+
+---
+
+## Quick Examples
+
+### Example 1: Basic Event Listening
+
+```javascript
+// Listen for an event
+memorio.dispatch.listen('my:event', (event) => {
+  console.debug('Event triggered:', event.detail);
+});
+
+// Trigger the event
+memorio.dispatch.set('my:event', { detail: { data: 'Hello World' } });
+// Output: "Event triggered: { data: 'Hello World' }"
+```
+
+### Example 2: State Reactivity (Vanilla JS)
+
+```javascript
+// React to state changes without React
+memorio.dispatch.listen('state.counter', (event) => {
+  console.debug('Counter is now:', event.detail);
+});
+
+// Update state
+state.counter = 1;
+// Output: "Counter is now: 1"
+
+state.counter = 5;
+// Output: "Counter is now: 5"
+```
+
+### Example 3: Remove Listener
+
+```javascript
+// Remove a specific event listener
+memorio.dispatch.remove('my:event');
+
+// Or remove all listeners for state changes
+memorio.dispatch.remove('state.user');
+```
+
+---
+
+## API Reference
+
+### memorio.dispatch.set(name, value)
+
+Dispatches a custom event with the specified name and value.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Event name (e.g., `'my:event'`, `'state.counter'`) |
+| `value` | `object` | Object with `detail` property (default: `{}`) |
+
+```javascript
+memorio.dispatch.set('custom:event', { detail: { data: 'value' } });
+```
+
+### memorio.dispatch.listen(name, callback)
+
+Listens for the specified event and executes the callback when triggered.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Event name to listen for |
+| `callback` | `function` | Function called with the event object |
+
+```javascript
+memorio.dispatch.listen('state.user', (event) => {
+  console.debug('User changed:', event.detail);
+});
+```
+
+### memorio.dispatch.remove(name)
+
+Removes the event listener for the specified event name.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | Event name to stop listening |
+
+```javascript
+memorio.dispatch.remove('state.counter');
+```
+
+---
+
+## Common Patterns
+
+### Form Validation
+
+```javascript
+memorio.dispatch.listen('state.form.email', (event) => {
+  const email = event.detail;
+  const isValid = email.includes('@');
+  state.form.isValid = isValid;
+});
+```
+
+### Analytics Tracking
+
+```javascript
+memorio.dispatch.listen('state.page', (event) => {
+  const page = event.detail;
+  analytics.track('page_view', { page });
+});
+```
+
+### Auto-save
+
+```javascript
+memorio.dispatch.listen('state.draft', (event) => {
+  const content = event.detail;
+  store.set('autosave', content);
+});
+```
+
+### Multiple Listeners
+
+```javascript
+// Listen for multiple state changes
+memorio.dispatch.listen('state.user', (e) => console.log('User:', e.detail));
+memorio.dispatch.listen('state.settings', (e) => console.log('Settings:', e.detail));
+```
+
+---
+
+## Migration from observer()
+
+The `observer()` Replace it with `memorio.dispatch.listen()`:
+
+```javascript
+observer('state.counter', (newValue) => {
+  console.debug('Counter:', newValue);
+});
+
+// NEW (recommended for vanilla JS)
+memorio.dispatch.listen('state.counter', (event) => {
+  console.debug('Counter:', event.detail);
+});
+```
+
+---
+
+## Best Practices
+
+1. Use specific event names: `'state.user.name'` not `'state'`
+2. Clean up listeners when no longer needed with `memorio.dispatch.remove()`
+3. Use `event.detail` to access the value
+4. For React applications, use [`useObserver`](USEOBSERVER.md) instead

package/markdown/OBSERVER.md

@@ -1,7 +1,5 @@
 # Observer - Memorio
 
-> ⚠️ **DEPRECATED**: This function is deprecated and will be removed in future versions. Please use [`useObserver`](USEOBSERVER.md) instead.
-
 Observer lets you react to state changes. When a state key changes, your callback function runs.
 
 ## Installation
@@ -21,9 +19,6 @@ import 'memorio';
 ### Example 1: Basic Usage
 
 ```javascript
-// Simple observer (DEPRECATED - use useObserver instead)
-console.warn('observer() is deprecated. Please use useObserver() for React or memorio.dispatch for vanilla JS.');
-
 observer('state.counter', (newValue) => {
   console.debug('Counter is now:', newValue);
 });
@@ -35,8 +30,6 @@ state.counter = 5;
 // Output: "Counter is now: 5"
 ```
 
-> **Note**: For new projects, use [`useObserver`](USEOBSERVER.md) for React or [`memorio.dispatch`](SUMMARY.md) for vanilla JS.
-
 ### Example 2: Intermediate
 
 ```javascript
@@ -55,9 +48,8 @@ state.user = { name: 'Luigi' };
 ### Example 3: Advanced
 
 ```javascript
-// Multiple observers
-const obs1 = observer('state.data', handler1);
-const obs2 = observer('state.data', handler2);
+// Multiple callbacks for same path
+observer('state.data', [handler1, handler2]);
 
 // List all observers
 console.debug(observer.list);
@@ -68,18 +60,45 @@ 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)
+### observer(path, callback, option)
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `path` | `string` | State path to watch (e.g., `'state.counter'`) |
-| `callback` | `function` | Function called on change |
+| `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
 
@@ -102,6 +121,7 @@ observer('state.key', (newValue, oldValue) => {
 |--------|------------|-------------|
 | `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) |
 
 ---
 

package/markdown/USEOBSERVER.md

@@ -24,6 +24,7 @@ import 'memorio';
 import 'memorio';
 
 function Counter() {
+  // Direct values work! ✅
   useObserver(() => {
     console.debug('Counter changed:', state.counter);
   }, [state.counter]);
@@ -63,14 +64,23 @@ function UserProfile() {
 ### Example 3: Advanced
 
 ```javascript
-// Multiple watchers with array
+// Multiple watchers with array - works with direct values
 function MultiWatch() {
   useObserver(() => {
     console.debug('A or B changed:', state.a, state.b);
-  }, [state.a, state.b]);
-
+  }, [state.a, state.b]); // Direct values work!
+  
   return <div>{state.a} - {state.b}</div>;
 }
+
+// With string path (for store)
+function StoreWatcher() {
+  useObserver(() => {
+    console.debug('Store changed');
+  }, 'store.userPreferences');
+
+  return <div />;
+}
 ```
 // With string path (for store)
 function StoreWatcher() {
@@ -91,15 +101,49 @@ function StoreWatcher() {
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
 | `callback` | `function` | Function to run on change |
-| `deps` | `function \| string \| array` | State path(s) to watch |
+| `deps` | `function \| string \| array \| proxy` | State path(s) to watch. Supports: |
+| | | - Direct values: `state.counter` |
+| | | - String paths: `'state.counter'` |
+| | | - Arrow functions: `() => state.counter` |
+| | | - Arrays: `[state.a, state.b]` or `['state.a', 'state.b']` |
+| | | - Optional chaining: `[state?.one]` |
+
+### Primitive Values
+
+Direct primitive values are now fully supported:
+
+```javascript
+// Direct values work with primitives ✅
+useObserver(() => { console.debug('changed') }, [state.counter])
+
+// Arrays of primitives work ✅
+useObserver(() => { console.log(state.a, state.b) }, [state.a, state.b])
+
+// Optional chaining works ✅
+useObserver(() => { console.log(state?.one) }, [state?.one])
+
+// Strings still work ✅
+useObserver(() => { console.debug('changed') }, ['state.counter'])
+
+// Functions still work ✅
+useObserver(() => { console.debug('changed') }, [() => state.counter])
+```
 
 ### Callback Parameters
 
 ```javascript
+// Single value (no array needed)
 useObserver(
   () => {
     console.debug('Changed:', state.key);
-  }, [state.key]
+  }, state.key  // Single value works!
+);
+
+// Array of values
+useObserver(
+  () => {
+    console.debug('Changed:', state.key);
+  }, [state.key]  // Array also works!
 );
 ```
 
@@ -129,24 +173,79 @@ Returns a cleanup function:
 
 ## Common Patterns
 
-### Sync with useState
+### Sync with useState (Recommended for Primitives)
 
 ```javascript
-function MyComponent() {
-  const [data, setData] = useState(null);
+function CounterComponent() {
+  // Sync memorio state with React state
+  const [counter, setCounter] = useState(state.counter)
+  
+  // React useEffect works correctly with primitive values
+  useEffect(() => {
+    console.log('Counter changed:', counter)
+  }, [counter])
+  
+  // Direct values now work with primitives!
+  useObserver(() => {
+    setCounter(state.counter)
+  }, [state.counter])  // ✅ Works now!
+  
+  return (
+    <div>
+      <button onClick={() => { state.counter++ }}>Increment</button>
+      <span>{counter}</span>
+    </div>
+  )
+}
+```
 
-  useObserver((newVal) => {
-    setData(newVal);
-  }, [state.data]);
+### Safe Access with Optional Chaining (Protection)
 
-  return <div>{data}</div>;
+```javascript
+// Optional chaining is supported - protects against errors
+useObserver(() => {
+  if (test?.one) {
+    console.log(test.one)
+  }
+}, [test?.one])
+
+// Works with objects
+function SafeComponent() {
+  const [test, setTest] = useState(state.test)
+  
+  useEffect(() => {
+    if (test?.one) {
+      console.log('test.one:', test.one)
+    }
+  }, [test?.one])
+  
+  useObserver(() => {
+    if (state.test?.one) {
+      setTest(state.test)
+    }
+  }, ['state.test.one'])
+  
+  return <div>{test?.one || 'Loading...'}</div>
 }
 ```
 
 ### Multiple Watchers
 
 ```javascript
-}, [state.a, state.b]);
+// Watch multiple properties with strings
+useObserver(() => {
+  console.log(state.a, state.b)
+}, ['state.a', 'state.b'])
+
+// Watch multiple properties with functions
+useObserver(() => {
+  console.log(state.a, state.b)
+}, [() => state.a, () => state.b])
+
+// Watch with auto-discovery
+useObserver(() => {
+  console.log(state.a, state.b) // Automatically tracks both
+}, [])
 ```
 
 ---

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorio",
   "codeName": "memorio",
-  "version": "4.3.2",
+  "version": "4.4.0",
   "description": "Memorio, State + Observer, Store and iDB for an easy life - Cross-platform compatible",
   "main": "./index.cjs",
   "browser": "./index.cjs",
@@ -55,14 +55,11 @@
     "url": "https://dario.passariello.ca/",
     "email": "dariopassariello@gmail.com"
   },
-  "dependencies": {
-    "baseline-browser-mapping": "2.10.43"
+  "resolutions": {
+    "esbuild": "^0.25.0"
   },
   "overrides": {
-    "object-assign": "npm:@socketregistry/object-assign@^1"
-  },
-  "resolutions": {
-    "object-assign": "npm:@socketregistry/object-assign@^1"
+    "esbuild": "^0.25.0"
   },
   "exports": {
     ".": {

package/types/memorio.d.ts

@@ -29,6 +29,9 @@ interface _memorio {
   _tracking?: boolean
   _trackedPaths?: Set<string>
   _locked?: boolean
+  _lastAccessedPath?: string
+  _stateVersion?: number
+  _propertyAccessLog?: string[]
   // Platform detection
   isBrowser: () => boolean
   isNode: () => boolean