Auto-Reconnection

This feature provides automatic reconnection attempts for connection drops that occur in real-time communication such as WebSockets. It performs reconnections based on a specific logic and emits success/failure events.

The autoReconnect function creates an instance of the AutoReconnect class, enabling the reconnection functionality.

Import

import { autoReconnect } from "@tai-kun/surrealdb";

Syntax

function autoReconnect(
  db: Client,
  options?: AutoReconnectOptions
): AutoReconnect;

Arguments

db

An instance object of the Surreal class.

options

Options to specify reconnection settings. You can specify the reconnection interval, maximum delay time, reconnection conditions, etc. Omit this if you want to use the default settings.

backoffLimit?: number

Specifies the maximum number of reconnection attempts. The default value is Infinity.

initialDelay?: number

The delay time (in milliseconds) before the first reconnection attempt. The default value is 500.

maxDelay?: number

The maximum value of the reconnection delay time (in milliseconds). The delay increases as the backoff progresses, but this value is the upper limit. The default value is 30_000 (30 seconds).

shouldReconnect?: { ping?: { threshold: number; perMillis: number }} | (error) => boolean

Specifies the conditions for reconnection. If specified as a function, it determines whether to perform a reconnection based on the arguments of the error event.

Return Value

Returns an instance of the AutoReconnect class. This instance can be used to control reconnections, retrieve status, and monitor events.

.getReconnectionInfo(): ReconnectionInfo

Retrieves the current reconnection information (.state and .phase). Each has the following meaning:

.state:

• "waiting" … Initial state. No reconnection attempts have been made yet.
• "running" … Reconnecting.
• "success" … Reconnection succeeded.
• "failure" … Reconnection failed.

.phase:

• "waiting" … Initial state. No reconnection attempts have been made yet.
• "pending" … A reconnection has been requested, and it’s waiting for a certain time before execution.
• "disconnecting" … Disconnecting.
• "connecting" … Connecting. Attempts to connect even if disconnection fails.
• "succeeded" … Reconnection succeeded.
• "failed" … Reconnection failed.

state	phase
"waiting"	"waiting"|"pending"
"running"	"disconnecting"|"connecting"
"success"	"pending"|"succeeded"
"failure"	"pending"|"failed"

.enable(): void

Enables the reconnection functionality. Calling this method enables reconnections. Enabled by default.

.disable(): void

Disables the reconnection functionality. Calling this method disables reconnections.

.reset(): void

Resets the reconnection counter. This initializes the reconnection backoff logic.

.enabled: boolean

A boolean value indicating whether the reconnection functionality is enabled. true if reconnection is enabled.

Example

import { autoReconnect, Surreal } from "@tai-kun/surrealdb";

const db = new Surreal();
const ar = autoReconnect(db, {
  initialDelay: 1000,
  maxDelay: 30000,
  backoffLimit: 5,
  shouldReconnect: {
    ping: {
      perMillis: 60000, // Within 1 minute,
      threshold: 3,     // Reconnect if the ping fails 3 or more times.
    },
  },
});

ar.on("pending", (endpoint, duration) => {
  console.log(`Reconnecting to ${endpoint} in ${duration / 1000} seconds...`);
});

ar.on("success", (endpoint) => {
  console.log(`Reconnection to ${endpoint} succeeded 🎉`);
});

ar.on("failure", (endpoint, cause) => {
  console.error(`Reconnection to ${endpoint} failed 🤯`);
  console.error("Cause:", cause);
});

try {
  await db.connect("ws://127.0.0.1:8000");

  // Various processes executed over a long period of time

} finally {
  await db.disconnect();
}

Note

• The reconnection logic is crucial for appropriately adjusting the stability of the WebSocket connection and the frequency of connection recovery. Option settings need to be adjusted according to system requirements and use cases.
• autoReconnect attempts to recover from connection loss, but it does not guarantee complete recovery in all cases.