You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+48-19
Original file line number
Diff line number
Diff line change
@@ -1,40 +1,71 @@
1
1
# msgpack.js
2
2
3
-
This is a [MessagePack](https://msgpack.org)codec written in JavaScript for web browsers (including IE 11). Support for JavaScript servers like Node.js is unknown because I’m not using those, but I see no reason why it shouldn’t work.
3
+
This is a [MessagePack](https://msgpack.org)serializer and deserializer written in JavaScript for web browsers (including IE 11) and Node.js.
4
4
5
5
It is compact but still fully-featured. This library supports the complete [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md) released on 2017-08-09, including date/time values. No other extension types are implemented in this library, it’s only the standard types which is perfectly fine for interoperability with MessagePack codecs in other programming languages.
6
6
7
7
I’m using the [MessagePack-CSharp](https://github.com/neuecc/MessagePack-CSharp/) library on the server side in my .NET applications.
MessagePack is an efficient binary serialisation format. It lets you exchange data among multiple languages like JSON. But it’s faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves.
12
14
13
15
## Size
14
16
15
-
This codec is very lightweight. The source code has around **480 lines**, the minified file is below 6.5 kB and can be GZip-compressed to **2.2 kB**.
17
+
This library is very lightweight. The source code has around **510 lines** (incl. browser/Node detection), the minified file has 6.6 kB and can be GZip-compressed to **2.4 kB**.
16
18
17
19
## Performance
18
20
19
21
The file msgpack-tests.html contains some tests and a benchmark function that compares this library with [msgpack-lite](https://github.com/kawanet/msgpack-lite). Here are the results, in milliseconds (lower is better). All tests done on an Intel Core i7-3770 and Windows 10.
**msgpack.js serialize**| 702 ms | +6% | 1232 ms | −42% | 2483 ms | +41% | 2493 ms| −3%
26
+
msgpack-lite encode | 663 ms | | 2124 ms | | 1762 ms | | 2578 ms|
27
+
**msgpack.js deserialize**| 652 ms | +13% | 869 ms | +5% | 821 ms | −48% | 651 ms| −68%
28
+
msgpack-lite decode | 577 ms | | 827 ms | | 1587 ms | | 2021 ms|
27
29
28
30
The numbers show that this library is comparable with msgpack-lite. In Chrome it’s only 10% slower. But serializing in Firefox and deserializing in Microsoft browsers is twice as fast.
29
31
30
32
## Usage
31
33
32
-
The source file contains two public functions: `serializeMsgPack` and `deserializeMsgPack`. The first can be called with any data and returns the encoded bytes. The second works in reverse, taking the encoded bytes and returning the runtime value.
34
+
### Browser
35
+
36
+
In browsers, a global `msgpack` object is created that contains the functions `serialize` and `deserialize`. The first can be called with any data and returns the serialized bytes. The second works in reverse, taking the serialized bytes and returning the runtime value.
37
+
38
+
Include the JavaScript file into your HTML document like this:
39
+
40
+
```html
41
+
<scriptsrc="msgpack.min.js"></script>
42
+
```
43
+
44
+
You can use the library functions after loading the script.
45
+
46
+
If there should be a naming conflict with another library you want to load, you can change the global object name from `msgpack` to something else by setting `msgpackJsName` before loading the script file:
47
+
48
+
```html
49
+
<script>
50
+
msgpackJsName ="msgpackJs";
51
+
</script>
52
+
<scriptsrc="msgpack.min.js"></script>
53
+
```
54
+
55
+
### Node.js
56
+
57
+
In Node.js, these functions are exported in the object you get from the `require` function.
58
+
59
+
```js
60
+
var msgpack =require('msgpack.js');
61
+
```
62
+
63
+
### Example
33
64
34
65
Here’s a simple example:
35
66
36
67
```js
37
-
// Define some data to encode
68
+
// Define some data
38
69
var sourceData = {
39
70
number:123,
40
71
number2:-0.129,
@@ -45,20 +76,18 @@ var sourceData = {
45
76
time:Date.now()
46
77
};
47
78
48
-
//Encode to byte array
49
-
varencodedBytes=serializeMsgPack(sourceData);
79
+
//Serialize to byte array
80
+
varbytes=msgpack.serialize(sourceData);
50
81
51
-
//Decode again
52
-
vardecodedData=deserializeMsgPack(encodedBytes);
82
+
//Deserialize again
83
+
vardeserializedData=msgpack.deserialize(bytes);
53
84
```
54
85
55
-
Include the JavaScript file into your HTML document like this:
86
+
### Compatibility
56
87
57
-
```html
58
-
<scriptsrc="msgpack.min.js"></script>
59
-
```
88
+
You can also use the functions `encode` and `decode` which are aliases to `serialize` and `deserialize`. This makes it easier to replace other libraries that use these function names with msgpack.js.
60
89
61
-
You can use the codec functions after loading the script. No additional configuration required.
90
+
New projects should use the preferred (and more precisely named) `serialize` and `deserialize` functions though.
0 commit comments