191 lines
No EOL
4.3 KiB
Markdown
191 lines
No EOL
4.3 KiB
Markdown
# @stock-bot/event-bus
|
|
|
|
Lightweight event bus for inter-service communication in the Stock Bot platform.
|
|
|
|
## Overview
|
|
|
|
This library provides a simple pub/sub event system using Redis, designed for real-time event distribution between microservices. It focuses on simplicity and reliability for event-driven communication.
|
|
|
|
## Features
|
|
|
|
- Simple pub/sub pattern using Redis
|
|
- Automatic reconnection and resubscription
|
|
- Local event emission (works even without Redis)
|
|
- TypeScript support with predefined trading event types
|
|
- Lightweight with minimal dependencies
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
bun add @stock-bot/event-bus
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Setup
|
|
|
|
```typescript
|
|
import { createEventBus, TradingEventType } from '@stock-bot/event-bus';
|
|
|
|
const eventBus = createEventBus({
|
|
serviceName: 'data-service',
|
|
redisConfig: {
|
|
host: 'localhost',
|
|
port: 6379,
|
|
},
|
|
enableLogging: true,
|
|
});
|
|
|
|
// Wait for connection
|
|
await eventBus.waitForConnection();
|
|
```
|
|
|
|
### Publishing Events
|
|
|
|
```typescript
|
|
// Publish a price update
|
|
await eventBus.publish(TradingEventType.PRICE_UPDATE, {
|
|
symbol: 'AAPL',
|
|
price: 150.25,
|
|
volume: 1000000,
|
|
timestamp: Date.now(),
|
|
});
|
|
|
|
// Publish with metadata
|
|
await eventBus.publish(TradingEventType.ORDER_FILLED,
|
|
{
|
|
orderId: '12345',
|
|
symbol: 'TSLA',
|
|
side: 'buy',
|
|
quantity: 100,
|
|
price: 250.50,
|
|
},
|
|
{ source: 'ib-gateway', region: 'us' }
|
|
);
|
|
```
|
|
|
|
### Subscribing to Events
|
|
|
|
```typescript
|
|
// Subscribe to price updates
|
|
await eventBus.subscribe(TradingEventType.PRICE_UPDATE, async (message) => {
|
|
console.log(`Price update for ${message.data.symbol}: $${message.data.price}`);
|
|
});
|
|
|
|
// Subscribe to order events
|
|
await eventBus.subscribe(TradingEventType.ORDER_FILLED, async (message) => {
|
|
const { orderId, symbol, quantity, price } = message.data;
|
|
console.log(`Order ${orderId} filled: ${quantity} ${symbol} @ $${price}`);
|
|
});
|
|
```
|
|
|
|
### Event Types
|
|
|
|
The library includes predefined event types for common trading operations:
|
|
|
|
```typescript
|
|
enum TradingEventType {
|
|
// Market data events
|
|
PRICE_UPDATE = 'market.price.update',
|
|
ORDERBOOK_UPDATE = 'market.orderbook.update',
|
|
TRADE_EXECUTED = 'market.trade.executed',
|
|
|
|
// Order events
|
|
ORDER_CREATED = 'order.created',
|
|
ORDER_FILLED = 'order.filled',
|
|
ORDER_CANCELLED = 'order.cancelled',
|
|
ORDER_REJECTED = 'order.rejected',
|
|
|
|
// Position events
|
|
POSITION_OPENED = 'position.opened',
|
|
POSITION_CLOSED = 'position.closed',
|
|
POSITION_UPDATED = 'position.updated',
|
|
|
|
// Strategy events
|
|
STRATEGY_SIGNAL = 'strategy.signal',
|
|
STRATEGY_STARTED = 'strategy.started',
|
|
STRATEGY_STOPPED = 'strategy.stopped',
|
|
|
|
// Risk events
|
|
RISK_LIMIT_BREACH = 'risk.limit.breach',
|
|
RISK_WARNING = 'risk.warning',
|
|
|
|
// System events
|
|
SERVICE_STARTED = 'system.service.started',
|
|
SERVICE_STOPPED = 'system.service.stopped',
|
|
SERVICE_ERROR = 'system.service.error',
|
|
}
|
|
```
|
|
|
|
### Typed Events
|
|
|
|
Use TypeScript generics for type-safe event handling:
|
|
|
|
```typescript
|
|
import type { PriceUpdateEvent, OrderEvent } from '@stock-bot/event-bus';
|
|
|
|
// Type-safe subscription
|
|
await eventBus.subscribe<PriceUpdateEvent>(
|
|
TradingEventType.PRICE_UPDATE,
|
|
async (message) => {
|
|
// message.data is typed as PriceUpdateEvent
|
|
const { symbol, price, volume } = message.data;
|
|
}
|
|
);
|
|
```
|
|
|
|
### Cleanup
|
|
|
|
```typescript
|
|
// Unsubscribe from specific event
|
|
await eventBus.unsubscribe(TradingEventType.PRICE_UPDATE);
|
|
|
|
// Close all connections
|
|
await eventBus.close();
|
|
```
|
|
|
|
## Architecture Notes
|
|
|
|
This library is designed for lightweight, real-time event distribution. For reliable job processing, retries, and persistence, use the `@stock-bot/queue` library with BullMQ instead.
|
|
|
|
### When to Use Event Bus
|
|
|
|
- Real-time notifications (price updates, trade executions)
|
|
- Service coordination (strategy signals, risk alerts)
|
|
- System monitoring (service status, errors)
|
|
|
|
### When to Use Queue
|
|
|
|
- Data processing jobs
|
|
- Batch operations
|
|
- Tasks requiring persistence and retries
|
|
- Scheduled operations
|
|
|
|
## Error Handling
|
|
|
|
The event bus handles connection failures gracefully:
|
|
|
|
```typescript
|
|
try {
|
|
await eventBus.publish(TradingEventType.PRICE_UPDATE, data);
|
|
} catch (error) {
|
|
// Event will still be emitted locally
|
|
console.error('Failed to publish to Redis:', error);
|
|
}
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Build
|
|
bun run build
|
|
|
|
# Run tests
|
|
bun test
|
|
|
|
# Clean build artifacts
|
|
bun run clean
|
|
``` |