Burro
Burro is a useful creature that auto-packages objects in length-prefixed JSON
byte streams.
Overview
Burro is made up of 4 streams that makes sending/receiving objects a breeze
Sender streams:
- burro.Encoder - encodes objects into proper JSON strings
- burro.Framer - frames JSON in a uint32be length-prefixed buffer
Receiver streams:
- burro.Unframer - processes length prefix and parses out JSON
- burro.Decoder - decodes JSON into objects
Example
var burro = require("burro"),
stream = require("stream");
var network = new stream.PassThrough();
var socket = burro.wrap(network);
socket.write({message: "どもうありがとう!", from: "japan", to: "usa"});
socket.write({message: "thank you!", from: "usa", to: "japan"});
var parser = new stream.Transform({objectMode: true});
parser._transform = function _transform (obj, encoding, done) {
this.push(obj.from + " says: " + obj.message + "\n");
done();
};
socket.pipe(parser).pipe(process.stdout);
Output
japan says: どもうありがとう!
usa says: thank you!
Installation
Available via npm:
$ npm install burro
Or via git:
$ git clone git://github.com/naomik/burro.git node_modules/burro
API
wrap
This is burro's easy mode. It will automatically construct the entire burro
chain around your existing duplex stream. If you want to configure the burro
chain manually, please see lib/burro.js
var socket = burro.wrap([duplexStream]);
Arguments
- duplexStream - an object implementing the
stream.Duplex
API. It must have
the following functions defined: _read
, _write
, pipe
, unpipe
.
Tests
Burro is a pretty versatile beast and can even handle very large payloads. It is
also tested against network packet fragmenting and buffering, thanks to
hiccup. See the tests for more details.
Development dependencies:
$ npm install mocha
$ npm install hiccup