Mux Demux Stream

Multiplexer and demultiplexter for binary/text streams with inspiration from the book Node.js Design Patterns by Mario Casciaro.

Multiplex and demultiplex up to eight binary/text streams with a single multiplexer or demultiplexer. Each chunk of data is prepended with a five bytes header, including channel id and payload length.

1 byte (Channel ID)	4 bytes (Payload length)	Original payload of variable length

Installation

npm install mux-demux-stream

Usage

The module can be used both with a "simplex" syntax and with a "duplex" syntax that offers some syntactic sugar over the simplex variant.

The simplex syntax is used for multiplexing several readable streams into a single writable stream, or demultiplexing several writable streams into a single readable stream.

The duplex syntax is more compact when for example implementing a protocol like JSON RPC 2.0 in a peer-to-peer fashion, where each RPC node consist of a server and a client that share a common bidirectional channel such as WebSockets. (See json-rpc-server-stream and json-rpc-client-stream for a more comprehensive discussion about using JSON RPC 2.0 in a peer-to-peer fashion.)

Simplex syntax

Require module and specific functions.

var mux = require('mux-demux-stream').mux;
var demux = require('mux-demux-stream').demux;

mux(sources, destination)

Combine multiple streams to allow transmission over a single stream.

var sourceA = createReadableStreamSomehow();
var sourceB = createReadableStreamSomehow();
var destination = createWritableStreamSomehow();
 
mux([sourceA, sourceB], destination);

demux(source, destinations)

Reconstruct the original streams from the data received from a shared stream.

var source = createReadableStreamSomehow();
var destinationA = createWritableStreamSomehow();
var destinationB = createWritableStreamSomehow();
 
demux(source, [destinationA, destinationB]);

Duplex syntax

Require module. (Note that this is not the same mux function as in the example above.)

var mux = require('mux-demux-stream');

mux(channel1[, ...]).pipe(sharedChannel).demux(channel1[, ...])

Internally the duplex variant uses "chaining" and closures to form a natural stream syntax when several duplex streams are multiplexed into and from a shared channel stream.

The following simplex syntax:

mux([localClientStream, localServerStream], sharedChannel);
demux(sharedChannel, [localClientStream, localServerStream]);

is equivalent to the following duplex syntax:

mux(localClientStream, localServerStream)
  .pipe(sharedChannel)
  .demux(localClientStream, localServerStream);

Test

Run unit tests:

npm test

License

MIT