Skip to content
Newer
Older
100644 141 lines (104 sloc) 5.75 KB
5db0865 @pgriess Add type mapping rules to README.md.
authored
1 `node-msgpack` is an addon for [NodeJS](http://nodejs.org) that provides an
861cc6e @pgriess Add README.
authored
2 API for serializing and de-serializing JavaScript objects using the
64cee77 @pgriess More README udpates.
authored
3 [MessagePack](http://msgpack.sourceforge.net) library. The performance of this
4 addon compared to the native `JSON` object is quite good, and the space
5 required for serialized data is far less than JSON.
861cc6e @pgriess Add README.
authored
6
484dbd3 @pgriess Update README with performance numbers.
authored
7 ### Performance
8
9 `node-msgpack` outperforms the built-in `JSON.stringify()` and `JSON.parse()`
10 methods handily. The following tests were performed with 500,000 instances of
11 the JavaScript object `{'abcdef' : 1, 'qqq' : 13, '19' : [1, 2, 3, 4]}`:
12
13 * `JSON.stringify()` 7.17 seconds
14 * `JSON.parse(JSON.stringify())` 22.18 seconds
15 * `msgpack.pack()` 5.80 seconds
16 * `msgpack.unpack(msgpack.pack())` 8.62 seconds
17
18 Note that `node-msgpack` produces and consumes Buffer objects, and a such does
19 not incur encoding/decoding overhead when performing I/O with native strings.
20
bed0760 @pgriess Add example code and CLI tools to README.md.
authored
21 ### Usage
22
23 This module provides two methods: `pack()`, which consumes a JavaScript object
24 and produces a node Buffer object; and `unpack()`, which consumes a node Buffer
5db0865 @pgriess Add type mapping rules to README.md.
authored
25 object and produces a JavaScript object. Packing of all native JavaScript types
26 (undefined, boolean, numbers, strings, arrays and objects) is supported, as
27 is the node Buffer type.
bed0760 @pgriess Add example code and CLI tools to README.md.
authored
28
29 The below code snippet packs and then unpacks a JavaScript object, verifying
30 the resulting object at the end using `assert.deepEqual()`.
31
32 var assert = require('assert');
33 var msgpack = require('msgpack');
34
35 var o = {"a" : 1, "b" : 2, "c" : [1, 2, 3]};
36 var b = msgpack.pack(o);
37 var oo = msgpack.unpack(b);
38
39 assert.deepEqual(oo, o);
40
c189d23 @pgriess Add msgpack.Stream documentation.
authored
41 As a convenience, a higher level streaming API is provided in the
42 `msgpack.Stream` class, which can be constructed around a `net.Stream`
43 instance. This object emits `msg` events when an object has been received.
44
45 var msgpack = require('msgpack');
46
47 // ... get a net.Stream instance, s, from somewhere
ba5d037 @pgriess Minor cleanup to README.md.
authored
48
c189d23 @pgriess Add msgpack.Stream documentation.
authored
49 var ms = new msgpack.Stream(s);
50 ms.addListener('msg', function(m) {
51 sys.debug('received message: ' + sys.inspect(m));
52 });
53
5db0865 @pgriess Add type mapping rules to README.md.
authored
54 ### Type Mapping
55
56 The JavaScript type system does not map cleanly on to the MsgPack type system,
57 though it's pretty close.
58
59 When packing, JavaScript values are mapped to MsgPack types as follows
60
61 * `undefined` and `null` values map to `MSGPACK_OBJECT_NIL`
62 * `boolean` values map to `MSGPACK_OBJECT_BOOLEAN`
63 * `number` values map differently depending on their value
64 * Floating point values map to `MSGPACK_OBJECT_DOUBLE`
65 * Positive values map to `MSGPACK_OBJECT_POSITIVE_INTEGER`
66 * Negative values map to `MSGPACK_OBJECT_NEGATIVE_INTEGER`
67 * `string` values map to `MSGPACK_OBJECT_RAW`; all strings are serialized
68 with UTF-8 encoding
69 * Array values (as defined by `Array.isArray()`) map to
70 `MSGPACK_OBJECT_ARRAY`; each element in the array is packed individually
71 the rules in this list
72 * NodeJS Buffer values map to `MSGPACK_OBJECT_RAW`
73 * Everything else maps to `MSGPACK_OBJECT_MAP`, where we iterate over the object's
74 properties and pack them and their values as per the mappings in this list
75
76 When unpacking, MsgPack types are mapped to JavaScript values as follows
77
78 * `MSGPACK_OBJECT_NIL` values map to the `null` value
79 * `MSGPACK_OBJECT_BOOLEAN` values map to `boolean` values
80 * `MSGPACK_OBJECT_POSITIVE_INTEGER`, `MSGPACK_OBJECT_NEGATIVE_INTEGER` and
81 `MSGPACK_OBJECT_DOUBLE` values map to `number` values
82 * `MSGPACK_OBJECT_ARRAY` values map to arrays; each object in the array is
83 packed individually using the rules in this list
84 * `MSGPACK_OBJECT_RAW` values are mapped to `string` values; these values are
85 unpacked using either UTF-8 or ASCII encoding, depending on the contents
86 of the raw buffer
87 * `MSGPACK_OBJECT_MAP` values are mapped to JavaScript objects; keys and values
88 are unpacked individually using the rules in this list
89
90 Strings are particularly problematic here, as it's difficult to get hints down
91 into the packing and unpacking codepaths about how to interpret a particular
92 string or `MSGPACK_OBJECT_RAW`. If you have strict requirements about the
93 encoding of your strings, it's recommended that you populate a Buffer object
94 yourself (e.g. using `Buffer.write()`) and pack that buffer rather than the
95 string. This will ensure that you can control what gets packed.
96
97 When unpacking, things are trickier as there is no way to know the encoding
98 used when a string was packed. There is an [an open
99 ticket](http://github.com/msgpack/msgpack/issues/issue/13) for the MsgPack
100 format to address this.
101
bed0760 @pgriess Add example code and CLI tools to README.md.
authored
102 ### Command Line Utilities
103
104 As a convenience and for debugging, `bin/json2msgpack` and `bin/msgpack2json`
105 are provided to convert JSON data to and from MessagePack data, reading from
106 stdin and writing to stdout.
107
7a021b1 @pgriess Add some CLI examples.
authored
108 % echo '[1, 2, 3]' | ./bin/json2msgpack | xxd -
109 0000000: 9301 0203 ....
110 % echo '[1, 2, 3]' | ./bin/json2msgpack | ./bin/msgpack2json
111 [1,2,3]
112
861cc6e @pgriess Add README.
authored
113 ### Building and installation
114
8760280 @tomtaylor Updating README and adding repository to package.json
tomtaylor authored
115 There are two ways to install msgpack.
2addb41 @pgriess Note dependency on unreleased nodejs.
authored
116
8760280 @tomtaylor Updating README and adding repository to package.json
tomtaylor authored
117 ## npm
118
119 npm install msgpack
120
121 This should build and install msgpack for you. Then just `require('msgpack')`.
122
123 ## Manually
124
125 Use `make` to build the add-on, then manually copy `build/default/mpBindings.node`
126 and `lib/msgpack.js` it to wherever your node.js installation will look for it (or
127 add the build directory to your `$NODE_PATH`).
861cc6e @pgriess Add README.
authored
128
129 % ls
130 LICENSE Makefile README.md deps/ src/ tags test.js
131 % make
132
133 The MessagePack library on which this depends is packaged with `node-msgpack`
134 and will be built as part of this process.
135
136 **Note:** MessagePack may fail to build if you do not have a modern version of
137 gcc in your `$PATH`. On Mac OS X Snow Leopard (10.5.x), you may have to use
138 `gcc-4.2`, which should come with your box but is not used by default.
139
140 % make CC=gcc-4.2 CXX=gcc-4.2
Something went wrong with that request. Please try again.