@bytesocket/server

@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:

• The Vitest instance (import * as vitest from 'vitest')
• A createByteSocket function
• A createByteSocketServer function
• 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