Overview

The Sockets module brings real-time, event-driven communication to Hyper Fetch, enabling seamless data exchange over persistent connections. Designed for flexibility and type safety, it empowers you to build robust, scalable applications with minimal effort.

---

Why Sockets?

Modern applications often require real-time updates-think chat apps, live dashboards, or collaborative tools. Our sockets package provides a unified, typesafe API for working with connections like WebSockets, Server-Sent Events (SSE), while supporting custom adapters for libraries like Firebase Realtime Database.

Our approach

Sockets is built on the same principles as the core Hyper Fetch package: consistency, type safety, and developer experience. It extends these ideas to the world of real-time data.

---

Typesafe realtime

Handling realtime data exchange such as with WebSockets or Server-Sent Events (SSE) presents unique challenges, particularly around maintaining type safety as your application grows. The library addresses this by exposing dedicated Listener and Emitter classes, each with their own explicit types for responses and payloads.

This means that when you use a listener, such as chatMessageListener, you always know the exact type of data being handled. Similarly, when emitting data, you have clear expectations for the payload structure.

This approach is especially powerful in projects with multiple listeners and emitters, ensuring type safety and maintainability even as your application scales.

import { socketClient } from "./socket-client";

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

const chatMessageListener = socketClient.createListener<{ message: string }>({
  url: "chat-message",
});

chatMessageListener.listen({
  callback: ({ data }) => {
    console.log(data); // { message: string }
  },
});

---

Listener templates

Usual approach to sockets it to use the .on() method where you have to define the topic and the callback. Our approach is a bit different. Just like in the core-package we prefer to create reusable templates for the listeners. They keep the information about expected message data type and other. This way you can use the listener template in multiple places with full type-safety.

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

// 1. Initialize the socket
const socket = new Socket({
  url: "ws://localhost:3000",
});

// 2. Create the listener template
const chatMessageListener = socket.createListener<{ message: string }>({
  topic: "chat-message",
});

// 3. Listen to the chat message
chatMessageListener.listen({
  callback: ({ data }) => {
    console.log(data); // { message: string }
  },
});

---

Emitter templates

To incorporate full type-safety and readability we also have emitter templates. They are used to send messages to the realtime servers. This way we keep very clear data-exchange between the client and the server. It is reusable and very easy to use.

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

// 1. Initialize the socket
const socket = new Socket({
  url: "ws://localhost:3000",
});

// 2. Create the emitter template
const chatMessageEmitter = socket.createEmitter<{ text: string }>({
  topic: "new-message",
});

// 3. Send the chat message
chatMessageEmitter.emit({
  data: { text: "Hello, world!" },
});

---

Event-Driven and Extensible

Sockets exposes all events, making it easy to build custom devtools, analytics, or advanced integrations. The event-driven approach ensures your app can react to every stage of the connection lifecycle.

---

See More

Socket Class

Learn more about the Socket class and its configuration options.

Listeners

How to receive and handle real-time events.

Emitters

How to send events and handle acknowledgements.

Adapters

Customize or extend socket communication with adapters.

---

With these building blocks, you're ready to build powerful, real-time features with Hyper Fetch Sockets! 🎊