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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Encoder
✓ import { Encoder } from 'socket.io-parser'
✗ const Encoder = require('socket.io-parser').Encoder
The package ships with its own TypeScript types. Use named imports for ESM environments.
Decoder
✓ import { Decoder } from 'socket.io-parser'
✗ const Decoder = require('socket.io-parser').Decoder
The Decoder class is an EventEmitter and emits a 'decoded' event upon successful packet reconstruction.
PacketType.EVENT
✓ import { PacketType } from 'socket.io-parser'
✗ import { EVENT } from 'socket.io-parser'
Protocol constants like `EVENT`, `CONNECT`, `DISCONNECT`, `ACK`, etc., are exposed via the `PacketType` enum (or `parser.EVENT` in CJS `require` context).
Demonstrates how to manually encode and decode a Socket.IO event packet using `Encoder` and `Decoder` classes, including handling packet types and verifying data integrity.
import { Encoder, Decoder, PacketType } from 'socket.io-parser';
import { EventEmitter } from 'events';
// Polyfill EventEmitter for Decoder in browser contexts if needed
// Decoder.prototype.__proto__ = EventEmitter.prototype; // Example if not using modern polyfills
interface MyPacket {
type: PacketType;
data: any;
id?: number;
nsp: string;
}
const encoder = new Encoder();
const decoder = new Decoder();
// Simulate an outgoing Socket.IO event packet
const originalPacket: MyPacket = {
type: PacketType.EVENT,
data: ['hello', { world: true, value: 123 }],
id: 42,
nsp: '/',
};
console.log('Original Packet:', originalPacket);
encoder.encode(originalPacket, (encodedPackets: (string | Buffer)[]) => {
console.log('Encoded Packets:', encodedPackets);
let decodedPacket: MyPacket | undefined;
decoder.on('decoded', (packet: MyPacket) => {
decodedPacket = packet;
console.log('Decoded Packet:', decodedPacket);
// Verify the decoded packet
if (
decodedPacket.type === originalPacket.type &&
JSON.stringify(decodedPacket.data) === JSON.stringify(originalPacket.data) &&
decodedPacket.id === originalPacket.id &&
decodedPacket.nsp === originalPacket.nsp
) {
console.log('Packet encoding and decoding successful!');
} else {
console.error('Packet mismatch after encoding/decoding.');
}
});
for (const chunk of encodedPackets) {
decoder.add(chunk);
}
});
Debug
Known issues
breakingA critical vulnerability, CVE-2026-33151, related to binary attachment limits, was discovered. This could lead to resource exhaustion if not mitigated.fixUpgrade `socket.io-parser` to version 4.2.6, 3.4.4, 3.3.5, or newer. These versions include fixes that add a limit to the number of binary attachments.
affects: <4.2.6, <3.4.4, <3.3.5
gotcha`socket.io-parser` is an internal component of the Socket.IO ecosystem. While its API is exposed, direct usage by application developers is generally discouraged unless implementing custom parsers for Socket.IO, as internal protocol changes might occur between major Socket.IO versions, potentially breaking direct integrations.fixFor most use cases, interact with Socket.IO through `socket.io` and `socket.io-client` packages, which correctly utilize `socket.io-parser` internally. Only use `socket.io-parser` directly if you fully understand the Socket.IO protocol specification and intend to replace or extend default parsing behavior.
affects: >=3.x
gotchaThe `Decoder` class is an `EventEmitter`. When receiving encoded chunks, you must `add` each chunk sequentially and listen for the `decoded` event to obtain the complete Socket.IO packet, especially with binary data where a single logical packet might be split across multiple encoded chunks.fixAlways use the `decoder.on('decoded', callback)` pattern and feed chunks using `decoder.add(chunk)` to ensure correct packet reassembly. Do not assume `decoder.add` immediately returns a complete packet. affects: >=3.x
Errors
Common errors & fixes
TypeError: (0 , socket_io_parser_1.Encoder) is not a constructor
Attempting to use `require` syntax (`const { Encoder } = require('socket.io-parser')`) in a pure ESM context, or incorrect named import in TypeScript/ESM.
fixEnsure you are using correct ES module named imports: `import { Encoder, Decoder } from 'socket.io-parser';`. If in CommonJS, use `const { Encoder, Decoder } = require('socket.io-parser');` TypeError: Cannot read properties of undefined (reading 'encode')
Attempting to call `encode` or `decode` methods directly on the imported `Encoder` or `Decoder` symbols without instantiating them first.
fixBoth `Encoder` and `Decoder` are classes and must be instantiated with `new` before use: `const encoder = new Encoder();` and `const decoder = new Decoder();`.
Audit
Dependencies
debugrequiredUsed for logging and debugging internal parser operations.