or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

event-handling.mdindex.mdsocket-connection.mdtransport-system.mdutility-functions.md
tile.json

tessl/npm-engine-io-client

Client for the realtime Engine providing bidirectional communication with WebSocket, polling, and WebTransport support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/engine.io-client@6.6.x

To install, run

npx @tessl/cli install tessl/npm-engine-io-client@6.6.0

index.mddocs/

Engine.IO Client

Engine.IO Client is a lightweight library providing real-time bidirectional communication between browsers and servers. It serves as the transport layer for Socket.IO and supports multiple transport protocols including WebSocket, polling, and WebTransport with automatic fallback mechanisms for reliable cross-platform connectivity.

Package Information

  • Package Name: engine.io-client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install engine.io-client

Core Imports

import { Socket, SocketOptions } from "engine.io-client";

For CommonJS:

const { Socket, SocketOptions } = require("engine.io-client");

Tree-shaking imports:

import { SocketWithoutUpgrade, WebSocket } from "engine.io-client";

Basic Usage

import { Socket } from "engine.io-client";

// Create and connect to server
const socket = new Socket("ws://localhost:3000");

// Listen for connection events
socket.on("open", () => {
  console.log("Connected to server");
  
  // Send data
  socket.send("Hello server!");
});

// Handle incoming messages
socket.on("message", (data) => {
  console.log("Received:", data);
});

// Handle errors and close events
socket.on("error", (error) => {
  console.error("Connection error:", error);
});

socket.on("close", (reason) => {
  console.log("Connection closed:", reason);
});

Architecture

Engine.IO Client is built around several key components:

  • Socket Classes: Three socket variants (Socket, SocketWithUpgrade, SocketWithoutUpgrade) providing different levels of transport upgrade capability
  • Transport System: Pluggable transport implementations (WebSocket, Polling, WebTransport) with automatic fallback
  • Event System: EventEmitter-based architecture for handling connection lifecycle and data flow
  • Binary Support: Native handling of various binary data types (ArrayBuffer, Blob, Buffer)
  • Cross-platform: Unified API supporting both browser and Node.js environments with platform-specific optimizations

Capabilities

Socket Connection Management

Core socket functionality for establishing and managing real-time connections with multiple transport support and automatic upgrading.

class Socket extends SocketWithUpgrade {
  constructor(uri?: string, opts?: SocketOptions);
  constructor(opts: SocketOptions);
  constructor(uri?: string | SocketOptions, opts?: SocketOptions);
  
  // Public properties
  id: string;
  transport: Transport;
  binaryType: BinaryType;
  readyState: SocketState;
  writeBuffer: Packet[];
  
  // Public methods
  send(msg: RawData, options?: WriteOptions, fn?: () => void): Socket;
  write(msg: RawData, options?: WriteOptions, fn?: () => void): Socket;
  close(): Socket;
  
  // Static properties
  static protocol: number;
  static priorWebsocketSuccess: boolean;
}

type SocketState = "opening" | "open" | "closing" | "closed";
type BinaryType = "blob" | "arraybuffer";

Socket Connection Management

Transport System

Pluggable transport layer supporting WebSocket, polling, and WebTransport protocols with automatic fallback and upgrade mechanisms.

interface SocketOptions {
  // Connection options
  host?: string;
  hostname?: string;
  secure?: boolean;
  port?: string | number;
  query?: { [key: string]: any };
  
  // Transport configuration
  transports?: ("polling" | "websocket" | "webtransport" | string)[];
  upgrade?: boolean;
  tryAllTransports?: boolean;
  rememberUpgrade?: boolean;
  
  // Protocol options
  forceBase64?: boolean;
  timestampParam?: string;
  timestampRequests?: boolean;
  requestTimeout?: number;
  path?: string;
  addTrailingSlash?: boolean;
  protocols?: string | string[];
}

abstract class Transport extends Emitter {
  query: Record<string, string>;
  writable: boolean;
  open(): Transport;
  close(): Transport;
}

Transport System

Event Handling

Comprehensive event system for monitoring connection lifecycle, data transmission, and error handling across all transport types.

interface SocketReservedEvents {
  open: () => void;
  handshake: (data: HandshakeData) => void;
  packet: (packet: Packet) => void;
  packetCreate: (packet: Packet) => void;
  data: (data: RawData) => void;
  message: (data: RawData) => void;
  drain: () => void;
  flush: () => void;
  heartbeat: () => void;
  ping: () => void;
  pong: () => void;
  error: (err: string | Error) => void;
  upgrading: (transport: Transport) => void;
  upgrade: (transport: Transport) => void;
  upgradeError: (err: Error) => void;
  close: (reason: string, description?: CloseDetails | Error) => void;
}

interface HandshakeData {
  sid: string;
  upgrades: string[];
  pingInterval: number;
  pingTimeout: number;
  maxPayload: number;
}

Event Handling

Utility Functions

Helper functions for URI parsing, timer management, and protocol utilities supporting both browser and Node.js environments.

function installTimerFunctions(obj: any, opts: any): void;
function parse(str: string): ParsedUri;
function nextTick(fn: Function): void;

const protocol: number;
const transports: {
  websocket: typeof WS;
  webtransport: typeof WT;
  polling: typeof XHR;
};

Utility Functions

Types

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

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

type TransportCtor = { new (o: any): Transport };

interface WriteOptions {
  compress?: boolean;
}

interface CloseDetails {
  description: string;
  context?: unknown;
}

interface Packet {
  type: PacketType;
  data?: RawData;
}

class TransportError extends Error {
  readonly type: "TransportError";
  readonly description: any;
  readonly context: any;
  constructor(reason: string, description: any, context: any);
}

interface ParsedUri {
  source: string;
  protocol: string;
  authority: string;
  userInfo: string;
  user: string;
  password: string;
  host: string;
  port: string;
  relative: string;
  path: string;
  directory: string;
  file: string;
  query: string;
  anchor: string;
  pathNames: string[];
  queryKey: Record<string, string>;
  ipv6uri?: boolean;
}