# sse-ts

> A ES6-based flexible Server-Sent Events source; supports GET and POST requests and custom headers to a SSE endpoint

Latest version **1.0.3** (published 2024-03-13) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install sse-ts
pnpm add sse-ts
yarn add sse-ts
bun add sse-ts
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2024-03-13 |
| First published | 2021-12-18 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 24.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Mukesh Agarwal |
| Maintainers | smartmuki |
| Keywords | sse, server-side-events, server-sent-events, eventsource, sse-ts, sse-es6 |

## Links

- npm: https://www.npmjs.com/package/sse-ts
- Repository: https://github.com/smartmuki/sse-ts
- Issues: https://github.com/smartmuki/sse-ts/issues
- npm.io page: https://npm.io/package/sse-ts

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 1.0.3 (latest) — 2024-03-13
- 1.0.2 — 2023-08-03
- 1.0.1 — 2021-12-18
- 1.0.0 — 2021-12-18

## README

# sse-ts

Forked from `https://github.com/mpetazzoni/sse.js`. 
Made the library strongly typed and added support for ES6 modules. So this library can now be imported as a ES6 module and compiled with TS. 

`sse-ts` is a strongly-typed ES6 module-based flexible `EventSource` replacement for Typescript designed
to consume Server-Sent Events (SSE) streams with more control and
options than the standard `EventSource`. The main limitations of
`EventSource` are that it only supports no-payload GET requests, and
does not support specifying additional custom headers to the HTTP
request. This library solves the problem by providing:
- Support for GET and POST requests to a SSE endpoint
- Support for additional headers that can be passed
- Support for `withCredentials` flag


## Installation
```ts
npm i sse-ts
```
OR
```ts
yarn add sse-ts
```

## Basic usage

The most simple way to use `SSE` is to create the `SSE` object, attach
one or more listeners, and activate the stream:

```ts

import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            method: SSEOptionsMethod.GET
        };


const source = new SSE(backendURL, sseOptions);
source.addEventListener('message', (event: CustomEventType) => {
            const dataEvent = event as CustomEventDataType;
            // Assuming we receive JSON-encoded data payloads:
            var payload = JSON.parse(dataEvent.data);
            console.log(payload);
          });

source.stream();
```

## Events

`SSE` implements the `EventTarget` interface (just like `EventSource`)
and emits fully constructed `Event` objects. The type of the event
corresponds to the Server-Sent Event's _name_, and the event's timestamp
is the UNIX timestamp of the _reception_ of the event.

Additionally, the events will have the following fields if the event type is `CustomEventDataType`:

- `id`: the event ID, if present; `null` otherwise
- `data`: the event data, unparsed

`SSE`, like `EventSource`, will emit the following events:

- `open`, when the first block of data is received from the event
  stream;
- `error`, if an error occurs while making the request;
- `readystatechange`, to notify of a change in the ready state of the
  event source.

Note that all events dispatched by `SSE` will have the event target
initially set to the `SSE` object itself.

## Listening for specific event types

The [Server-Sent Events
specification](https://html.spec.whatwg.org/multipage/comms.html#server-sent-events)
allows for arbitrary event types, as the `event` field of the event. The
default event type is `message`, so you'll most likely want to register
a listener for this kind of events. If you expect another type of
events, simply register your callback with the appropriate event type:

```ts
import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            method: SSEOptionsMethod.GET
        };
        
const source = new SSE(backendURL, sseOptions);
source.addEventListener('status', (event: CustomEventType) => {
        const dataEvent = event as CustomEventDataType;
        console.log('System status is now: ' + dataEvent.data);
        });

        source.stream();
```


## Passing custom headers

```ts
import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            headers: { 'Content-Type': 'application/json', 'api-key': "apiKey" },
            method: SSEOptionsMethod.GET,
        };

const source = new SSE(backendURL, sseOptions);
        
```

## Making a POST request and overriding the HTTP method

To make a HTTP POST request, simply specify a `payload` in the options:

```ts
import { CustomEventDataType, CustomEventType, SSE, SSEOptions, SSEOptionsMethod } from "sse-ts";

const sseOptions: SSEOptions = {
            headers: { 'Content-Type': 'application/json', 'api-key': "apiKey" },
            method: SSEOptionsMethod.POST,
            payload: JSON.stringify({
                foo: "bar"
            })
        };

const source = new SSE(backendURL, sseOptions);
```


## `withCredentials` support

This `EventSource` polyfill supports the `withCredentials` option to
request that the outgoing HTTP request be made with a CORS credentials
mode of `include`, as per the [HTML Living
Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode).

## Options reference

| Name              | Description |
| ----------------- | ----------- |
| `headers`         | A map of additional headers to use on the HTTP request |
| `method`          | (Required) Override HTTP method (GET or POST) |
| `payload`         | The request payload to sent with the request |
| `withCredentials` | If set to `true`, CORS requests will be set to include credentials |

## TODOs and caveats

- Internet Explorer 11 does not support arbitrary values in
  `CustomEvent`s.  A dependency on `custom-event-polyfill` is necessary
  for IE11 compatibility.
- Improve `XmlHttpRequest` error handling and connection states
- Automatically reconnect with `Last-Event-ID`

---
_Source: https://npm.io/package/sse-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._