https://github.com/andreasnicolaou/reactive-event-source
A lightweight reactive wrapper around EventSource using RxJS, providing automatic reconnection with backoff and jitter.
https://github.com/andreasnicolaou/reactive-event-source
Last synced: 7 months ago
JSON representation
A lightweight reactive wrapper around EventSource using RxJS, providing automatic reconnection with backoff and jitter.
- Host: GitHub
- URL: https://github.com/andreasnicolaou/reactive-event-source
- Owner: andreasnicolaou
- License: mit
- Created: 2025-04-17T08:04:05.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-05-12T07:41:09.000Z (8 months ago)
- Last Synced: 2025-05-12T13:04:13.310Z (7 months ago)
- Language: TypeScript
- Size: 679 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-angular - reactive-event-source - Lightweight RxJS-based EventSource wrapper with auto-reconnect, leak prevention, and reactive state management. (Underlying Technologies / RxJS)
- awesome-angular - reactive-event-source - Lightweight RxJS-based EventSource wrapper with auto-reconnect, leak prevention, and reactive state management. (Underlying Technologies / RxJS)
README
# reactive-event-source
A lightweight reactive wrapper around EventSource using RxJS, providing automatic reconnection and buffering.
## Features
- Automatic reconnection with exponential backoff
- Type-safe event handling
- Buffered events (never miss the last message)
- Clean RxJS API with no callback hell
- Configurable retry strategies
## Installation
You can install the package via npm:
```bash
npm install @andreasnicolaou/reactive-event-source
```
## Usage
```ts
import { ReactiveEventSource } from '@andreasnicolaou/reactive-event-source';
const eventSource = new ReactiveEventSource('https://api.example.com/stream');
// Subscribe to standard events
eventSource.on('open').subscribe(() => console.log('Connected'));
eventSource.on('error').subscribe((err) => console.error('Error:', err));
eventSource.on('update').subscribe((event) => {
console.log('New update:', event.data);
});
// Close when done
eventSource.close();
```
## API
### Constructor
| Signature | Description |
| ------------------------------------------------------------------------------------ | ------------------------------------ |
| `new ReactiveEventSource(url: string \| URL, options?: Partial)` | Creates a new SSE connection manager |
### Options
| Property | Type | Default | Description |
| ----------------- | --------- | ------- | --------------------------------- |
| `maxRetries` | `number` | `3` | Maximum retry attempts on failure |
| `initialDelay` | `number` | `1000` | Initial retry delay in ms |
| `maxDelay` | `number` | `10000` | Maximum retry delay in ms |
| `withCredentials` | `boolean` | `false` | Send cookies with requests |
### Methods
| Method | Returns | Description |
| ------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `.on(eventType: string = 'message')` | `Observable` | Returns hot observable that:
• Buffers last event
• Auto-reconnects
• Completes on close |
| `.close()` | `void` | Closes connection and cleans up resources |
### Properties
| Property | Type | Values | Description |
| ------------------ | --------- | ------------------------------------------- | ----------------------------------------------------------------------------------- |
| `.readyState` | `number` | `0`: CONNECTING
`1`: OPEN
`2`: CLOSED | Current connection state. Automatically updates during reconnections. |
| `.withCredentials` | `boolean` | `true`/`false` | Indicates if credentials are sent with requests (set at construction) |
| `.URL` | `string` | - | Readonly resolved endpoint URL. Returns string even if constructed with URL object. |
### Observable Behavior
• Buffers last event (ReplaySubject)
• Automatic reconnection
• Completes when connection closes
• Shared between subscribers
### Connection States
| State | Value | Description |
| ---------- | ----- | ----------------------- |
| CONNECTING | `0` | Establishing connection |
| OPEN | `1` | Connection active |
| CLOSED | `2` | Connection terminated |
## Polyfill for Node.js / Legacy Environments
This library depends on the EventSource API, which is available in most modern browsers. If you're running in an environment where EventSource is not defined (such as Node.js), you can globally provide a compatible implementation:
```ts
// Only do this once, at the top level of your application
globalThis.EventSource = /* your EventSource-compatible implementation */;
```
## Contributing
Contributions are welcome! If you encounter issues or have ideas to enhance the library, feel free to submit an issue or pull request.