Connection

This guide provides a comprehensive overview of how to manage socket connections using Hyper-fetch. You'll learn how to control connection states, handle automatic and manual connections, and configure retry policies to build robust real-time applications.

What you'll learn

1. How to enable or disable automatic connections.
2. How to manually connect and disconnect from the socket.
3. How to implement manual reconnection logic.
4. How to monitor the connection status using callbacks.
5. How to configure connection retries and handle reconnection failures.

---

Autoconnect

By default, Hyper-fetch attempts to connect to the socket server as soon as the Socket instance is created. This behavior is controlled by the autoConnect option, which is set to true by default.

You can disable autoconnect by setting autoConnect: false in the adapter options. This is useful when you want to delay the connection until a user performs a specific action, such as logging in or navigating to a certain page.

import { Socket } from "@hyper-fetch/sockets";

const socket = new Socket({
  url: "ws://localhost:8080",
  adapterOptions: { autoConnect: false },
});

When autoConnect is disabled, you'll need to manually initiate the connection.

---

Manual Connect

When autoConnect is disabled, you can manually establish a connection using the socket.connect() method. This gives you precise control over when the connection is initiated.

function Component() {
  const [socket] = React.useState(() => {
    return new Socket({
      url: "ws://localhost:8080",
      adapterOptions: { autoConnect: false },
    });
  });

  return (
    <div>
      <button onClick={() => socket.connect()}>Connect</button>
    </div>
  );
}

The connect method is asynchronous and returns a promise that resolves once the connection is established.

---

Disconnect

You can manually close a socket connection using the socket.disconnect() method. This is useful for logging out a user, leaving a specific feature area, or performing cleanup.

function Component() {
  const [socket] = React.useState(() => {
    return new Socket({
      url: "ws://localhost:8080",
    });
  });

  return (
    <div>
      <button onClick={() => socket.disconnect()}>Disconnect</button>
    </div>
  );
}

Like connect, the disconnect method is asynchronous and returns a promise that resolves once the connection is fully closed.

---

Reconnect

Hyper-fetch provides a socket.reconnect() method to manually trigger a reconnection attempt. This can be useful in scenarios where you want to give users a way to re-establish a connection without a full page reload, such as when a connection is lost due to a temporary network issue.

function Component() {
  const [socket] = React.useState(() => {
    return new Socket({
      url: "ws://localhost:8080",
    });
  });

  return (
    <div>
      <button onClick={() => socket.reconnect()}>Reconnect</button>
    </div>
  );
}

The reconnect method will attempt to connect again, respecting the retry policies configured on the socket instance.

---

Connection Status

To monitor the socket's connection status, you can use the onConnected and onDisconnected callbacks. These allow you to react to changes in the connection state and update your UI accordingly.

• onConnected: Triggered when the socket successfully connects.
• onDisconnected: Triggered when the socket connection is closed, either manually or due to a network issue.

Here's how you can use these callbacks to track the connection status:

function Component() {
  const [isConnected, setConnected] = React.useState(false);

  const [socket] = React.useState(() => {
    const instance = new Socket({
      url: "ws://localhost:8080",
    });

    instance.onConnected(() => {
      setConnected(true);
      console.log("Socket connected");
    });

    instance.onDisconnected(() => {
      setConnected(false);
      console.log("Socket disconnected");
    });

    return instance;
  });

  return (
    <div>
      <p>Status: {isConnected ? "Connected" : "Disconnected"}</p>
    </div>
  );
}

For React applications, consider using the useSocketState hook from @hyper-fetch/react for a more declarative way to handle connection states.

---

Retries

Hyper-fetch automatically handles reconnection attempts when a connection is lost. You can customize the retry behavior using the reconnect and reconnectTime options in the Socket constructor.

• reconnect: The maximum number of reconnection attempts. Set to Infinity by default for endless retries.
• reconnectTime: The time in milliseconds between each retry attempt. Defaults to 5000 (5 seconds).

Customizing Retry Logic

Here's how you can configure a custom retry policy. In this example, the socket will attempt to reconnect up to 5 times, with a 3-second delay between each attempt.

import { Socket } from "@hyper-fetch/sockets";

const socket = new Socket({
  url: "ws://localhost:8080",
  reconnect: 5,
  reconnectTime: 3000,
});

Handling Reconnection Events

You can also hook into the reconnection lifecycle with onReconnect and onReconnectFailed callbacks:

• onReconnect: Triggered at the start of each reconnection attempt.
• onReconnectFailed: Triggered when all reconnection attempts have failed.

function Component() {
  const [socket] = React.useState(() => {
    const instance = new Socket({
      url: "ws://localhost:8080",
      reconnect: 3,
      reconnectTime: 2000,
    });

    instance.onReconnect(() => {
      console.log("Reconnection attempt started");
    });

    instance.onReconnectFailed(() => {
      console.error("All reconnection attempts failed.");
    });

    return instance;
  });

  return <div>Check the console for reconnection events.</div>;
}

---

Congratulations!

You now know how to manage socket connections in Hyper-fetch.

• You can control automatic and manual connections.
• You can disconnect and reconnect from the server on demand.
• You can monitor the connection lifecycle with callbacks.
• You can create robust retry strategies for network resilience.