const msgpack = require("msgpack-lite");// encode from JS Object to MessagePack (Buffer)const buffer = msgpack.encode({"foo": "bar"});// decode from MessagePack (Buffer) to JS Objectconst data = msgpack.decode(buffer); // => {"foo": "bar"}// if encode/decode receives an invalid argument an error is thrown
Writing to MessagePack Stream
const fs = require("fs");const msgpack = require("msgpack-lite");const writeStream = fs.createWriteStream("test.msp");const encodeStream = msgpack.createEncodeStream();encodeStream.pipe(writeStream);// send multiple objects to streamencodeStream.write({foo: "bar"});encodeStream.write({baz: "qux"});// call this once you're done writing to the stream.encodeStream.end();
Reading from MessagePack Stream
const fs = require("fs");const msgpack = require("msgpack-lite");const readStream = fs.createReadStream("test.msp");const decodeStream = msgpack.createDecodeStream();// show multiple objects decoded from streamreadStream.pipe(decodeStream).on("data", console.warn);
Browser version msgpack.min.js is also available. 50KB minified, 14KB gziped.
<!--[if lte IE 9]><script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.1.10/es5-shim.min.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"></script><![endif]--><script src="https://cdn.jsdelivr.net/npm/msgpack-lite/dist/msgpack.min.js"></script><script>// encode from JS Object to MessagePack (Uint8Array)var buffer = msgpack.encode({foo: "bar"});// decode from MessagePack (Uint8Array) to JS Objectvar array = new Uint8Array([0x81, 0xA3, 0x66, 0x6F, 0x6F, 0xA3, 0x62, 0x61, 0x72]);var data = msgpack.decode(array);</script>
MessagePack Mapping Table
The following table shows how JavaScript objects (value) will be mapped to
MessagePack formats
and vice versa.
Source Value
MessagePack Format
Value Decoded
null, undefined
nil format family
null
Boolean (true, false)
bool format family
Boolean (true, false)
Number (32bit int)
int format family
Number (int or double)
Number (64bit double)
float format family
Number (double)
String
str format family
String
Buffer
bin format family
Buffer
Array
array format family
Array
Map
map format family
Map (if usemap=true)
Object (plain object)
map format family
Object (or Map if usemap=true)
Object (see below)
ext format family
Object (see below)
Note that both null and undefined are mapped to nil 0xC1 type.
This means undefined value will be upgraded to null in other words.
Extension Types
The MessagePack specification allows 128 application-specific extension types.
The library uses the following types to make round-trip conversion possible
for JavaScript native objects.
Type
Object
Type
Object
0x00
0x10
0x01
EvalError
0x11
Int8Array
0x02
RangeError
0x12
Uint8Array
0x03
ReferenceError
0x13
Int16Array
0x04
SyntaxError
0x14
Uint16Array
0x05
TypeError
0x15
Int32Array
0x06
URIError
0x16
Uint32Array
0x07
0x17
Float32Array
0x08
0x18
Float64Array
0x09
0x19
Uint8ClampedArray
0x0A
RegExp
0x1A
ArrayBuffer
0x0B
Boolean
0x1B
Buffer
0x0C
String
0x1C
0x0D
Date
0x1D
DataView
0x0E
Error
0x1E
0x0F
Number
0x1F
Other extension types are mapped to built-in ExtBuffer object.
Custom Extension Types (Codecs)
Register a custom extension type number to serialize/deserialize your own class instances.
The first argument of addExtPacker and addExtUnpacker should be an integer within the range of 0 and 127 (0x0 and 0x7F). myVectorPacker is a function that accepts an instance of MyVector, and should return a buffer representing that instance. myVectorUnpacker is the opposite: it accepts a buffer and should return an instance of MyVector.
If you pass an array of functions to addExtPacker or addExtUnpacker, the value to be encoded/decoded will pass through each one in order. This allows you to do things like this:
You can also pass the codec option to msgpack.Decoder(options), msgpack.Encoder(options), msgpack.createEncodeStream(options), and msgpack.createDecodeStream(options).
If you wish to modify the default built-in codec, you can access it at msgpack.codec.preset.
Custom Codec Options
msgpack.createCodec() function accepts some options.
It does NOT have the preset extension types defined when no options given.
const codec = msgpack.createCodec();
preset: It has the preset extension types described above.
safe: It runs a validation of the value before writing it into buffer. This is the default behavior for some old browsers which do not support ArrayBuffer object.
const codec = msgpack.createCodec({safe: true});
useraw: It uses raw formats instead of bin and str.
To combine Maps with built-in extension types such as Uint8Array, also enable
preset. Custom codecs do not inherit the default codec's extension handlers:
usemap alone does not preserve typed arrays. Pass the codec to both encoding
and decoding to preserve both types.
const codec = msgpack.createCodec({usemap: true, preset: true});const value = new Map([["bytes", new Uint8Array([1, 2, 3])]]);const encoded = msgpack.encode(value, {codec});const decoded = msgpack.decode(encoded, {codec});// decoded is a Map; decoded.get("bytes") is Uint8Array [1, 2, 3].
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.