Registry / serialization / engine.io-parser

engine.io-parser

library5.2.3jsnpmunverified

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.

serialization http-networking communication

npm install engine.io-parser

github ↗package ↗

INSTALL

IMPORT

SIG · ENGINE.IO-PARSER

engine.io-parser

serializationjavascriptv5.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parser

✓ import * as parser from 'engine.io-parser';

✗ import 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

✓ import { encodePacket } from 'engine.io-parser';

✗ const { encodePacket } = require('engine.io-parser');

For ESM, individual functions can be directly imported. For CommonJS, these are methods on the main 'parser' object.

decodePayload

✓ import { decodePayload } from 'engine.io-parser';

✗ import { Parser } 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.

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); } }); });

Debug

Known issues

gotchaThe 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: parser.encodePacket is not a function

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';`.

ReferenceError: Buffer is not defined

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.

Upgrade

Version history

5.2.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/socketio/socket.io ↗

packagehttps://www.npmjs.com/package/engine.io-parser ↗