CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-engine-io-parser

Parser for the engine.io protocol encoding, handling packet and payload encoding/decoding with binary support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

packet-operations.mddocs/

Packet Operations

Core functionality for encoding and decoding individual engine.io protocol packets with support for all packet types and binary data formats.

Capabilities

Packet Encoding

Encodes a packet object into the engine.io wire format, with automatic binary data handling based on environment and support flags.

/**
 * Encodes a packet into engine.io wire format
 * @param packet - The packet to encode containing type and optional data
 * @param supportsBinary - Whether binary data should be preserved or base64 encoded
 * @param callback - Callback receiving the encoded packet data
 */
function encodePacket(
  packet: Packet,
  supportsBinary: boolean,
  callback: (encodedPacket: RawData) => void
): void;

Usage Examples:

import { encodePacket, Packet } from "engine.io-parser";

// Text packet encoding
const textPacket: Packet = { type: "message", data: "hello" };
encodePacket(textPacket, true, (encoded) => {
  console.log(encoded); // "4hello"
});

// Binary packet encoding (Node.js)
const binaryPacket: Packet = { 
  type: "message", 
  data: Buffer.from([1, 2, 3, 4]) 
};
encodePacket(binaryPacket, true, (encoded) => {
  console.log(encoded); // Buffer containing binary data
});

// Binary packet with base64 fallback
encodePacket(binaryPacket, false, (encoded) => {
  console.log(encoded); // "bAQIDBA==" (base64 encoded)
});

// Control packets (no data)
const pingPacket: Packet = { type: "ping" };
encodePacket(pingPacket, true, (encoded) => {
  console.log(encoded); // "2"
});

Packet Decoding

Decodes wire format data back into packet objects, with automatic binary format conversion based on the specified binary type.

/**
 * Decodes wire format data into a packet object
 * @param encodedPacket - The encoded packet data (string or binary)
 * @param binaryType - How to handle binary data ("nodebuffer", "arraybuffer", "blob")
 * @returns Decoded packet object or error packet for malformed data
 */
function decodePacket(
  encodedPacket: RawData,
  binaryType?: BinaryType
): Packet;

Usage Examples:

import { decodePacket, BinaryType } from "engine.io-parser";

// Text packet decoding
const decodedText = decodePacket("4hello");
console.log(decodedText); // { type: "message", data: "hello" }

// Control packet decoding
const decodedPing = decodePacket("2probe");
console.log(decodedPing); // { type: "ping", data: "probe" }

// Binary packet decoding (Node.js)
const buffer = Buffer.from([1, 2, 3, 4]);
const decodedBinary = decodePacket(buffer, "nodebuffer");
console.log(decodedBinary); // { type: "message", data: Buffer }

// Base64 binary packet decoding
const decodedBase64 = decodePacket("bAQIDBA==", "arraybuffer");
console.log(decodedBase64); // { type: "message", data: ArrayBuffer }

// Error handling for malformed packets
const errorPacket = decodePacket("invalid");
console.log(errorPacket); // { type: "error", data: "parser error" }

Packet Types

The engine.io protocol defines seven packet types, each with a specific numeric code:

type PacketType = 
  | "open"     // 0 - Connection open
  | "close"    // 1 - Connection close  
  | "ping"     // 2 - Ping packet
  | "pong"     // 3 - Pong response
  | "message"  // 4 - Data message
  | "upgrade"  // 5 - Transport upgrade
  | "noop"     // 6 - No operation
  | "error";   // Generated for malformed packets

Data Types

type RawData = any; // string | Buffer | ArrayBuffer | ArrayBufferView | Blob

type BinaryType = "nodebuffer" | "arraybuffer" | "blob";

interface Packet {
  type: PacketType;
  options?: { compress: boolean };
  data?: RawData;
}

Platform Differences

Node.js Environment

  • Binary data handled as Buffer objects
  • Direct buffer operations for optimal performance
  • Support for all binary data types

Browser Environment

  • Binary data handled as Blob or ArrayBuffer
  • FileReader API used for base64 conversion when needed
  • Automatic fallback for environments without binary support

Error Handling

All decoding functions return a standardized error packet for malformed input:

const ERROR_PACKET: Packet = { type: "error", data: "parser error" };

This ensures consistent error handling across all parser operations.

Install with Tessl CLI

npx tessl i tessl/npm-engine-io-parser

docs

index.md

packet-operations.md

payload-operations.md

streaming-operations.md

tile.json