reactive-event-source

A lightweight, production-ready reactive wrapper around EventSource using RxJS, providing automatic reconnection, memory leak prevention, and reactive state management.

Features

• Automatic reconnection with configurable exponential backoff
• Enhanced timeout handling with race condition prevention
• Memory leak prevention with proper subscription cleanup
• Reactive state tracking with readyState$ observable
• Improved error recovery with state-based retry logic
• Modern build system using Rollup (ESM + UMD bundles)
• TypeScript-first with full type safety
• Simplified API - removed confusing buffer options
• Event buffering using ReplaySubject(1) - never miss the last message
• Clean RxJS API with no callback hell
• Configurable retry strategies
• Browser-optimized - no Node.js dependencies

Installation

Package Managers

# npm
npm install @andreasnicolaou/reactive-event-source

# yarn
yarn add @andreasnicolaou/reactive-event-source

# pnpm
pnpm add @andreasnicolaou/reactive-event-source

Via CDN

For browser usage without a build system, you can include the library directly from a CDN:

<!-- unpkg CDN (latest version, unminified) -->
<script src="https://unpkg.com/@andreasnicolaou/reactive-event-source/dist/index.umd.js"></script>

<!-- unpkg CDN (latest version, minified) -->
<script src="https://unpkg.com/@andreasnicolaou/reactive-event-source/dist/index.umd.min.js"></script>

<!-- jsDelivr CDN (unminified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/reactive-event-source/dist/index.umd.js"></script>

<!-- jsDelivr CDN (minified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/reactive-event-source/dist/index.umd.min.js"></script>

The library will be available as reactiveEventSource on the global scope:

<script>
  const eventSource = new reactiveEventSource.ReactiveEventSource('https://api.example.com/stream');
  eventSource.on('message').subscribe((event) => {
    console.log('Received:', event.data);
  });
</script>

Usage

You can use this library in any modern JavaScript environment:

ESM (ECMAScript Modules)

import { ReactiveEventSource } from '@andreasnicolaou/reactive-event-source';

const eventSource = new ReactiveEventSource('https://api.example.com/stream');
eventSource.on('message').subscribe((event) => {
  console.log('Received:', event.data);
});

CommonJS (Node.js require)

const { ReactiveEventSource } = require('@andreasnicolaou/reactive-event-source');

const eventSource = new ReactiveEventSource('https://api.example.com/stream');
eventSource.on('message').subscribe((event) => {
  console.log('Received:', event.data);
});

UMD (CDN/Browser)

<script src="https://unpkg.com/@andreasnicolaou/reactive-event-source/dist/index.umd.min.js"></script>
<script>
  const { ReactiveEventSource } = reactiveEventSource;
  const eventSource = new ReactiveEventSource('https://api.example.com/stream');
  eventSource.on('message').subscribe((event) => {
    console.log('Received:', event.data);
  });
</script>

API

Constructor

| Signature | Description | | ------------------------------------------------------------------------------------ | ------------------------------------ | | new ReactiveEventSource(url: string \| URL, options?: Partial<EventSourceOptions>) | 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 | | connectionTimeout | number | 15000 | Timeout for initial connection in ms | | withCredentials | boolean | false | Send cookies with requests |

Methods

| Method | Returns | Description | | ------------------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | .on(eventType: string = 'message') | Observable<MessageEvent> | Returns hot observable that:• Buffers last event with ReplaySubject(1)• Auto-reconnects with exponential backoff• Properly cleans up subscriptions• Completes on close | | .close() | void | Closes connection and cleans up all resources (prevents memory leaks) |

Properties

| Property | Type | Values | Description | | ------------------ | -------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------- | | .readyState | number | 0: CONNECTING1: OPEN2: CLOSED | Current connection state getter. Automatically updates during reconnections. | | .readyState$ | Observable<number> | 0: CONNECTING1: OPEN2: CLOSED | Reactive observable that emits connection state changes in real-time. | | .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

✅ Memory Safe: Proper subscription cleanup prevents memory leaks
✅ Event Buffering: Uses ReplaySubject(1) to buffer the last event
✅ Automatic Reconnection: Exponential backoff with configurable limits
✅ Shared Subscriptions: Efficient sharing between multiple subscribers
✅ Reactive State: readyState$ observable for real-time connection monitoring
✅ Clean Completion: All observables complete when connection closes

Connection States

| State | Value | Description | | ---------- | ----- | ----------------------- | | CONNECTING | 0 | Establishing connection | | OPEN | 1 | Connection active | | CLOSED | 2 | Connection terminated |

Error Handling

The library exports a custom EventSourceError class for enhanced error handling:

import { ReactiveEventSource, EventSourceError } from '@andreasnicolaou/reactive-event-source';

const eventSource = new ReactiveEventSource('https://api.example.com/stream');

eventSource.on('error').subscribe((error) => {
  if (error instanceof EventSourceError) {
    console.log('EventSource error:', error.message);
    console.log('Retry attempt:', error.attempt);
  }
});

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:

// 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.