Automatic Reconnection

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

The autoReconnect function creates an instance of the AutoReconnect class, enabling the use of 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. This parameter is optional; default settings will be used if omitted.

backoffLimit?: number

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

initialDelay?: number

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

maxDelay?: number

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

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

Specifies the conditions under which a reconnection should be attempted. 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, obtain status information, 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.
• "running" … Reconnecting.
• "success" … Reconnection successful.
• "failure" … Reconnection failed.

.phase:

• "waiting" … Initial state. No reconnection attempts have been made.
• "pending" … A reconnection has been requested, and a certain waiting period is in place before execution.
• "closing" … Disconnecting.
• "connecting" … Connecting. Attempts to connect even if disconnection fails.
• "succeeded" … Reconnection successful.
• "failed" … Reconnection failed.

state	phase
"waiting"	"waiting"|"pending"
"running"	"closing"|"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 indicates that 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(`Successfully reconnected to ${endpoint} 🎉`);
});

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

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

  // Various processes that run for a long time

} finally {
  await db.close();
}

Notes

• The reconnection logic is crucial for properly adjusting the stability of the WebSocket connection and the frequency of connection recovery. Option settings should be adjusted according to system requirements and use cases.
• autoReconnect attempts to recover from lost connections, but complete recovery is not guaranteed in all cases.