wdullaer/sse-utils

View on GitHub
README.md

Summary

Maintainability
Test Coverage
# SSE Utils
![NPM Version](https://img.shields.io/npm/v/sse-utils.svg)
![Build Status](https://github.com/wdullaer/sse-utils/workflows/sse-utils/badge.svg)
![Dependency Status](https://david-dm.org/wdullaer/sse-utils.svg)
[![Code Climate](https://codeclimate.com/github/wdullaer/sse-utils/badges/gpa.svg)](https://codeclimate.com/github/wdullaer/sse-utils)
[![Test Coverage](https://codeclimate.com/github/wdullaer/sse-utils/badges/coverage.svg)](https://codeclimate.com/github/wdullaer/sse-utils/coverage)

This is a small package that aims to be the server sent events equivalent of the JSON built-in module.
It allows you to stringify an SSE object so it can be put on the wire.
It allows you parse a stringified SSE object (you'll normally use another library to create an SSE client, but this can be helpfull for testing purposes).

This library is "done", in the sense that it is feature complete and has no known bugs. It is still maintained and bugs will be fixed. It also has no dependencies, which means that other than to fix bugs in the library code, there is no reason to make new releases.

## Installation

```bash
npm install sse-utils
```

## Examples

### Individual Messages
```javascript
let sse = require('sse-utils');

let input = {data: {foo: 'bar'}};
let sseString = sse.stringify(input);
console.log(sseString);
let output = sse.parse(sseString);
console.log(output);
```

### Multiple Messages
```javascript
let sse = require('sse-utils');

let input = [{data: {foo: 'bar'}}, {data: {bar: 'baz'}}];
let sseString = sse.stringifyAll(input);
console.log(sseString);

let output = sse.parseAll(sseString);
console.log(sseString);
```

## TODO
* Add support for asynchronous (de)serializers

## API
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

-   [SSEObject][1]
-   [Serializer][2]
-   [Deserializer][3]
-   [stringify][4]
-   [stringifyAll][5]
-   [parse][6]
-   [parseAll][7]

## SSEObject

Type: [object][8]

**Properties**

-   `data` **any** The payload of the message
-   `id` **[string][9]?** The ID of the message (for reconnection)
-   `event` **[string][9]?** The type of event being sent

## Serializer

Custom serialization function

Type: [function][10]

**Parameters**

-   `payload` **any** 

Returns **[string][9]** 

## Deserializer

Custom deserialization function

Type: [function][10]

**Parameters**

-   `data` **[string][9]** 

Returns **any** 

## stringify

Stringify the data to an SSE message

**Parameters**

-   `payload` **[SSEObject][11]** The payload of the sse message: contains data, id?, event?
-   `serializer` **[Serializer][12]?** A specialized function that marshals the data into a string (optional)


-   Throws **[TypeError][13]** Arguments should have their correct types

Returns **[string][9]** The data as an SSE message

## stringifyAll

Stringify an array of data to SSE messages

**Parameters**

-   `payload` **[array][14]&lt;[SSEObject][11]>** An array of SSEObjects to be serialized
-   `serializer` **[Serializer][12]?** A specialized function that marshals the data into a string (optional)


-   Throws **[TypeError][13]** Arguments should have their correct types

Returns **[string][9]** The data is a single SSE message string

## parse

Parse an SSE message and return the data

**Parameters**

-   `sseObject` **[string][9]** The SSE message to parse
-   `deserializer` **[Deserializer][15]?** A specialized function to reconstruct the payload


-   Throws **[TypeError][13]** `sseObject` should be a string including the terminating newlines

Returns **[SSEObject][11]** The data sent in this SSE message

## parseAll

Parse multiple SSE messages and return an array of SSEObjects

**Parameters**

-   `sseObjects` **[string][9]** The SSE messages to parse
-   `deserializer` **[Deserializer][15]?** A specialized function to reconstruct the payload


-   Throws **[TypeError][13]** `sseObjects` should be a string including terminating newlines

Returns **[array][14]&lt;[SSEObject][11]>** An array with the data sent in the messages

[1]: #sseobject

[2]: #serializer

[3]: #deserializer

[4]: #stringify

[5]: #stringifyall

[6]: #parse

[7]: #parseall

[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function

[11]: #sseobject

[12]: #serializer

[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError

[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[15]: #deserializer