michaelschiemer/docs/modules/event-bus.md

# Event Bus Module

**Centralized Event System for Cross-Module Communication**

The Event Bus Module provides a pub/sub event system for decoupled communication between modules, components, and services.

---

## Features

- **Pub/Sub Pattern** - Publish and subscribe to events
- **Namespaced Events** - Organize events with namespaces (e.g., 'user:created')
- **Event Filtering** - Filter events by data or conditions
- **Event History** - Track event history for debugging
- **Integration with LiveComponents** - Works seamlessly with LiveComponents
- **Integration with SSE** - Integrate with Server-Sent Events
- **Wildcard Support** - Subscribe to event patterns
- **Middleware Support** - Transform or filter events with middleware

---

## Quick Start

### Basic Usage

```javascript
import { EventBus } from './modules/event-bus/index.js';

// Create event bus
const bus = EventBus.create();

// Subscribe to an event
const unsubscribe = bus.on('user:created', (user) => {
    console.log('User created:', user);
});

// Emit an event
bus.emit('user:created', { id: 1, name: 'John' });

// Unsubscribe
unsubscribe();
```

### Module System Integration

```html
<!-- Enable global event bus -->
<script type="module">
    import { init } from './modules/event-bus/index.js';
    
    init({
        enableHistory: true,
        maxHistorySize: 100
    });
</script>

<!-- Access globally -->
<script>
    // Subscribe
    window.EventBus.on('user:created', (user) => {
        console.log('User created:', user);
    });
    
    // Emit
    window.EventBus.emit('user:created', { id: 1, name: 'John' });
</script>
```

---

## API Reference

### EventBus.create(config)

Create a new EventBus instance.

**Parameters**:
- `config.enableHistory` - Enable event history (default: false)
- `config.maxHistorySize` - Maximum history size (default: 100)
- `config.enableWildcards` - Enable wildcard patterns (default: true)

**Example**:
```javascript
const bus = EventBus.create({
    enableHistory: true,
    maxHistorySize: 50
});
```

### bus.on(eventName, callback, options)

Subscribe to an event.

**Parameters**:
- `eventName` - Event name (supports wildcards: 'user:*', '*')
- `callback` - Callback function: `(data, eventName, options) => void`
- `options.once` - Subscribe only once (default: false)
- `options.priority` - Subscription priority (default: 0)
- `options.filter` - Filter function: `(data, options) => boolean`

**Returns**: Unsubscribe function

**Example**:
```javascript
// Basic subscription
const unsubscribe = bus.on('user:created', (user) => {
    console.log('User created:', user);
});

// Once subscription
bus.once('user:created', (user) => {
    console.log('User created (once):', user);
});

// Priority subscription
bus.on('user:created', (user) => {
    console.log('High priority handler');
}, { priority: 10 });

// Filtered subscription
bus.on('user:created', (user) => {
    console.log('Admin user created');
}, {
    filter: (user) => user.role === 'admin'
});
```

### bus.once(eventName, callback, options)

Subscribe to an event once (auto-unsubscribe after first emission).

**Parameters**: Same as `on()`

**Returns**: Unsubscribe function

### bus.off(eventName, callback)

Unsubscribe from an event.

**Parameters**:
- `eventName` - Event name
- `callback` - Callback function to remove

### bus.emit(eventName, data, options)

Emit an event.

**Parameters**:
- `eventName` - Event name
- `data` - Event data
- `options` - Event options

**Example**:
```javascript
bus.emit('user:created', { id: 1, name: 'John' });
bus.emit('user:updated', { id: 1, name: 'Jane' }, { source: 'api' });
```

### bus.use(middleware)

Add middleware to transform or filter events.

**Parameters**:
- `middleware` - Middleware function: `(eventName, data, options) => data | null | false`

