@turbo-tools/sse

Server-Sent Events for turbo-http based servers

Getting Started

const sse = require('@turbo-tools/sse')

sse(response, connectionID, options = {}, closeCb = function () {})

Initializes the session. A connectionID must be given, it can be used to keep track of the connection. Default allocated buffer size is 5kb, it can be changes via the options object, using the maxEventSourceBufferSize property (in bytes). The retry property can be used to set the retry interval if the connection is closes, the default is 1000ms. If a closeCb is given, it will be called if the server or client terminates the connection. The first argument is the response object, the second is the connectionID. It returns the send function that can be used to send the messages.

send(data, type = 'message')

The function takes a string (data), that gets pushed to the client. The default type is message, but can be adjusted.

More on Server-Sent Events can be found on MDN and HTML5Rocks

Example

const sse = require('@turbo-tools/sse')
// initialize the connection (a connedction id must be given integer or string)
const sendMessage = sse(response, 1)
// send a message (must be a string)
sendMessage('Some string gettin´ pushed')
// messages can be send as long as the size of the allocated buffer isn't reached (5kb by default)
const iv = setInterval(() => sendMessage('pong'), 1000)
// closing the response closes the message channel as well
setTimeout(() => clearInterval(iv) && response.close(), 5000)

With turbo-http server

const http = require('turbo-http')
const sse = require('@turbo-tools/sse')

// Will be called if a connection gets terminated by the server or the client
const closeCb = function (response, clientId) {
  console.log(`Client with ID ${clientId} quit`)
}

// Create server
const server = http.createServer(function (request, response) {
  // should be a proper client id, not just a random number/string
  const clientId = Date.now()
  const options = {
    // reconnect timeout in ms, defaults to 1000ms
    retry: 1000,
    // size of the buffer that gets allocated in bytes, 5kb by default
    // after the size is reached, the connection is closed
    maxEventSourceBufferSize: 5192
  }
  // initialize the connection (a function that can be used to send messages is returned)
  const sendMessage = sse(response, clientId, options, closeCb)
  console.log(`Client with ID ${clientId} joined`)
})

// Listen
server.listen(3000)

Installing

npm install @turbo-tools/sse --save

Running the tests

All tests are contained in the test.js file, and written using Jest

Run them:

npm test

If you´d like to get the coverage data in addition to runnign the tests, use:

npm run test-coverage

Built With

• NPM - Dependency Management
• Commitizen - Easy semantic commit messages
• Jest - Easy tests
• Semantic Release - Easy software releases

Contributing

Please read CONTRIBUTING.md for details on the process for submitting pull requests to us, and CODE_OF_CONDUCT.md for details on the code of conduct.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Sebastian Golasch - Initial work - asciidisco

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgments

• Hat tip to @mafintosh for building turbo-net and turbo-http