or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md packet-operations.md payload-operations.md streaming-operations.md

tile.json

Payload Operations

Functionality for handling multiple packets as a single payload using ASCII delimiter separation, enabling efficient batch processing of engine.io protocol messages.

Capabilities

Payload Encoding

Encodes multiple packets into a single payload string using ASCII character 30 (0x1E) as the delimiter between encoded packets.

/**
 * Encodes multiple packets into a single payload string
 * @param packets - Array of packets to encode into payload
 * @param callback - Callback receiving the encoded payload string
 */
function encodePayload(
  packets: Packet[],
  callback: (encodedPayload: string) => void
): void;

Usage Examples:

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

// Multiple text packets
const packets: Packet[] = [
  { type: "ping", data: "probe" },
  { type: "message", data: "hello" },
  { type: "close" }
];

encodePayload(packets, (payload) => {
  console.log(payload); // "2probe\x1e4hello\x1e1"
  // \x1e is the ASCII separator character (char code 30)
});

// Mixed packet types
const mixedPackets: Packet[] = [
  { type: "open", data: '{"sid":"abc123"}' },
  { type: "message", data: "user message" },
  { type: "ping" }
];

encodePayload(mixedPackets, (payload) => {
  console.log(payload); // '0{"sid":"abc123"}\x1e4user message\x1e2'
});

// Binary packets (encoded as base64)
const binaryPackets: Packet[] = [
  { type: "message", data: Buffer.from([1, 2, 3]) },
  { type: "message", data: "text after binary" }
];

encodePayload(binaryPackets, (payload) => {
  // Binary data is automatically base64 encoded in payloads
  console.log(payload); // "bAQID\x1e4text after binary"
});

Payload Decoding

Decodes a payload string back into an array of individual packets, with automatic error handling for malformed payloads.

/**
 * Decodes a payload string into an array of packets
 * @param encodedPayload - The payload string to decode
 * @param binaryType - How to handle binary data ("nodebuffer", "arraybuffer", "blob")
 * @returns Array of decoded packets, stops at first error packet
 */
function decodePayload(
  encodedPayload: string,
  binaryType?: BinaryType
): Packet[];

Usage Examples:

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

// Basic payload decoding
const payload = "2probe\x1e4hello\x1e1";
const packets = decodePayload(payload);
console.log(packets);
// [
//   { type: "ping", data: "probe" },
//   { type: "message", data: "hello" },
//   { type: "close" }
// ]

// Binary data handling
const binaryPayload = "bAQID\x1e4text message";
const binaryPackets = decodePayload(binaryPayload, "nodebuffer");
console.log(binaryPackets);
// [
//   { type: "message", data: Buffer.from([1, 2, 3]) },
//   { type: "message", data: "text message" }
// ]

// ArrayBuffer binary handling (browser)
const arrayBufferPackets = decodePayload(binaryPayload, "arraybuffer");
console.log(arrayBufferPackets);
// [
//   { type: "message", data: ArrayBuffer containing [1, 2, 3] },
//   { type: "message", data: "text message" }
// ]

// Error handling for malformed payloads
const malformedPayload = "invalid\x1e4valid";
const errorPackets = decodePayload(malformedPayload);
console.log(errorPackets);
// [{ type: "error", data: "parser error" }]
// Stops at first error, doesn't process remaining packets

Payload Format

Payloads use a simple concatenation format with ASCII delimiter separation:

[encoded_packet_1][SEPARATOR][encoded_packet_2][SEPARATOR]...[encoded_packet_n]

Where:

SEPARATOR is ASCII character 30 (0x1E)
Each encoded packet follows standard engine.io packet encoding rules
Binary data in payloads is always base64 encoded (prefixed with 'b')

Binary Data Handling

Encoding Behavior

All binary data in payloads is converted to base64 format
Base64 encoded packets are prefixed with 'b' character
This ensures payload remains a valid string for transmission

Decoding Behavior

Base64 packets (prefixed with 'b') are automatically decoded
Final binary format depends on binaryType parameter:
- "nodebuffer": Returns Buffer objects (Node.js default)
- "arraybuffer": Returns ArrayBuffer objects
- "blob": Returns Blob objects (browser only)

Error Handling

Malformed Payload Processing

Decoding stops at the first malformed packet encountered
Returns an array containing only an error packet: [{ type: "error", data: "parser error" }]
Does not attempt to process remaining packets after an error

Empty Payloads

Empty strings decode to empty arrays: []
Single separator characters are handled gracefully

Performance Considerations

Encoding Performance

Operations are queued and executed asynchronously
Callback is invoked only after all packets are encoded
Length is captured at start to handle dynamic packet additions during encoding

Memory Usage

Payloads are concatenated in memory as strings
For large binary data, consider using streaming operations instead
Base64 encoding increases binary data size by ~33%

Types

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

type PacketType = 
  | "open" | "close" | "ping" | "pong" 
  | "message" | "upgrade" | "noop" | "error";

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

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

Version

Tile

Files