@bytesocket/server

Shared server logic for ByteSocket WebSocket server implementations. This package provides the abstract base classes, interfaces, and types that the transport‑specific adaptors (@bytesocket/node, @bytesocket/uws) extend to create a fully‑typed, real‑time server.

You do not need to install this package directly; it is a dependency of the main packages.

Features

• Transport‑agnostic server skeleton - ByteSocketServerBase handles message parsing, middleware execution, event routing, authentication, room join/leave, and lifecycle hooks. You only implement the transport‑specific parts.
• Type‑safe event system - Full TypeScript generics for emit/listen maps, room events, socket data, and middleware callbacks.
• Pluggable serialization - JSON (text) or MessagePack (binary) encoding, selectable per‑server instance or per‑message.
• Shared test utilities - Common test factories (/test-utils) let you run the exact same test suite against every adaptor.

Installation

npm install @bytesocket/server

This package is not meant to be used directly. Choose an adaptor that matches your WebSocket library:

• @bytesocket/node - for Node.js ws
• @bytesocket/uws - for uWebSockets.js

Exports

Main entry (@bytesocket/server)

• ByteSocketServerBase - abstract server class
• SocketServerBase - abstract per‑connection socket class
• IByteSocket / ISocket / ISocketRooms / IRoomsServer / ILifecycleServer - public API interfaces
• ByteSocketOptionsBase - configuration options shared by every adaptor
• ServerIncomingData / ServerOutgoingData - type aliases for raw WebSocket data
• Middleware, EventCallback, RoomEventMiddleware, AuthFunction, MiddlewareNext - callback types
• SocketData - the user data shape attached to every socket
• encode / decode - serialization helpers (MessagePack / JSON)

Test utilities (@bytesocket/server/test-utils)

Factory functions that create a server + test client for running integration tests across adaptors:

import { serverConnectionTest } from "@bytesocket/server/test-utils";

Available test suites:

• serverConnectionTest - connection open/close, origin checks, header getters
• serverHeartbeatTest - empty‑binary ping/pong, automatic keep‑alive
• serverAuthTest - authentication flow (success / failure / timeout)
• serverLifecycleTest - lifecycle hook ordering and errors
• serverMessagingTest - message send / receive, serialization
• serverRoomsSingleTest - single‑room join/leave/emit
• serverRoomsBulkTest - bulk room operations

Each factory function receives:

1. The Vitest instance (import * as vitest from 'vitest')
2. A createByteSocket function
3. A createByteSocketServer function
4. A destroyByteSocketServer function

See the adaptor packages for concrete examples.

API overview

ByteSocketServerBase

The abstract server class. Adaptors extend it and implement attach, publishRaw, and the upgrade lifecycle methods.

import { ByteSocketServerBase } from "@bytesocket/server";

class MyByteSocket extends ByteSocketServerBase<MyEvents> {
	attach(server: unknown, path: string): this {
		/* … */
	}
	// …
}

Key protected methods (call these from your adaptor):

• message(socket, data, isBinary) - process an incoming WebSocket message
• close(socket, code, reason) - handle a transport close event

Public API: emit, on, off, once, use (middleware), encode, decode, destroy.

SocketServerBase

Abstract socket instance. Adaptors subclass it to provide sendRaw, publishRaw, joinRoom, leaveRoom, and closeTransport.

Common options (ByteSocketOptionsBase)

| Option | Type | Default | Description | | ------------------------ | ------------------------------------- | ---------------------------- | -------------------------------------------------- | | debug | boolean | false | Enable debug logging | | serialization | "json" | "binary" | "binary" | Payload encoding format | | broadcastRoom | string | "__bytesocket_broadcast__" | Internal room used for global broadcasts | | authTimeout | number | 0 | Max milliseconds to wait for an auth response | | middlewareTimeout | number | 0 | Timeout for global middleware | | roomMiddlewareTimeout | number | 0 | Timeout for room middleware | | idleTimeout | number | 120000 | Milliseconds before an idle connection is closed | | sendPingsAutomatically | boolean | true | Send WebSocket pings to keep the connection alive | | origins | string[] | - | Allowed origin list (empty = all allowed) | | onMiddlewareError | "ignore" | "close" | function | "ignore" | Action when global middleware errors | | onMiddlewareTimeout | "ignore" | "close" | function | "ignore" | Action when global middleware times out | | msgpackrOptions | object | - | Options forwarded to the msgpackr Packr instance | | auth | AuthFunction | - | User‑supplied authentication handler |

Usage example (via an adaptor)

import { ByteSocket } from '@bytesocket/node';   // or '@bytesocket/uws'
import { SocketEvents } from '@bytesocket/core';

type MyEvents = SocketEvents<{
  "chat:message": { text: string };
  "user:joined": { userId: string };
}>;

const io = new ByteSocket<MyEvents>({ debug: true });

io.on('chat:message', (socket, data) => {
  console.log(\`${socket.id} says: ${data.text}\`);
});

io.emit('user:joined', { userId: 'server' });

// attach to an HTTP server or uWS app
io.attach(server, '/ws');

Adaptors

Transport‑specific implementations:

• @bytesocket/node - Node.js ws library
• @bytesocket/uws - uWebSockets.js

Both expose a concrete ByteSocket class that you instantiate directly.

Testing with shared utilities

// packages/node/tests/connection.test.ts
import * as vitest from "vitest";
import { serverConnectionTest } from "@bytesocket/server/test-utils";
import { createByteSocket, createByteSocketServer, destroyByteSocketServer } from "./factory";

describe("ByteSocket node: Connection", () => {
	serverConnectionTest(vitest, createByteSocket, createByteSocketServer, destroyByteSocketServer);
});

Your factory file provides the three functions that wrap your specific transport setup. The shared test suite handles the rest.

License

MIT © 2026 Ahmed Ouda

• GitHub: @a7med3ouda