@ezez/ws-server - v0.5.1
    Preparing search index...

    Class EZEZWebsocketServer<IncomingEvents, OutgoingEvents, TContext>

    WebSocket server with built-in authentication, type-safe events, and reply tracking.

    Wraps the native ws WebSocketServer and provides:

    • Type-safe event-based messaging via TypeScript generics
    • Built-in authentication flow with configurable timeout
    • Message queuing for pre-auth messages
    • Reply tracking with automatic cleanup
    • Broadcasting to all connected clients

    Supports three operational modes:

    • Standalone - creates its own HTTP server (pass port in options)
    • External server - attaches to an existing HTTP server (pass server in options)
    • Manual upgrade - no automatic attachment, you handle upgrades yourself (pass noServer: true)
    type FromClient = {
        ping: [message: string];
        getData: [id: number];
    };

    type FromServer = {
        pong: [message: string];
        data: [id: number, payload: string];
    };

    const server = new EZEZWebsocketServer<FromClient, FromServer>(
        { port: 8080 },
        {
            onAuthRequest: async (client, authKey) => authKey === "secret",
            onAuthOk: (client) => {
                client.send("pong", ["connected!"]);
            },
        },
    );

    await server.start();

    Type Parameters

    • IncomingEvents extends TEvents

      Map of event names to argument tuples that clients can send to this server

    • OutgoingEvents extends TEvents = IncomingEvents

      Map of event names to argument tuples that this server can send to clients. Defaults to IncomingEvents if not specified (bidirectional events).

    • TContext extends object = Record<string, never>

      Shape of the per-client mutable context bag accessible via client.context. Defaults to Record<string, never> (no context) if not specified. When set, you must provide a defaultContext option that will be structuredCloned into each new client.

    Index

    Constructors

    constructor

    Accessors

    clients wss

    Methods

    broadcast close start

    Constructors

    • Creates a new WebSocket server instance.

      The server is not started until start is called.

      Type Parameters

      • IncomingEvents extends TEvents

        Map of event names to argument tuples that clients can send to this server

      • OutgoingEvents extends TEvents = IncomingEvents

        Map of event names to argument tuples that this server can send to clients. Defaults to IncomingEvents if not specified (bidirectional events).

      • TContext extends object = Record<string, never>

        Shape of the per-client mutable context bag accessible via client.context. Defaults to Record<string, never> (no context) if not specified. When set, you must provide a defaultContext option that will be structuredCloned into each new client.

      Parameters

      • options: Options<TContext>

        Server and client behavior configuration. Must include one of: port (standalone), server (external server), or noServer: true (manual upgrade handling).

      • callbacks: Callbacks<IncomingEvents, OutgoingEvents, TContext>

        Lifecycle callbacks for authentication, messages, disconnections, and errors.

      Returns EZEZWebsocketServer<IncomingEvents, OutgoingEvents, TContext>

      Error if clearAwaitingRepliesAfterMs is set to 0 or less.

    Accessors

    • get wss(): WebSocketServer | null

      Gets the underlying ws WebSocketServer instance, or null if the server is not started or has been closed.

      Returns WebSocketServer | null

      Sending messages directly through this instance will bypass the library's serialization protocol and will likely cause parsing errors on connected clients.

    Methods

    • Sends a message to all currently connected and authenticated clients.

      Type Parameters

      • T extends string | number | symbol

      Parameters

      • eventName: T

        The event name to broadcast.

      • args: OutgoingEvents[T]

        The arguments to send with the event.

      Returns void

    • Stops the server, closes all client connections, and clears the client list.

      After calling this method, the server can no longer accept connections. The wss getter will return null.

      Returns void

    • Starts the server and begins listening for connections.

      • In standalone mode (with port), the promise resolves once the server is listening.
      • In external server or noServer mode, the promise resolves immediately after setup.

      Returns Promise<void>

      A promise that resolves when the server is ready to accept connections.

      Error if the server fails to start (e.g., port is already in use).

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods