Readme.md (6317B)
1 2 # engine.io-parser 3 4 [](https://travis-ci.org/socketio/engine.io-parser) 5 [](https://npmjs.com/package/engine.io-parser) 6 7 This is the JavaScript parser for the engine.io protocol encoding, 8 shared by both 9 [engine.io-client](https://github.com/socketio/engine.io-client) and 10 [engine.io](https://github.com/socketio/engine.io). 11 12 ## How to use 13 14 ### Standalone 15 16 The parser can encode/decode packets, payloads, and payloads as binary 17 with the following methods: `encodePacket`, `decodePacket`, `encodePayload`, 18 `decodePayload`, `encodePayloadAsBinary`, `decodePayloadAsBinary`. 19 20 The browser-side parser also includes `encodePayloadAsArrayBuffer` and `encodePayloadAsBlob`. 21 22 Example: 23 24 ```js 25 var parser = require('engine.io-parser'); 26 27 var data = new Buffer(5); 28 for (var i = 0; i < data.length; i++) { data[i] = i; } 29 30 parser.encodePacket({ type: 'message', data: data }, function(encoded) { 31 var decodedData = parser.decodePacket(encoded); // { type: 'message', data: data } 32 }); 33 ``` 34 35 ### With browserify 36 37 Engine.IO Parser is a commonjs module, which means you can include it by using 38 `require` on the browser and package using [browserify](http://browserify.org/): 39 40 1. install the parser package 41 42 ```shell 43 npm install engine.io-parser 44 ``` 45 46 1. write your app code 47 48 ```js 49 var parser = require('engine.io-parser'); 50 51 var testBuffer = new Int8Array(10); 52 for (var i = 0; i < testBuffer.length; i++) testBuffer[i] = i; 53 54 var packets = [{ type: 'message', data: testBuffer.buffer }, { type: 'message', data: 'hello' }]; 55 56 parser.encodePayload(packets, function(encoded) { 57 parser.decodePayload(encoded, 58 function(packet, index, total) { 59 var isLast = index + 1 == total; 60 if (!isLast) { 61 var buffer = new Int8Array(packet.data); // testBuffer 62 } else { 63 var message = packet.data; // 'hello' 64 } 65 }); 66 }); 67 ``` 68 69 1. build your app bundle 70 71 ```bash 72 $ browserify app.js > bundle.js 73 ``` 74 75 1. include on your page 76 77 ```html 78 <script src="/path/to/bundle.js"></script> 79 ``` 80 81 ## Features 82 83 - Runs on browser and node.js seamlessly 84 - Runs inside HTML5 WebWorker 85 - Can encode and decode packets 86 - Encodes from/to ArrayBuffer or Blob when in browser, and Buffer or ArrayBuffer in Node 87 88 ## API 89 90 Note: `cb(type)` means the type is a callback function that contains a parameter of type `type` when called. 91 92 ### Node 93 94 - `encodePacket` 95 - Encodes a packet. 96 - **Parameters** 97 - `Object`: the packet to encode, has `type` and `data`. 98 - `data`: can be a `String`, `Number`, `Buffer`, `ArrayBuffer` 99 - `Boolean`: optional, binary support 100 - `Function`: callback, returns the encoded packet (`cb(String)`) 101 - `decodePacket` 102 - Decodes a packet. Data also available as an ArrayBuffer if requested. 103 - Returns data as `String` or (`Blob` on browser, `ArrayBuffer` on Node) 104 - **Parameters** 105 - `String` | `ArrayBuffer`: the packet to decode, has `type` and `data` 106 - `String`: optional, the binary type 107 108 - `encodeBase64Packet` 109 - Encodes a packet with binary data in a base64 string (`String`) 110 - **Parameters** 111 - `Object`: the packet to encode, has `type` and `data` 112 - `Function`: callback, returns the base64 encoded message (`cb(String)`) 113 - `decodeBase64Packet` 114 - Decodes a packet encoded in a base64 string. 115 - **Parameters** 116 - `String`: the base64 encoded message 117 - `String`: optional, the binary type 118 119 - `encodePayload` 120 - Encodes multiple messages (payload). 121 - If any contents are binary, they will be encoded as base64 strings. Base64 122 encoded strings are marked with a b before the length specifier 123 - **Parameters** 124 - `Array`: an array of packets 125 - `Boolean`: optional, binary support 126 - `Function`: callback, returns the encoded payload (`cb(String)`) 127 - `decodePayload` 128 - Decodes data when a payload is maybe expected. Possible binary contents are 129 decoded from their base64 representation. 130 - **Parameters** 131 - `String`: the payload 132 - `String`: optional, the binary type 133 - `Function`: callback, returns (cb(`Object`: packet, `Number`:packet index, `Number`:packet total)) 134 135 - `encodePayloadAsBinary` 136 - Encodes multiple messages (payload) as binary. 137 - **Parameters** 138 - `Array`: an array of packets 139 - `Function`: callback, returns the encoded payload (`cb(Buffer)`) 140 - `decodePayloadAsBinary` 141 - Decodes data when a payload is maybe expected. Strings are decoded by 142 interpreting each byte as a key code for entries marked to start with 0. See 143 description of encodePayloadAsBinary. 144 - **Parameters** 145 - `Buffer`: the buffer 146 - `String`: optional, the binary type 147 - `Function`: callback, returns the decoded packet (`cb(Object)`) 148 149 ### Browser 150 151 - `encodePayloadAsArrayBuffer` 152 - Encodes multiple messages (payload) as binary. 153 - **Parameters** 154 - `Array`: an array of packets 155 - `Function`: callback, returns the encoded payload (`cb(ArrayBuffer)`) 156 - `encodePayloadAsBlob` 157 - Encodes multiple messages (payload) as blob. 158 - **Parameters** 159 - `Array`: an array of packets 160 - `Function`: callback, returns the encoded payload (`cb(Blob)`) 161 162 ## Tests 163 164 Standalone tests can be run with `make test` which will run both node.js and browser tests. 165 166 Browser tests are run using [zuul](https://github.com/defunctzombie/zuul). 167 (You must have zuul setup with a saucelabs account.) 168 169 You can run the tests locally using the following command: 170 171 ``` 172 ./node_modules/.bin/zuul --local 8080 -- test/index.js 173 ``` 174 175 ## Support 176 177 The support channels for `engine.io-parser` are the same as `socket.io`: 178 - irc.freenode.net **#socket.io** 179 - [Google Groups](http://groups.google.com/group/socket_io) 180 - [Website](http://socket.io) 181 182 ## Development 183 184 To contribute patches, run tests or benchmarks, make sure to clone the 185 repository: 186 187 ```bash 188 git clone git://github.com/LearnBoost/engine.io-parser.git 189 ``` 190 191 Then: 192 193 ```bash 194 cd engine.io-parser 195 npm install 196 ``` 197 198 See the `Tests` section above for how to run tests before submitting any patches. 199 200 ## License 201 202 MIT