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