**Example**:
```javascript
// Logging middleware
bus.use((eventName, data, options) => {
    console.log(`Event: ${eventName}`, data);
    return data; // Continue
});

// Filtering middleware
bus.use((eventName, data, options) => {
    if (eventName.startsWith('debug:')) {
        return null; // Block debug events in production
    }
    return data;
});
```

### bus.getHistory(filter)

Get event history.

**Parameters**:
- `filter` - Optional filter (string for event name, or function)

**Returns**: `Array<EventHistoryItem>`

**Example**:
```javascript
// Get all history
const history = bus.getHistory();

// Get history for specific event
const userHistory = bus.getHistory('user:created');

// Get history with custom filter
const recentHistory = bus.getHistory((item) => {
    return Date.now() - item.timestamp < 60000; // Last minute
});
```

---

## Namespaced Events

Organize events with namespaces:

```javascript
// Subscribe to namespace
bus.on('user:*', (data, eventName) => {
    console.log(`User event: ${eventName}`, data);
});

// Emit namespaced events
bus.emit('user:created', { id: 1 });
bus.emit('user:updated', { id: 1 });
bus.emit('user:deleted', { id: 1 });
```

---

## Wildcard Support

Subscribe to event patterns:

```javascript
// Subscribe to all events
bus.on('*', (data, eventName) => {
    console.log(`Event: ${eventName}`, data);
});

// Subscribe to pattern
bus.on('user:*', (data, eventName) => {
    console.log(`User event: ${eventName}`, data);
});
```

---

## Integration with LiveComponents

```javascript
import { EventBus } from './modules/event-bus/index.js';
import { LiveComponentManager } from './modules/livecomponent/index.js';

const bus = EventBus.create();
const lcManager = LiveComponentManager.getInstance();

// Listen for LiveComponent events
bus.on('livecomponent:action-executed', (data) => {
    console.log('Action executed:', data);
});

// Emit LiveComponent events
lcManager.on('action-executed', (componentId, actionName, params) => {
    bus.emit('livecomponent:action-executed', {
        componentId,
        actionName,
        params
    });
});
```

---

## Integration with SSE

```javascript
import { EventBus } from './modules/event-bus/index.js';
import { SseClient } from './modules/sse/index.js';

const bus = EventBus.create();
const sse = new SseClient(['updates']);

// Forward SSE messages to event bus
sse.on('message', (data) => {
    bus.emit('sse:message', data);
});

// Listen for SSE events
bus.on('sse:message', (data) => {
    console.log('SSE message:', data);
});
```

---

## Use Cases

### Module Communication

```javascript
// Module A
const bus = EventBus.create();
bus.emit('module-a:data-ready', { data: [...] });

// Module B
bus.on('module-a:data-ready', (data) => {
    processData(data);
});
```

### Component Communication

```javascript
// Component A
bus.emit('component:user-selected', { userId: 123 });

// Component B
bus.on('component:user-selected', (data) => {
    loadUserDetails(data.userId);
});
```

### Global Notifications

```javascript
// Emit notification
bus.emit('notification:show', {
    type: 'success',
    message: 'Operation completed'
});

// Listen for notifications
bus.on('notification:show', (data) => {
    showNotification(data.type, data.message);
});
```

### Analytics Events

```javascript
// Track events
bus.on('*', (data, eventName) => {
    // Send to analytics
    analytics.track(eventName, data);
});
```

---

## Best Practices

1. **Use Namespaces** - Organize events with namespaces (e.g., 'user:created')
2. **Document Events** - Document all events and their data structures
3. **Use TypeScript** - Use TypeScript definitions for type safety
4. **Clean Up Subscriptions** - Always unsubscribe when done
5. **Use Middleware** - Use middleware for cross-cutting concerns (logging, analytics)

---

## Browser Support

- **Chrome/Edge**: 90+
- **Firefox**: 88+
- **Safari**: 14+
- **Mobile**: iOS 14+, Android Chrome 90+

**Required Features**:
- ES2020 JavaScript
- Map and Set support

---

**Next**: Continue with Phase 2 modules →