README.md
# SSE Utils
[](https://codeclimate.com/github/wdullaer/sse-utils)
[](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]<[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]<[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