withWebSocketHeartbeat (@defjs/core)

@defjs/core · Function

Signature

function withWebSocketHeartbeat(
  options: ClientWebSocketOptions["heartbeat"],
): ClientOption;

Passing undefined clears an earlier setting. The option type is:

{
  intervalMs: number
  isAck?: (message: unknown) => boolean
  message?: <T = unknown>() => T | unknown
  timeoutMs?: number
}

Every intervalMs, message() is called and its result is sent through the endpoint's outgoing struct. No message is sent when message is omitted or returns undefined.
With timeoutMs, an acknowledgement is expected after each heartbeat. isAck receives the decoded incoming message; when it returns true, the timer is cleared and that message is not delivered to receive.
If no ack arrives within timeoutMs, or a heartbeat cannot be sent, the session fails. This does not trigger a reconnect.
Heartbeat uses the same JSON guard as session.send: a value JSON cannot represent after struct encoding causes TypeError and ends the logical session.
intervalMs and timeoutMs must be positive, finite, and at most 2_147_483_647; otherwise the operation fails with REQ_OPTIONS_INVALID.
A heartbeat in the request options replaces this one for that call.

Prop

Type

options ClientWebSocketOptions["heartbeat"]

Heartbeat interval, payload, timeout, and ACK predicate.

An option that sets config.webSocket.heartbeat.