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 | [![Sauce Test Status](https://saucelabs.com/browser-matrix/msgpack-lite.svg)](https://saucelabs.com/u/msgpack-lite)
|
6 |
|
7 | Online demo: [http://kawanet.github.io/msgpack-lite/](http://kawanet.github.io/msgpack-lite/)
|
8 |
|
9 | ### Features
|
10 |
|
11 | - Pure JavaScript only (No node-gyp nor gcc required)
|
12 | - Faster than any other pure JavaScript libraries on node.js v4
|
13 | - Even faster than C++ based [msgpack](https://www.npmjs.com/package/msgpack) library (**90% faster** on encoding)
|
14 | - Streaming encoding and decoding interface is also available. It's more faster.
|
15 | - Ready for [Web browsers](https://saucelabs.com/u/msgpack-lite) including Chrome, Firefox, Safari and even IE8
|
16 | - [Tested](https://travis-ci.org/kawanet/msgpack-lite) on Node.js v0.10, v0.12 and v4.2 as well as Web browsers
|
17 |
|
18 | ### Encoding and Decoding MessagePack
|
19 |
|
20 | ```js
|
21 | var msgpack = require("msgpack-lite");
|
22 |
|
23 | // encode from JS Object to MessagePack (Buffer)
|
24 | var buffer = msgpack.encode({"foo": "bar"});
|
25 |
|
26 | // decode from MessagePack (Buffer) to JS Object
|
27 | var data = msgpack.decode(buffer); // => {"foo": "bar"}
|
28 |
|
29 | // if encode/decode receives an invalid argument an error is thrown
|
30 | ```
|
31 |
|
32 | ### Writing to MessagePack Stream
|
33 |
|
34 | ```js
|
35 | var fs = require("fs");
|
36 | var msgpack = require("msgpack-lite");
|
37 |
|
38 | var writeStream = fs.createWriteStream("test.msp");
|
39 | var encodeStream = msgpack.createEncodeStream();
|
40 | encodeStream.pipe(writeStream);
|
41 |
|
42 | // send multiple objects to stream
|
43 | encodeStream.write({foo: "bar"});
|
44 | encodeStream.write({baz: "qux"});
|
45 | ```
|
46 |
|
47 | ### Reading from MessagePack Stream
|
48 |
|
49 | ```js
|
50 | var fs = require("fs");
|
51 | var msgpack = require("msgpack-lite");
|
52 |
|
53 | var readStream = fs.createReadStream("test.msp");
|
54 | var decodeStream = msgpack.createDecodeStream();
|
55 |
|
56 | // show multiple objects decoded from stream
|
57 | readStream.pipe(decodeStream).on("data", console.warn);
|
58 | ```
|
59 |
|
60 | ### Command Line Interface
|
61 |
|
62 | A CLI tool bin/msgpack converts data stream from JSON to MessagePack and vice versa.
|
63 |
|
64 | ```sh
|
65 | $ echo '{"foo": "bar"}' | ./bin/msgpack -Jm | od -tx1
|
66 | 0000000 81 a3 66 6f 6f a3 62 61 72
|
67 |
|
68 | $ echo '{"foo": "bar"}' | ./bin/msgpack -Jm | ./bin/msgpack -Mj
|
69 | {"foo":"bar"}
|
70 | ```
|
71 |
|
72 | ### Installation
|
73 |
|
74 | ```sh
|
75 | $ npm install --save msgpack-lite
|
76 | ```
|
77 |
|
78 | ### Tests
|
79 |
|
80 | Run tests on node.js:
|
81 |
|
82 | ```sh
|
83 | $ make test
|
84 | ```
|
85 |
|
86 | Run tests on browsers:
|
87 |
|
88 | ```sh
|
89 | $ make test-browser-local
|
90 | open the following url in a browser:
|
91 | http://localhost:4000/__zuul
|
92 | ```
|
93 |
|
94 | ### Browser Build
|
95 |
|
96 | Browser version [msgpack.min.js](https://rawgithub.com/kawanet/msgpack-lite/master/dist/msgpack.min.js) is also available. 37KB minified, 11KB gziped.
|
97 |
|
98 | ```html
|
99 | <!--[if lte IE 9]>
|
100 | <script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/4.1.10/es5-shim.min.js"></script>
|
101 | <script src="https://cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"></script>
|
102 | <![endif]-->
|
103 | <script src="https://rawgithub.com/kawanet/msgpack-lite/master/dist/msgpack.min.js"></script>
|
104 | <script>
|
105 | // encode from JS Object to MessagePack (Uint8Array)
|
106 | var buffer = msgpack.encode({foo: "bar"});
|
107 |
|
108 | // decode from MessagePack (Uint8Array) to JS Object
|
109 | var array = new Uint8Array([0x81, 0xA3, 0x66, 0x6F, 0x6F, 0xA3, 0x62, 0x61, 0x72]);
|
110 | var data = msgpack.decode(array);
|
111 | </script>
|
112 | ```
|
113 |
|
114 | ### Interoperability
|
115 |
|
116 | It is tested to have basic compatibility with other Node.js MessagePack modules below:
|
117 |
|
118 | - [https://www.npmjs.com/package/msgpack](https://www.npmjs.com/package/msgpack) (1.0.2)
|
119 | - [https://www.npmjs.com/package/msgpack-js](https://www.npmjs.com/package/msgpack-js) (0.3.0)
|
120 | - [https://www.npmjs.com/package/msgpack-js-v5](https://www.npmjs.com/package/msgpack-js-v5) (0.3.0-v5)
|
121 | - [https://www.npmjs.com/package/msgpack-unpack](https://www.npmjs.com/package/msgpack-unpack) (2.1.1)
|
122 | - [https://github.com/msgpack/msgpack-javascript](https://github.com/msgpack/msgpack-javascript) (msgpack.codec)
|
123 | - [https://www.npmjs.com/package/msgpack5](https://www.npmjs.com/package/msgpack5) (3.3.0)
|
124 | - [https://www.npmjs.com/package/notepack](https://www.npmjs.com/package/notepack) (0.0.2)
|
125 |
|
126 | ### Benchmarks
|
127 |
|
128 | A benchmark tool `lib/benchmark.js` is available to compare encoding/decoding speed
|
129 | (operation per second) with other MessagePack modules.
|
130 | It counts operations of [1KB JSON document](https://github.com/kawanet/msgpack-lite/blob/master/test/example.json) in 10 seconds.
|
131 |
|
132 | ```sh
|
133 | $ npm install msgpack msgpack-js msgpack-js-v5 msgpack-unpack msgpack5 notepack
|
134 | $ node lib/benchmark.js 10
|
135 | ```
|
136 |
|
137 | operation | op | ms | op/s
|
138 | --------------------------------------------------------- | -----: | ----: | -----:
|
139 | buf = Buffer(JSON.stringify(obj)); | 1055200 | 10000 | 105520
|
140 | obj = JSON.parse(buf); | 863800 | 10000 | 86380
|
141 | buf = require("msgpack-lite").encode(obj); | 969100 | 10000 | 96910
|
142 | obj = require("msgpack-lite").decode(buf); | 600300 | 10000 | 60030
|
143 | buf = require("msgpack").pack(obj); | 503500 | 10001 | 50344
|
144 | obj = require("msgpack").unpack(buf); | 560200 | 10001 | 56014
|
145 | buf = Buffer(require("msgpack.codec").msgpack.pack(obj)); | 653500 | 10000 | 65349
|
146 | obj = require("msgpack.codec").msgpack.unpack(buf); | 367500 | 10001 | 36746
|
147 | buf = require("msgpack-js-v5").encode(obj); | 189500 | 10002 | 18946
|
148 | obj = require("msgpack-js-v5").decode(buf); | 408900 | 10000 | 40890
|
149 | buf = require("msgpack-js").encode(obj); | 189200 | 10000 | 18920
|
150 | obj = require("msgpack-js").decode(buf); | 375600 | 10002 | 37552
|
151 | buf = require("msgpack5")().encode(obj); | 110500 | 10009 | 11040
|
152 | obj = require("msgpack5")().decode(buf); | 165500 | 10000 | 16550
|
153 | buf = require("notepack")().encode(obj); | 847800 | 10000 | 84780
|
154 | obj = require("notepack")().decode(buf); | 599800 | 10000 | 59980
|
155 | obj = require("msgpack-unpack").decode(buf); | 48100 | 10002 | 4809
|
156 |
|
157 | Streaming benchmark tool `lib/benchmark-stream.js` is also available.
|
158 | It counts milliseconds for 1,000,000 operations of 30 bytes fluentd msgpack fragment.
|
159 | This shows streaming encoding and decoding are super faster.
|
160 |
|
161 | ```sh
|
162 | $ node lib/benchmark-stream.js 2
|
163 | ```
|
164 |
|
165 | operation (1000000 x 2) | op | ms | op/s
|
166 | ------------------------------------------------ | ------: | ----: | -----:
|
167 | stream.write(msgpack.encode(obj)); | 1000000 | 3027 | 330360
|
168 | stream.write(notepack.encode(obj)); | 1000000 | 2012 | 497017
|
169 | msgpack.Encoder().on("data",ondata).encode(obj); | 1000000 | 2956 | 338294
|
170 | msgpack.createEncodeStream().write(obj); | 1000000 | 1888 | 529661
|
171 | stream.write(msgpack.decode(buf)); | 1000000 | 2020 | 495049
|
172 | stream.write(notepack.decode(buf)); | 1000000 | 1794 | 557413
|
173 | msgpack.Decoder().on("data",ondata).decode(buf); | 1000000 | 2744 | 364431
|
174 | msgpack.createDecodeStream().write(buf); | 1000000 | 1341 | 745712
|
175 |
|
176 | Test environment: msgpack-lite 0.1.14, Node v4.2.3, Intel(R) Xeon(R) CPU E5-2666 v3 @ 2.90GHz
|
177 |
|
178 | ### MessagePack Mapping Table
|
179 |
|
180 | The following table shows how JavaScript objects (value) will be mapped to
|
181 | [MessagePack formats](https://github.com/msgpack/msgpack/blob/master/spec.md)
|
182 | and vice versa.
|
183 |
|
184 | Source Value|MessagePack Format|Value Decoded
|
185 | ----|----|----
|
186 | null, undefined|nil format family|null
|
187 | Boolean (true, false)|bool format family|Boolean (true, false)
|
188 | Number (32bit int)|int format family|Number (int or double)
|
189 | Number (64bit double)|float format family|Number (double)
|
190 | String|str format family|String
|
191 | Buffer|bin format family|Buffer
|
192 | Array|array format family|Array
|
193 | Object (plain object)|map format family|Object
|
194 | Object (see below)|ext format family|Object (see below)
|
195 |
|
196 | Note that both `null` and `undefined` are mapped to nil `0xC1` type.
|
197 | This means `undefined` value will be *upgraded* to `null` in other words.
|
198 |
|
199 | ### Extension Types
|
200 |
|
201 | The MessagePack specification allows 128 application-specific extension types.
|
202 | The library uses the following types to make round-trip conversion possible
|
203 | for JavaScript native objects.
|
204 |
|
205 | Type|Object|Type|Object
|
206 | ----|----|----|----
|
207 | 0x00||0x10|
|
208 | 0x01|EvalError|0x11|Int8Array
|
209 | 0x02|RangeError|0x12|Uint8Array
|
210 | 0x03|ReferenceError|0x13|Int16Array
|
211 | 0x04|SyntaxError|0x14|Uint16Array
|
212 | 0x05|TypeError|0x15|Int32Array
|
213 | 0x06|URIError|0x16|Uint32Array
|
214 | 0x07||0x17|Float32Array
|
215 | 0x08||0x18|Float64Array
|
216 | 0x09||0x19|Uint8ClampedArray
|
217 | 0x0A|RegExp|0x1A|ArrayBuffer
|
218 | 0x0B|Boolean|0x1B|
|
219 | 0x0C|String|0x1C|
|
220 | 0x0D|Date|0x1D|DataView
|
221 | 0x0E|Error|0x1E|
|
222 | 0x0F|Number|0x1F|
|
223 |
|
224 | Other extension types are mapped to internal ExtBuffer object.
|
225 |
|
226 | ### Repository
|
227 |
|
228 | - [https://github.com/kawanet/msgpack-lite](https://github.com/kawanet/msgpack-lite)
|
229 |
|
230 | ### See Also
|
231 |
|
232 | - [http://msgpack.org/](http://msgpack.org/)
|
233 |
|
234 | ### License
|
235 |
|
236 | The MIT License (MIT)
|
237 |
|
238 | Copyright (c) 2015-2016 Yusuke Kawasaki
|
239 |
|
240 | Permission is hereby granted, free of charge, to any person obtaining a copy
|
241 | of this software and associated documentation files (the "Software"), to deal
|
242 | in the Software without restriction, including without limitation the rights
|
243 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
244 | copies of the Software, and to permit persons to whom the Software is
|
245 | furnished to do so, subject to the following conditions:
|
246 |
|
247 | The above copyright notice and this permission notice shall be included in all
|
248 | copies or substantial portions of the Software.
|
249 |
|
250 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
251 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
252 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
253 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
254 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
255 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
256 | SOFTWARE.
|