msgpack5 ![CI](https://github.com/mcollina/msgpack5/workflows/CI/badge.svg)
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)
console.log(encode({ 'hello': 'world' }).toString('hex'))
// 81a568656c6c6fa5776f726c64
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
API
msgpack()
msgpack().encode()
msgpack().decode()
msgpack().registerEncoder()
msgpack().registerDecoder()
msgpack().register()
msgpack().encoder()
msgpack().decoder()
msgpack(options(obj))
Creates a new instance on which you can register new types for being encoded.
options:
forceFloat64
, a boolean to that forces all floats to be encoded as 64-bits floats. Defaults to false.sortKeys
, a boolean to force a determinate keys ordercompatibilityMode
, a boolean that enables "compatibility mode" which doesn't use str 8 format. Defaults to false.disableTimestampEncoding
, a boolean that when set disables the encoding of Dates into the timestamp extension type. Defaults to false.
encode(object)
Encodes object
in msgpack, returns a bl.
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.
registerEncoder(check(obj), encode(obj))
Register a new custom object type for being automatically encoded. The arguments are:
check
, a function that will be called to check if the passed object should be encoded with theencode
functionencode
, a function that will be called to encode an object in binary form; this function must return aBuffer
which include the same type for registerDecoder.
registerDecoder(type, decode(buf))
Register a new custom object type for being automatically decoded. The arguments are:
type
, is a greater than zero integer identificating the type once serializeddecode
, a function that will be called to decode the object from the passedBuffer
register(type, constructor, encode(obj), decode(buf))
Register a new custom object type for being automatically encoded and decoded. The arguments are:
type
, is a greater than zero integer identificating the type once serializedconstructor
, the function that will be used to match the objects withinstanceof
encode
, a function that will be called to encode an object in binary form; this function must return aBuffer
that can be deserialized by thedecode
functiondecode
, a function that will be called to decode the object from the passedBuffer
This is just a commodity that calls registerEncoder
and registerDecoder
internally.
encoder(options)
Builds a stream in object mode that encodes msgpack.
Supported options:
wrap
, objects should be passed to encoder in wrapped object {value: data}. Wrap option should be used if you need to pass null to encoder.
decoder(options)
Builds a stream in object mode that decodes msgpack.
Supported options:
wrap
, decoded objects returned in wrapped object {value: data}. Wrap option should be used if stream contains msgpack nil.
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
- msgpack5rpc: An implementation of the msgpack-rpc spec on top of this library.
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