{"id":17592,"library":"engine.io-parser","title":"Engine.IO Parser","description":"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.","status":"active","version":"5.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/socketio/socket.io","tags":["javascript","typescript"],"install":[{"cmd":"npm install engine.io-parser","lang":"bash","label":"npm"},{"cmd":"yarn add engine.io-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add engine.io-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import parser from 'engine.io-parser';","symbol":"parser","correct":"import * as parser from 'engine.io-parser';"},{"note":"For ESM, individual functions can be directly imported. For CommonJS, these are methods on the main 'parser' object.","wrong":"const { encodePacket } = require('engine.io-parser');","symbol":"encodePacket","correct":"import { encodePacket } from 'engine.io-parser';"},{"note":"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.","wrong":"import { Parser } from 'engine.io-parser';","symbol":"decodePayload","correct":"import { decodePayload } from 'engine.io-parser';"}],"quickstart":{"code":"import { encodePacket, decodePacket, encodePayload, decodePayload } from 'engine.io-parser';\nimport { Buffer } from 'buffer'; // Node.js Buffer for example\n\nconst data = Buffer.from([ 1, 2, 3, 4 ]);\n\nconsole.log('--- Packet Encoding/Decoding ---');\nencodePacket({ type: 'message', data }, true, encoded => {\n  console.log('Encoded Packet:', encoded); // Should be a string or ArrayBuffer\n  const decodedPacket = decodePacket(encoded, 'arraybuffer');\n  console.log('Decoded Packet:', decodedPacket.data); // Should be { type: 'message', data: ArrayBuffer }\n});\n\nconsole.log('\\n--- Payload Encoding/Decoding ---');\nconst testBuffer = new Int8Array(10);\nfor (let i = 0; i < testBuffer.length; i++) testBuffer[i] = i;\n\nconst packets = [\n  { type: 'message', data: testBuffer.buffer },\n  { type: 'message', data: 'hello world' }\n];\n\nencodePayload(packets, encodedPayload => {\n  console.log('Encoded Payload:', encodedPayload);\n  decodePayload(encodedPayload, (packet, index, total) => {\n    console.log(`Decoded Payload Packet ${index + 1}/${total}:`, packet);\n    if (index === 0) {\n      console.log('  Binary data (ArrayBuffer):', new Int8Array(packet.data));\n    } else {\n      console.log('  String data:', packet.data);\n    }\n  });\n});","lang":"typescript","description":"This quickstart demonstrates encoding and decoding single Engine.IO packets and multi-packet payloads, including binary data, showcasing the library's core functionality."},"warnings":[{"fix":"Consider wrapping callback-based functions with `util.promisify` in Node.js or creating custom Promise wrappers for a more modern async experience.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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';`.","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.","error":"TypeError: parser.encodePacket is not a function"},{"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.","cause":"Attempting to use Node.js `Buffer` objects in a browser environment without a polyfill or proper bundling for Node.js APIs.","error":"ReferenceError: Buffer is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}