Naughty Program Manipulator

    sseries-of-tubes

    2.0.0 • Public • Published

    sseries-of-tubes

    Build Status Coverage Status Dependency Status devDependency Status Downloads

    Takes Express/Connect routes and creates stream.Writable endpoints for Server Sent Events.

    NPM

    Introduction

    SSEriesOfTubes attaches to an http.Server and efficiently manages each endpoint for Server Sent Events by creating a writeable StringTube Stream that is piped to every http.Response. StringTube is a utf8 String Stream subclassed from Through2.

    Additionally, SSEriesOfTubes can wrap a standard Express/Connect route controller (a function that takes arguments (req, res, next)), poll that controller for data, and push that data to the SSE stream.

    This way, any API can easily support REST/polling and Server Sent Events with the same route controller.

    SSEriesOfTubes is an EventEmitter based on chrisdickinson/sse-stream, so it handles SSE headers, keep-alive messaging, and emits events around the connection and polling lifecycle.

    Installation

    npm install --save sseries-of-tubes

    Usage

    Example

    # on server 
    http           = require "http"
    express        = require "express"
    SSEriesOfTubes = require "sseries-of-tubes"
     
    server         = new http.Server
    app            = express()
    sseriesOfTubes = new SSEriesOfTubes server
     
    sendHello = (req, res, next) ->
        res.json hello: "world"
     
    # Sends {"hello": "world"} every 3s to every client connected to /sse/hello 
    app.get "/sse/hello"sseriesOfTubes.plumb sendHello3
     
    ...
     
    # on client 
    source = new EventSource "/sse/hello"
    # log {"hello": "world"} as received every 3s 
    source.onmessage = (data) -> console.log data
     

    Interface

    SSEriesOfTubes.StringTube

    Pointer to class StringTube, a Through2 Readable/Writable stream.

    SSEriesOfTubes::constructor(server, keepAliveInterval)

    new SSEriesOfTubes http.Server serverint keepAliveInterval

    returns sseriesOfTubes instance

    Creates a new SSEriesOfTubes instance that reacts to http.Server "listening" and "close" events.

    sseriesOfTubes.plumb(fn, interval)

    sseriesOfTubes.plumb Function routeint interval

    returns Function route

    Creates a new StringTube source which polls a route to write to all clients for an endpoint.

    sseriesOfTubes.plumb(fn, interval, event)

    sseriesOfTubes.plumb Function routeint intervalString event

    returns Function route

    Creates a new StringTube source which polls a route to write to all clients for an endpoint, and will send the event event (in EventSource syntax) before sending data.

    sseriesOfTubes.plumb()

    sseriesOfTubes.plumb()

    returns Function route

    Creates a new StringTube source which writes to all clients for an endpoint.

    sseriesOfTubes.source(url)

    sseriesOfTubes.source String url

    returns StringTube source

    Retrieves the StringTube source for an endpoint.

    sseriesOfTubes.combine(router, paths...)

    sseriesOfTubes.combine express.Router routerString paths...

    returns Function route

    Creates a new StringTube source by combining existing StringTube sources referenced by their path. This way different combinations of streams can be provided without duplicating pollers. Requires a router conforming to the express.Router interface for method handle.

    sseriesOfTubes.multiplex(router, param = "streams")

    sseriesOfTubes.multiplex express.Router routerString param

    returns Function route

    Creates new StringTube sources by dynamically combining existing StringTube sources, referenced by their path in an comma-separated list provided by the client in the query or body as parameter param. This method is similar to combine, but works with paths that have route parameters. Requires a router conforming to the express.Router interface for method handle.

    sseriesOfTubes.destroy()

    sseriesOfTubes.destroy()

    Ends all SSE client connections and destroys all clients.

    Events

    connection

    sseriesOfTubes.on "connection"(client) ->

    On client connection, calls bound function with an instance of Client.

    poll

    sseriesOfTubes.on "poll"(url) ->

    On route start poll, calls bound function with the url endpoint.

    plumb

    sseriesOfTubes.on "plumb"(url) ->

    On route start plumb (creates StringTube source), calls bound function with the url endpoint.

    stop

    sseriesOfTubes.on "stop"(url) ->

    On last client disconnect, calls bound function with the url endpoint.

    License

    MIT

    Install

    npm i sseries-of-tubes

    DownloadsWeekly Downloads

    0

    Version

    2.0.0

    License

    MIT

    Last publish

    Collaborators

    • doublerebel