Emitter

Read the API Reference »

The Emitter class is a core component of Hyper Fetch's real-time communication layer, built on top of WebSockets. It provides a structured, type-safe way to define, configure, and send events to a server. By encapsulating all the details for an event—such as its topic and data payload—Emitter ensures consistency and predictability in your real-time data interactions.

---

Purpose

• Define reusable event templates to create standardized event structures.
• Enforce a consistent data schema for all events.
• Reliably send events to your WebSocket server.

---

Initialization

Emitter should be initialized from the Socket instance with createEmitter method. This passes a shared reference to the place that manages communication in the application.

Example of Emitter initialization

import { socket } from "./socket";

export const sendChatMessage = socket.createEmitter<MessageType>()({
  topic: "new-message", // topic of the event
});

export const sendUserStatus = socket.createEmitter<UserStatusType>()({
  topic: "user-status", // topic of the event
});

---

Emitting Events

You can trigger an event with the emit method, which sends data to the server.

Sending Data

Use the setPayload method to assign data to be sent to the server.

sendChatMessage.setPayload({ message: "message" });

Emitting

Use the emit method to start the event emitting.

sendChatMessage.emit({ payload: { message: "message" } });

// or

sendChatMessage.setPayload({ message: "message" }).emit();

Emitting Events

Learn the basics of emitting events to your server.

---

Methods

Using methods on a emitter is different from other classes in Hyper Fetch. This is to ensure isolation between different uses, which allows you to avoid overwriting previously-prepared emitters and to dynamically generate keys for queues or the cache.

danger

Using any method on emitter returns its clone! We do not return a reference!

// ❌ WRONG

const emitter = sendMessageEmitter;

emitter.setPayload({ message: "some message" }); // Returns CLONED emitter with assigned data

emitter.emit(); // Server error - no data

// ✅ Good

const emitter = sendMessageEmitter;

const emitterWithData = emitter.setPayload({ message: "some message" }); // Returns CLONED emitter with assigned data

emitterWithData.emit(); // Success

Methods

Name	Description
setPayloadMapper(payloadMapper)
setPayload(payload)
setParams(params)
setOptions(options)
clone(config)
emit

Detailed Emitter API Methods

Explore all available methods, their parameters, and return values for the Emitter class.

---

Parameters

Configuration options for the emitter. The options field accepts adapter-specific options that depend on the adapter being used.

const emitter = socket.createEmitter<MessageType>()({
  topic: "chat-message",
});

EmitterOptionsType

Name	Type	Description
options	ExtractAdapterEmitterOptionsType<AdapterType>
topic	Topic

---

TypeScript

When creating an emitter with socket.createEmitter, you can specify a generic type to ensure type safety. PayloadType is the expected type of the data payload sent with the event.

import { socket } from "./socket";

const sendChatMessage = socket.createEmitter<{ message: string; author: string }>()({
  topic: "chat-message",
});

sendChatMessage.emit({
  payload: { message: "Hello!", author: "Me" },
});

---

Payload Mapper

You can use setPayloadMapper to transform the payload before it is sent. This is useful when you need to serialize or reshape data before transmission.

const emitter = socket
  .createEmitter<{ message: string }>()({
    topic: "chat-message",
  })
  .setPayloadMapper((payload) => {
    return { ...payload, timestamp: Date.now() };
  });

---

See More

Socket

Learn more about the Socket class and its configuration options.

Listener

Learn more about the Listener class and its configuration options.

Socket SDK

Use emitters via a type-safe, proxy-based SDK with centralized configuration.