Nimble Polyglot Microcosm

    missive

    3.0.1 • Public • Published

    missive

    Build Status

    Fast, lightweight library for encoding and decoding JSON messages over streams.

    Built using fringe

    Installing

    npm install --save missive
    

    How it works

    Rather than simply using newlines to delimit messages, missive uses the time-honored tradition of length prefixing. We think this is safer, and it can also be quite a bit faster.

    Examples

    Piping data

    missive exports just two functions, encode() and parse(). Each returns an instance of Stream.Transform.

    Both streams pipe Buffer instances on the way out (like pretty much all streams), but encode expects an object to be passed to write.

    let missive = require('missive');
    // create an encoder stream
    let encode = missive.encode();
    // create a parser stream
    let parse = missive.parse();
     
    encode.pipe( parse ).pipe( process.stdout );
     
    encode.write({ hello: 'world' }); // should log {"hello": "world"}
    data events

    Both streams implement standard data events, which emit Buffer instances.

    let missive = require('missive');
    let encode = missive.encode();
    let parse = missive.parse();
     
    parse.on( 'data', buffer => {
      console.log( buffer instanceof Buffer ); // true
    });
     
    encode.write({ foo: 'bar' });
    message event

    The parse stream also implements a custom message event for convenience. Rather than emitting a Buffer instance, the message event emits a parsed JavaScript object.

    let missive = require('missive');
    let encode = missive.encode();
    let parse = missive.parse();
     
    parse.on( 'message', obj => {
      console.log( obj.foo ); // 'bar'
    });
     
    encode.write({ foo: 'bar' });
    Writing to sockets
    let net = require('net');
    let missive = require('missive');
    let server = net.createServer();
     
    server.listen( 1337 );
     
    server.on( 'connection', socket => {
      let encode = missive.encode();
      encode.pipe( socket );
      encode.write({ hello: 'world' });
    });
    Reading from sockets
    let net = require('net');
    let missive = require('missive');
    let client = net.createConnection({ port: 1337 });
     
    client.pipe( missive.parse() ).on( 'message', obj => {
      console.log( obj ); // { hello: 'world' }
    });
    Compression

    To enable Node's zlib compression, instantiate an encode stream with { deflate: true } and a parse stream with { inflate: true }

    Note that this will incur a fairly substantial performance penalty, so compression is only advised in situations where message volume is low and saving bytes over the wire is critical.

    let missive = require('missive');
    let encode = missive.encode({ deflate: true });
    let parse = missive.parse({ inflate: true });
     
    parse.on( 'message', obj => {
      console.log( obj.foo ); // 'bar'
    });
     
    encode.write({ foo: 'bar' });

    Spec

    In case you can't use missive on one side of a socket, this is how it encodes data:

    1. Let data be the result of JSON.stringify( object ) + '\n'.
    2. Let header be the string 'JSON' as a utf-8 string.
    3. Let byteLength be the byte length of data as utf-8.
    4. Let buffer be a new buffer of length byteLength + 8.
    5. Write header at byte offset 0 of buffer as a UInt32LE.
    6. Write byteLength at byte offset 4 of buffer as a UInt32LE.
    7. Write data at byte offset 8 of buffer as a utf-8 string.

    Install

    npm i missive

    DownloadsWeekly Downloads

    52

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    25.5 kB

    Total Files

    23

    Last publish

    Collaborators

    • kevincennis
    • spmurrayzzz