tessl/npm-engine-io

The realtime engine behind Socket.IO providing bidirectional connection foundation between client and server

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Engine.IO

Name: tessl/npm-engine-io
Author: tessl

Engine.IO is a transport-based cross-browser/cross-device bidirectional communication layer that serves as the foundation for Socket.IO. It provides maximum reliability by establishing a long-polling connection first, then upgrading to better transports like WebSocket when available, handling connection management, transport switching, message queuing, and protocol negotiation.

Package Information

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

Core Imports

import { Server, Socket, listen, attach, uServer, Transport, parser, protocol } from "engine.io";

For CommonJS:

const { Server, Socket, listen, attach, uServer, Transport, parser, protocol } = require("engine.io");

Basic Usage

Creating a Standalone Server

import { listen } from "engine.io";

// Create server listening on port 3000
const server = listen(3000);

server.on('connection', (socket) => {
  console.log('Client connected:', socket.id);
  
  // Send messages
  socket.send('Hello client!');
  socket.send(Buffer.from([0, 1, 2, 3])); // binary data
  
  // Handle messages
  socket.on('message', (data) => {
    console.log('Received:', data);
  });
  
  socket.on('close', () => {
    console.log('Client disconnected:', socket.id);
  });
});

Attaching to Existing HTTP Server

import { createServer } from "http";
import { attach } from "engine.io";

const httpServer = createServer().listen(3000);
const server = attach(httpServer);

server.on('connection', (socket) => {
  socket.on('message', (data) => {
    socket.send(`Echo: ${data}`);
  });
});

Manual Server Setup

import { Server } from "engine.io";
import { createServer } from "http";

const server = new Server({
  pingTimeout: 20000,
  pingInterval: 25000,
  transports: ['polling', 'websocket']
});

const httpServer = createServer();
server.attach(httpServer, { path: '/engine.io' });

httpServer.listen(3000);

Architecture

Engine.IO is built around several key components:

Server Management: Core Server class that manages client connections and handles HTTP/WebSocket upgrades
Client Connections: Each client connection is represented by a Socket instance with bidirectional communication
Transport Layer: Pluggable transport system supporting polling (XHR/JSONP) and WebSocket protocols
Protocol Management: Automatic transport negotiation and upgrade handling for optimal connectivity
Message Processing: Binary and text message support with automatic encoding/decoding

Capabilities

Server Management

Core server functionality for creating and managing realtime connections with automatic transport negotiation and client lifecycle management.

function listen(port: number, options?: ServerOptions, callback?: () => void): Server;
function attach(server: HttpServer, options?: AttachOptions & ServerOptions): Server;

class Server extends BaseServer {
  constructor(opts?: ServerOptions);
  attach(server: HttpServer, options?: AttachOptions): void;
  handleRequest(req: IncomingMessage, res: ServerResponse): void;
  handleUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): void;
  close(): void;
}

Server Management

Client Socket Connections

Individual client connection management with bidirectional message passing, transport upgrades, and connection state tracking.

class Socket extends EventEmitter {
  readonly id: string;
  readonly protocol: number;
  readonly readyState: ReadyState;
  readonly transport: Transport;
  readonly request: IncomingMessage;
  readonly remoteAddress: string;
  
  send(data: string | Buffer, options?: SendOptions, callback?: () => void): void;
  close(discard?: boolean): void;
}

Socket Connections

Transport System

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

abstract class Transport extends EventEmitter {
  readonly name: string;
  readonly sid: string;
  readonly protocol: number;
  writable: boolean;
  
  abstract send(packets: Packet[]): void;
  close(fn?: () => void): void;
}

interface TransportRegistry {
  polling: typeof Polling;
  websocket: typeof WebSocket;
  webtransport: typeof WebTransport;
}

Transport System

Configuration Types

Core Configuration Interfaces

Primary interfaces for configuring server behavior, connection handling, and transport options.

interface ServerOptions {
  pingTimeout?: number;
  pingInterval?: number;
  upgradeTimeout?: number;
  maxHttpBufferSize?: number;
  transports?: ("polling" | "websocket" | "webtransport")[];
  allowUpgrades?: boolean;
  cors?: CorsOptions;
  cookie?: CookieSerializeOptions & { name: string } | boolean;
}

interface AttachOptions {
  path?: string;
  destroyUpgrade?: boolean;
  destroyUpgradeTimeout?: number;
  addTrailingSlash?: boolean;
}

Configuration Types

Protocol & Constants

// Protocol version
const protocol: number;

// Protocol parser
const parser: {
  protocol: number;
  packets: Record<string, number>;
  encodePacket(packet: Packet): string | Buffer;
  decodePacket(data: string | Buffer): Packet;
};

Error Handling

Engine.IO emits various events for error handling:

Server errors: connection_error events with error details
Socket errors: error events on individual socket instances
Transport errors: Automatic fallback to alternative transports
Connection timeouts: Configurable via pingTimeout and pingInterval

Install with Tessl CLI

npx tessl i tessl/npm-engine-io

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/engine.io@6.6.x
Publish Source: CLI
Badge