Home

Awesome

msgpack5  CI

A msgpack v5 implementation for node.js and the browser, with extension point support.

Install

npm install msgpack5 --save

Usage

var msgpack = require('msgpack5')() // namespace our extensions
  , a       = new MyType(2, 'a')
  , encode  = msgpack.encode
  , decode  = msgpack.decode

msgpack.register(0x42, MyType, mytipeEncode, mytipeDecode)

const hex = encode({ 'hello': 'world' }).toString('hex')
console.log(hex)
// 81a568656c6c6fa5776f726c64
const obj = decode(Buffer.from(hex, 'hex'))
console.log(obj)
// { hello: 'world' }

console.log(decode(encode({ 'hello': 'world' })))
// { hello: 'world' }
console.log(encode(a).toString('hex'))
// d5426161
console.log(decode(encode(a)) instanceof MyType)
// true
console.log(decode(encode(a)))
// { value: 'a', size: 2 }

function MyType(size, value) {
  this.value = value
  this.size  = size
}

function mytipeEncode(obj) {
  var buf = new Buffer(obj.size)
  buf.fill(obj.value)
  return buf
}

function mytipeDecode(data) {
  var result = new MyType(data.length, data.toString('utf8', 0, 1))
    , i

  for (i = 0; i < data.length; i++) {
    if (data.readUInt8(0) != data.readUInt8(i)) {
      throw new Error('should all be the same')
    }
  }

  return result
}

In the Browser

This library is compatible with Browserify.

If you want to use standalone, grab the file in the dist folder of this repo, and use in your own HTML page, the module will expose a msgpack5 global.

<script type="text/javascript"
        src="./msgpack5.min.js">
</script>

To build

	npm run build

API

<a name="api"></a>

API


<a name="msgpack"></a>

msgpack(options(obj))

Creates a new instance on which you can register new types for being encoded.

options:


<a name="encode"></a>

encode(object)

Encodes object in msgpack, returns a bl.


<a name="decode"></a>

decode(buf)

Decodes buf from in msgpack. buf can be a Buffer or a bl instance.

In order to support a stream interface, a user must pass in a bl instance.


<a name="registerEncoder"></a>

registerEncoder(check(obj), encode(obj))

Register a new custom object type for being automatically encoded. The arguments are:


<a name="registerDecoder"></a>

registerDecoder(type, decode(buf))

Register a new custom object type for being automatically decoded. The arguments are:


<a name="register"></a>

register(type, constructor, encode(obj), decode(buf))

Register a new custom object type for being automatically encoded and decoded. The arguments are:

This is just a commodity that calls registerEncoder and registerDecoder internally.


<a name="encoder"></a>

encoder(options)

Builds a stream in object mode that encodes msgpack.

Supported options:


<a name="decoder"></a>

decoder(options)

Builds a stream in object mode that decodes msgpack.

Supported options:

LevelUp Support

msgpack5 can be used as a LevelUp valueEncoding straight away:

var level = require('level')
  , pack  = msgpack()
  , db    = level('foo', {
      valueEncoding: pack
    })
  , obj   = { my: 'obj' }

db.put('hello', obj, function(err) {
  db.get('hello', function(err, result) {
    console.log(result)
    db.close()
  })
})

Related projects

Disclaimer

This library is built fully on JS and on bl to simplify the code. Every improvement that keeps the same API is welcome.

Acknowledgements

This project was kindly sponsored by nearForm.

This library was originally built as the data format for JSChan.

License

MIT