Events

Events allow for the exchange of values between the client and the server through a WebSocket connection.

Event-related errors are communicated through the event life cycle error.

Address

The name used by the issuer must match the name registered by the receiver.

The names distinguish capital and lower capital. message and Message represent different events.

On() and on()

On() and on() they register handlers to receive events.

Server

Firma:func (*Socket) On(event string, handler any)

The server uses On() to receive events issued by the client:

socket.On("message", func(message string) {
    log.Println(message)
})

event contains the name of the event and handler must be a function without return.

The handler can declare zero or more parameters. Its quantity, order and types must match the values sent by emit().

Handlers can't be different.

Client

Firma:on(event: string, handler: (...values: unknown[]) => void): Socket

The client uses on() to receive events issued by the server:

socket.on("message", message => {
    console.log(message)
})

The handler parameters receive the values in the same order in which they were issued by Emit().

on() returns the current instance of Socket, so you can chain up with other methods.

On both sides there can only be one handler by name. Recording the same event replaces the previous handler.

The handlers registered by on() are independent of the life-cycle events recorded by when().

See Values to know the type correspondence between Go and JavaScript.

Emit() and emit()

Emit() and emit() They send events across the connection.

Server

Firma:func (*Socket) Emit(event string, values ...any)

The server uses Emit() to send an event to the client:

socket.Emit("message", "Hola, George")

event contains the name of the event and values contains the values that the handler will receive by on().

The event can be broadcast without values. When it contains several, they are delivered in the same order in which they were sent.

Emit() He doesn't return a mistake.

Client

Firma:emit(event: string, ...values: unknown[]): Promise<unknown>

The client uses emit() to send an event to the server:

socket.emit("message", "Hola, George")

event contains the name of the event and values contains the values that the handler will receive by On().

The amount, order and types of the values must match the parameters of the Go handler.

The event can be broadcast without values.

On both sides, emissions made before the connection is established remain in the queue and are sent when the transport is available.

HTML controls and forms can also be sent as arguments. Values to know their conversion and the rates admitted.

Full example

The client emits ping and the server responds by pong.

Servidor:

module websocket

import "github.com/gox-lang/gox"

func Index(socket *gox.Socket) gox.WebSocket {
    socket.On("ping", func(message string) {
        socket.Emit("pong", message)
    })
}

Cliente:

import { Socket } from "@gox/websocket"

const socket = new Socket()

socket.on("pong", message => {
    console.log(message)
})

socket.emit("ping", "Hola, George")

The value issued by the client is delivered to the parameter message of On("ping"). The server returns it by Emit("pong") and the client receives it by on("pong").

Best practices

• It uses names of short and descriptive events.
• Keep the same name convention on the client and server.
• Declares specific types on the Go handlers.
• Send only the necessary values.
• It protects the state shared by several handlers.
• It uses requests when the issuer needs to receive an associated response.

To learn more about Lifecycle, check your documentation.

See also

• Lifecycle
• Values