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

    Interface EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>

    Represents an individual client connected to the WebSocket server.

    Each instance manages:

    • Per-client authentication state and timeout
    • Type-safe event listeners via on, off, and once
    • Message sending with optional reply tracking via send
    • Automatic cleanup of stale reply listeners

    Instances are created automatically by EZEZWebsocketServer when a client connects and are passed to your callbacks (e.g., onAuthRequest, onAuthOk, onMessage).

    interface EZEZServerClient<
        IncomingEvents extends TEvents,
        OutgoingEvents extends TEvents = IncomingEvents,
        TContext extends object = Record<string, never>,
    > {
        context: TContext;
        off: <
            T extends
                | string
                | number
                | symbol
                | string & EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >
                | symbol & EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >,
        >(
            event: T,
            fn?: EventListener<
                EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >,
                T,
            >,
            context?: any,
            once?: boolean,
        ) => this;
        on: <
            T extends
                | string
                | number
                | symbol
                | string & EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >
                | symbol & EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >,
        >(
            event: T,
            fn: EventListener<
                EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >,
                T,
            >,
            context?: any,
        ) => this;
        once: <
            T extends
                | string
                | number
                | symbol
                | string & EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >
                | symbol & EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >,
        >(
            event: T,
            fn: EventListener<
                EventsToEventEmitter<
                    IncomingEvents,
                    EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                >,
                T,
            >,
            context?: any,
        ) => this;
        send: <TEvent extends string | number | symbol>(
            eventName: TEvent,
            args: OutgoingEvents[TEvent],
            onReply?: <
                REvent extends
                    [
                        client: EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                        eventName: keyof IncomingEvents,
                        args: IncomingEvents[keyof IncomingEvents],
                        reply: <TEvent extends keyof OutgoingEvents>(eventName: TEvent, args: OutgoingEvents[TEvent], onReply?: (<REvent extends ReplyTupleUnion<IncomingEvents, EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>>>(...replyArgs: REvent) => void) | undefined) => Ids | undefined,
                        ids: Ids,
                    ],
            >(
                ...replyArgs: REvent,
            ) => void,
        ) => Ids | undefined;
        get alive(): boolean;
        get awaitingRepliesCount(): number;
        get client(): WebSocket;
        get connectionId(): number;
        disconnect(code?: number, reason?: string): void;
    }

    Type Parameters

    • IncomingEvents extends TEvents

      Map of event names to argument tuples that this client can send to the server.

    • OutgoingEvents extends TEvents = IncomingEvents

      Map of event names to argument tuples that the server can send to this client. Defaults to IncomingEvents if not specified.

    • TContext extends object = Record<string, never>

      Shape of the per-client mutable context bag accessible via context. Defaults to Record<string, never> (no context) if not specified.

    Index

    Properties

    context off on once send

    Accessors

    alive awaitingRepliesCount client connectionId

    Methods

    disconnect

    Properties

    context: TContext

    Per-client mutable context bag. Read and write freely to attach state to a specific client connection (e.g., authenticated user info, subscriptions, room memberships).

    Initialized from the server's defaultContext option via structuredClone, so each client starts with an independent copy. Shape is typed via the TContext generic on EZEZWebsocketServer.

    off: <
        T extends
            | string
            | number
            | symbol
            | string & EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >
            | symbol & EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >,
    >(
        event: T,
        fn?: EventListener<
            EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >,
            T,
        >,
        context?: any,
        once?: boolean,
    ) => this

    Unregisters an event listener for given event.

    on: <
        T extends
            | string
            | number
            | symbol
            | string & EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >
            | symbol & EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >,
    >(
        event: T,
        fn: EventListener<
            EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >,
            T,
        >,
        context?: any,
    ) => this

    Registers an event listener for given event. Please note that if a message is a reply and onReply function was given, then this listener will not be called.

    Type Declaration

    once: <
        T extends
            | string
            | number
            | symbol
            | string & EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >
            | symbol & EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >,
    >(
        event: T,
        fn: EventListener<
            EventsToEventEmitter<
                IncomingEvents,
                EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
            >,
            T,
        >,
        context?: any,
    ) => this

    Registers an event listener for given event, which will be called only once. Please note that if a message is a reply and onReply function was given, then this listener will not be called.

    Type Declaration

    send: <TEvent extends string | number | symbol>(
        eventName: TEvent,
        args: OutgoingEvents[TEvent],
        onReply?: <
            REvent extends
                [
                    client: EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                    eventName: keyof IncomingEvents,
                    args: IncomingEvents[keyof IncomingEvents],
                    reply: <TEvent extends keyof OutgoingEvents>(eventName: TEvent, args: OutgoingEvents[TEvent], onReply?: (<REvent extends ReplyTupleUnion<IncomingEvents, EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>>>(...replyArgs: REvent) => void) | undefined) => Ids | undefined,
                    ids: Ids,
                ],
        >(
            ...replyArgs: REvent,
        ) => void,
    ) => Ids | undefined

    Sends a message to the client.

    If the client is disconnected, behavior depends on the sendAfterDisconnect option:

    • "ignore" (default): silently returns undefined
    • "throw": throws an error

    Type Declaration

      • <TEvent extends string | number | symbol>(
            eventName: TEvent,
            args: OutgoingEvents[TEvent],
            onReply?: <
                REvent extends
                    [
                        client: EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                        eventName: keyof IncomingEvents,
                        args: IncomingEvents[keyof IncomingEvents],
                        reply: <TEvent extends keyof OutgoingEvents>(eventName: TEvent, args: OutgoingEvents[TEvent], onReply?: (<REvent extends ReplyTupleUnion<IncomingEvents, EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>>>(...replyArgs: REvent) => void) | undefined) => Ids | undefined,
                        ids: Ids,
                    ],
            >(
                ...replyArgs: REvent,
            ) => void,
        ): Ids | undefined

      • Type Parameters

        • TEvent extends string | number | symbol

        Parameters

        • eventName: TEvent

          The name of the event to send.

        • args: OutgoingEvents[TEvent]

          The arguments to send with the event.

        • OptionalonReply: <
              REvent extends
                  [
                      client: EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>,
                      eventName: keyof IncomingEvents,
                      args: IncomingEvents[keyof IncomingEvents],
                      reply: <TEvent extends keyof OutgoingEvents>(eventName: TEvent, args: OutgoingEvents[TEvent], onReply?: (<REvent extends ReplyTupleUnion<IncomingEvents, EZEZServerClient<IncomingEvents, OutgoingEvents, TContext>>>(...replyArgs: REvent) => void) | undefined) => Ids | undefined,
                      ids: Ids,
                  ],
          >(
              ...replyArgs: REvent,
          ) => void

          Optional callback invoked when the client replies to this specific message. When a reply arrives and this callback is registered, the reply bypasses any per-event on() listeners.

        Returns Ids | undefined

        The message Ids (containing eventId and replyTo), or undefined if the message was not sent.

    Accessors

    • get alive(): boolean

      Whether the client's WebSocket connection is currently open and ready to send/receive messages.

      Returns boolean

    • get awaitingRepliesCount(): number

      Gets the count of messages that are waiting for a reply.

      Returns number

    • get client(): WebSocket

      The underlying ws WebSocket instance for this connection.

      Returns WebSocket

      Sending messages directly through this instance will bypass the library's serialization protocol and will likely cause parsing errors on the receiving end. Use send instead.

    • get connectionId(): number

      Unique numeric identifier for this connection, auto-incremented starting from 0 across the lifetime of the server process.

      Useful for logging or tracking individual clients. Note that this counter is global and does not reset when the server restarts within the same process.

      Returns number

    Methods

    • Disconnects the client from the server.

      Parameters

      • Optionalcode: number

        Optional close code (default: 1000 - normal closure)

      • Optionalreason: string

        Optional close reason string

      Returns void

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods