# 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(
  () => {
    console.debug('Changed:', state.key);
  }, [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.debug(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