1 | # msgpack-lite [![npm version](https://badge.fury.io/js/msgpack-lite.svg)](http://badge.fury.io/js/msgpack-lite) [![Build Status](https://travis-ci.org/kawanet/msgpack-lite.svg?branch=master)](https://travis-ci.org/kawanet/msgpack-lite)
|
2 |
|
3 | Fast Pure JavaScript MessagePack Encoder and Decoder
|
4 |
|
5 | Online Demo: http://kawanet.github.io/msgpack-lite/
|
6 |
|
7 | ### Encoding and Decoding MessagePack
|
8 |
|
9 | ```js
|
10 | var msgpack = require("msgpack-lite");
|
11 |
|
12 | // encode from JS Object to MessagePack (Buffer)
|
13 | var buffer = msgpack.encode({"foo": "bar"});
|
14 |
|
15 | // decode from MessagePack (Buffer) to JS Object
|
16 | var data = msgpack.decode(buffer); // => {"foo": "bar"}
|
17 | ```
|
18 |
|
19 | ### Writing to MessagePack Stream
|
20 |
|
21 | ```js
|
22 | var fs = require("fs");
|
23 | var msgpack = require("msgpack-lite");
|
24 |
|
25 | var writeStream = fs.createWriteStream("test.msp");
|
26 | var encodeStream = msgpack.createEncodeStream();
|
27 | encodeStream.pipe(writeStream);
|
28 |
|
29 | // send multiple objects to stream
|
30 | encodeStream.write({foo: "bar"});
|
31 | encodeStream.write({baz: "qux"});
|
32 | ```
|
33 |
|
34 | ### Reading from MessagePack Stream
|
35 |
|
36 | ```js
|
37 | var fs = require("fs");
|
38 | var msgpack = require("msgpack-lite");
|
39 |
|
40 | var readStream = fs.createReadStream("test.msp");
|
41 | var decodeStream = msgpack.createDecodeStream();
|
42 |
|
43 | // show multiple objects decoded from stream
|
44 | readStream.pipe(decodeStream).on("data", console.warn);
|
45 | ```
|
46 |
|
47 | ### Command Line Interface
|
48 |
|
49 | A CLI tool bin/msgpack converts data stream from JSON to MessagePack and vice versa.
|
50 |
|
51 | ```sh
|
52 | $ echo '{"foo": "bar"}' | ./bin/msgpack -Jm | od -tx1
|
53 | 0000000 81 a3 66 6f 6f a3 62 61 72
|
54 |
|
55 | $ echo '{"foo": "bar"}' | ./bin/msgpack -Jm | ./bin/msgpack -Mj
|
56 | {"foo":"bar"}
|
57 | ```
|
58 |
|
59 | ### Installation
|
60 |
|
61 | ```sh
|
62 | $ npm install --save msgpack-lite
|
63 | ```
|
64 |
|
65 | ### Browser Build
|
66 |
|
67 | Browser version is also available. 33KB minified, 10KB gziped.
|
68 |
|
69 | ```html
|
70 | <script src="https://rawgithub.com/kawanet/msgpack-lite/master/dist/msgpack.min.js"></script>
|
71 | <script>
|
72 | // encode from JS Object to MessagePack (Uint8Array)
|
73 | var buffer = msgpack.encode({foo: "bar"});
|
74 |
|
75 | // decode from MessagePack (Uint8Array) to JS Object
|
76 | var array = new Uint8Array([0x81, 0xA3, 0x66, 0x6F, 0x6F, 0xA3, 0x62, 0x61, 0x72]);
|
77 | var data = msgpack.decode(array);
|
78 | </script>
|
79 | ```
|
80 |
|
81 | It works even on IE9 with [es5-shim
](https://github.com/es-shims/es5-shim).
|
82 |
|
83 | ### Interoperability
|
84 |
|
85 | It is tested to have basic compatibility with other Node.js MessagePack modules below:
|
86 |
|
87 | - https://www.npmjs.com/package/msgpack (0.2.6)
|
88 | - https://www.npmjs.com/package/msgpack-js (0.3.0)
|
89 | - https://www.npmjs.com/package/msgpack-js-v5 (0.3.0-v5)
|
90 | - https://www.npmjs.com/package/msgpack5 (3.1.0)
|
91 | - https://www.npmjs.com/package/msgpack-unpack (2.1.1)
|
92 | - https://github.com/msgpack/msgpack-javascript (msgpack.codec)
|
93 |
|
94 | ### Speed Comparison
|
95 |
|
96 | A benchmark tool lib/benchmark.js is available to compare encoding/decoding speed.
|
97 |
|
98 | ```txt
|
99 | $ node -v
|
100 | v0.10.40
|
101 | $ node lib/benchmark.js 10
|
102 | operation | result | op/s
|
103 | -------------------------------------------------------------- | ------------------ | -----
|
104 | buf = Buffer(JSON.stringify(obj)); | 225700op / 10001ms | 2256
|
105 | obj = JSON.parse(buf); | 243000op / 10000ms | 2430
|
106 | buf = require("msgpack").pack(obj); | 182000op / 10014ms | 1817
|
107 | obj = require("msgpack").unpack(buf); | 232100op / 10004ms | 2320
|
108 | buf = require("msgpack-lite").encode(obj); | 203300op / 10001ms | 2032
|
109 | obj = require("msgpack-lite").decode(buf); | 145700op / 10003ms | 1456
|
110 | buf = Buffer(require("msgpack-javascript").msgpack.pack(obj)); | 138400op / 10010ms | 1382
|
111 | obj = require("msgpack-javascript").msgpack.unpack(buf); | 102000op / 10007ms | 1019
|
112 | buf = require("msgpack-js-v5").encode(obj); | 28900op / 10032ms | 288
|
113 | obj = require("msgpack-js-v5").decode(buf); | 99600op / 10008ms | 995
|
114 | buf = require("msgpack-js").encode(obj); | 28700op / 10004ms | 286
|
115 | obj = require("msgpack-js").decode(buf); | 104600op / 10012ms | 1044
|
116 | buf = require("msgpack5")().encode(obj); | 4500op / 10025ms | 44
|
117 | obj = require("msgpack5")().decode(buf); | 18600op / 10024ms | 185
|
118 | obj = require("msgpack-unpack").decode(buf); | 1600op / 10245ms | 15
|
119 | ```
|
120 |
|
121 | The msgpack-lite is the fastest module on both encoding and decoding
|
122 | operations compared to the other pure JavaScript msgpack-* modules.
|
123 | It's even 12% faster than C++ node-gyp backed msgpack module on encoding!
|
124 |
|
125 | ### MessagePack Mapping Table
|
126 |
|
127 | The following table shows how JavaScript objects (value) will be mapped to
|
128 | [MessagePack formats](https://github.com/msgpack/msgpack/blob/master/spec.md)
|
129 | and vice versa.
|
130 |
|
131 | Source Value|MessagePack Format|Value Decoded
|
132 | ----|----|----
|
133 | null, undefined|nil format family|null
|
134 | Boolean (true, false)|bool format family|Boolean (true, false)
|
135 | Number (32bit int)|int format family|Number (int or double)
|
136 | Number (64bit double)|float format family|Number (double)
|
137 | String|str format family|String
|
138 | Buffer|bin format family|Buffer
|
139 | Array|array format family|Array
|
140 | Object (plain object)|map format family|Object
|
141 | Object (see below)|ext format family|Object (see below)
|
142 |
|
143 | Note that both `null` and `undefined` are mapped to nil `0xC1` type.
|
144 | This means `undefined` value will be *upgraded* to `null` in other words.
|
145 |
|
146 | ### Extension Types
|
147 |
|
148 | The MessagePack specification allows 128 application-specific extension types.
|
149 | The library uses the following types to make round-trip conversion possible
|
150 | for JavaScript native objects.
|
151 |
|
152 | Type|Object|Type|Object
|
153 | ----|----|----|----
|
154 | 0x00||0x10|
|
155 | 0x01|EvalError|0x11|Int8Array
|
156 | 0x02|RangeError|0x12|Uint8Array
|
157 | 0x03|ReferenceError|0x13|Int16Array
|
158 | 0x04|SyntaxError|0x14|Uint16Array
|
159 | 0x05|TypeError|0x15|Int32Array
|
160 | 0x06|URIError|0x16|Uint32Array
|
161 | 0x07||0x17|Float32Array
|
162 | 0x08||0x18|Float64Array
|
163 | 0x09||0x19|Uint8ClampedArray
|
164 | 0x0A|RegExp|0x1A|ArrayBuffer
|
165 | 0x0B|Boolean|0x1B|
|
166 | 0x0C|String|0x1C|
|
167 | 0x0D|Date|0x1D|DataView
|
168 | 0x0E|Error|0x1E|
|
169 | 0x0F|Number|0x1F|
|
170 |
|
171 | Other extension types are mapped to internal ExtBuffer object.
|
172 |
|
173 | ### Repository
|
174 |
|
175 | - https://github.com/kawanet/msgpack-lite
|
176 |
|
177 | ### See Also
|
178 |
|
179 | - http://msgpack.org/
|
180 |
|
181 | ### License
|
182 |
|
183 | The MIT License (MIT)
|
184 |
|
185 | Copyright (c) 2015 Yusuke Kawasaki
|
186 |
|
187 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
188 | of this software and associated documentation files (the "Software"), to deal
|
189 | in the Software without restriction, including without limitation the rights
|
190 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
191 | copies of the Software, and to permit persons to whom the Software is
|
192 | furnished to do so, subject to the following conditions:
|
193 |
|
194 | The above copyright notice and this permission notice shall be included in all
|
195 | copies or substantial portions of the Software.
|
196 |
|
197 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
198 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
199 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
200 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
201 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
202 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
203 | SOFTWARE.
|