Socket

Read the API Reference »

Socket is the central class for configuring your server connection in the Hyper Fetch sockets module. It initializes all core subsystems—such as offline, events, and interceptors—and provides a unified way to create and manage listeners and emitters based on its configuration. By keeping all data and logic encapsulated within a single socket instance, you ensure that each socket remains isolated and independent from others.

---

Purpose

1. Orchestrates the components and flow of the sockets library
2. Creates listeners and emitters to provide global setup and environment
3. Isolates sockets from each other and their events

---

Initialization

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

export const socket = new Socket({ url: "ws://localhost:3000" });

---

Features

Here are the main features of the Socket class.

Adapters

You can pick between two built-in modes for the data exchange:

1. WebSocket mode (default)
2. Server Sent Events (SSE) mode

You can change it with the SSE adapter:

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

new Socket({ url: "ws://localhost:3000" }).setAdapter(sseAdapter);

---

Interceptors

There are a few methods for intercepting a response from a request:

• onSend — triggered before sending an event.

new Socket({ url: "ws://localhost:3000" }).onSend((event) => {
  // Modify the event before it is sent
  event.payload = { ...event.payload, token: "1234567890" };
  return event;
});

• onError — triggered on error from socket.

new Socket({ url: "ws://localhost:3000" }).onError((error) => {
  // Modify the error before it is emitted to other sub-systems
  error.message = "An error occurred";
  return error;
});

• onMessage — triggered on any received message.

new Socket({ url: "ws://localhost:3000" }).onMessage((message) => {
  // Modify the message before it is emitted to other sub-systems
  message.data = { ...message.data, token: "1234567890" };
  return message;
});

You can modify received data or payload with these interceptors before it is emitted to other sub-systems.

---

Query Params

Sockets has a built-in query params encoding function; you can modify its options or provide your own function. Use the queryParamsConfig method and the options listed below.

QueryStringifyOptionsType

Name	Type	Description
arrayFormat	bracket | index | comma | separator | bracket-separator | none	Array encoding type
arraySeparator	string	Array format separator
encode	boolean	Encode keys and values
skipEmptyString	boolean	Skip keys with empty string
skipNull	boolean	Skip keys with null values
strict	boolean	Strict URI encoding
dateParser	(value: QueryParamType) => string	Parsing function for date type query param
objectParser	(value: QueryParamType) => string	Parsing function for object type query param

To change the encoding function, use the queryParamsStringify method:

export const socket = new Socket({
  url: "ws://localhost:3000",
  queryParams: { param1: [1, 2, 3], param2: "test" },
  queryParamsStringify: (value: string) => encode(value),
});

---

Authentication

To exchange authenticated events, set up the queryParams parameter with authentication parameter.

export const socket = new Socket({
  url: "ws://localhost:3000",
  queryParams: { authToken: "1234567890" },
});

Authentication guide

Learn how to set up authentication for your sockets.

---

TypeScript

Sockets has one generic type responsible for the type of the current Socket Adapter. It defaults to the built-in adapter type and will automatically change to any new adapter type you pass to the Socket class.

---