Engine.IO Parser

5.2.3 verified Thu Apr 23 auth: no javascript

engine.io-parser is a foundational JavaScript parser library responsible for encoding and decoding packets and payloads for the Engine.IO protocol, which underpins Socket.IO. It enables seamless communication by handling various data types including strings, numbers, buffers, and ArrayBuffers across both Node.js and browser environments. The current stable version is 5.2.3, and it is actively maintained as part of the broader Socket.IO ecosystem, receiving updates alongside major Socket.IO releases. Its key differentiators include robust cross-environment compatibility (Node.js, browser, WebWorkers) and flexible binary data handling (encoding to/from ArrayBuffer, Blob, or Buffer), making it a critical component for real-time, low-level data transmission.

Common errors

error TypeError: parser.encodePacket is not a function ↓

cause Incorrect import statement for ESM, attempting to destructure named exports when a namespace import or default export (if applicable) is needed, or vice-versa.

fix

For ESM, try import * as parser from 'engine.io-parser'; then use parser.encodePacket(...). If individual functions are exported, use import { encodePacket } from 'engine.io-parser';.

error ReferenceError: Buffer is not defined ↓

cause Attempting to use Node.js `Buffer` objects in a browser environment without a polyfill or proper bundling for Node.js APIs.

fix

When running in a browser, ensure you are providing ArrayBuffer or Blob objects for binary data instead of Node.js Buffer objects. If using a bundler like Webpack or Browserify, ensure buffer is polyfilled or correctly configured for browser usage.

Warnings

gotcha The API primarily uses callback-based asynchronous patterns for encoding and decoding operations. Developers accustomed to Promise-based or async/await syntax may find this less ergonomic, potentially leading to nested callbacks (callback hell) if not managed with utilities like `util.promisify`. ↓

fix Consider wrapping callback-based functions with `util.promisify` in Node.js or creating custom Promise wrappers for a more modern async experience.

gotcha When handling binary data, `engine.io-parser` automatically encodes it as base64 strings within payloads if not explicitly handled as raw binary. While convenient for universal transport, this can introduce a performance overhead due to increased data size and encoding/decoding CPU cycles, especially for large binary payloads. Be aware of the `binary support` parameter in `encodePacket` and the `binary type` in `decodePacket`. ↓

fix Optimize binary handling by understanding when base64 encoding occurs. For direct binary transport, ensure your transport layer (e.g., WebSocket) is configured to handle ArrayBuffers or Buffers natively and that `engine.io-parser`'s specific binary flags are correctly utilized.

gotcha The representation of binary data (Buffer, ArrayBuffer, Blob) varies between Node.js and browser environments. While `engine.io-parser` abstracts some of this, direct manipulation or assumptions about the underlying binary type can lead to cross-environment bugs if not carefully handled. `decodePacket` can return `ArrayBuffer` in Node.js, but `Blob` in browsers. ↓

fix Always check the specific type of binary data returned (e.g., `instanceof Buffer` in Node, `instanceof ArrayBuffer` or `instanceof Blob` in browser) and write platform-agnostic code or branch logic as needed.

Install

npm install engine.io-parser

yarn add engine.io-parser

pnpm add engine.io-parser

Imports

parser
wrong
```
import parser from 'engine.io-parser';
```
correct
```
import * as parser from 'engine.io-parser';
```
While CommonJS uses a default-like `require('engine.io-parser')`, ESM typically exposes functions as named exports or a namespace object for internal libraries. Using `* as parser` ensures compatibility with the object-oriented API shown in documentation.
encodePacket
wrong
```
const { encodePacket } = require('engine.io-parser');
```
correct
```
import { encodePacket } from 'engine.io-parser';
```
For ESM, individual functions can be directly imported. For CommonJS, these are methods on the main 'parser' object.
decodePayload
wrong
```
import { Parser } from 'engine.io-parser';
```
correct
```
import { decodePayload } from 'engine.io-parser';
```
Key parsing functions like `decodePayload` are named exports. There is no `Parser` class for direct instantiation; methods are exposed directly or via the main imported object.

Quickstart

This quickstart demonstrates encoding and decoding single Engine.IO packets and multi-packet payloads, including binary data, showcasing the library's core functionality.

import { encodePacket, decodePacket, encodePayload, decodePayload } from 'engine.io-parser';
import { Buffer } from 'buffer'; // Node.js Buffer for example

const data = Buffer.from([ 1, 2, 3, 4 ]);

console.log('--- Packet Encoding/Decoding ---');
encodePacket({ type: 'message', data }, true, encoded => {
  console.log('Encoded Packet:', encoded); // Should be a string or ArrayBuffer
  const decodedPacket = decodePacket(encoded, 'arraybuffer');
  console.log('Decoded Packet:', decodedPacket.data); // Should be { type: 'message', data: ArrayBuffer }
});

console.log('\n--- Payload Encoding/Decoding ---');
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 world' }
];

encodePayload(packets, encodedPayload => {
  console.log('Encoded Payload:', encodedPayload);
  decodePayload(encodedPayload, (packet, index, total) => {
    console.log(`Decoded Payload Packet ${index + 1}/${total}:`, packet);
    if (index === 0) {
      console.log('  Binary data (ArrayBuffer):', new Int8Array(packet.data));
    } else {
      console.log('  String data:', packet.data);
    }
  });
});