# 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