Emitting Events

In real-time applications, you often need to send data from the client to the server. With Hyper-Fetch's socket module, you can emit events to send data, and optionally.

What you'll learn

1. How to create an emitter to send events.
2. How to send data with an event.
3. How to handle server acknowledgments.
4. The difference between using .setPayload() and passing data directly to .emit().
5. How to use parameters in event topics.

---

Creating an Emitter

First, you need to create an emitter instance. An emitter is responsible for sending events to a specific topic on your server. You can define the types for the data you're sending.

Let's create an emitter for a chat application.

type ChatMessageType = {
  message: string;
};

const sendChatMessage = socketInstance.createEmitter<ChatMessageType>()({
  endpoint: "chat-message", // topic of the event
});

---

Sending Data

There are two main ways to send data with an emitter:

1. Using .setPayload(): You can prepare the emitter with data before sending it. This is useful if you want to create a reusable emitter instance with predefined data.
2. Passing data to .emit(): You can pass the data directly to the .emit() method. This is convenient for one-time emissions.

1. Using .setPayload()

You can use the .setPayload() method to attach data to the emitter. This method returns a new emitter instance with the data, so the original emitter remains unchanged.

const emitterWithPayload = sendChatMessage.setPayload({
  message: "Hello from .setPayload()!",
});

// No need to pass data here as it's already set
emitterWithPayload.emit();

2. Passing Data to .emit()

Alternatively, you can pass the data as part of the options object to the .emit() method.

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

---

Using Parameters in Topics

Sometimes, you need to send events to dynamic topics, for example, to a specific user or a specific chat room. You can define parameters in the topic string, similar to how you define routes in a web framework.

Let's create an emitter to send a private message to a specific user.

const sendPrivateMessage = socketInstance.createEmitter<{ message: string }>()({
  endpoint: "private-message/:userId",
});

You can then set the userId parameter when you emit the event:

const privateMessageEmitter = sendPrivateMessage.setParams({
  userId: "user-123",
});

privateMessageEmitter.emit({
  payload: { message: "This is a private message!" },
});

When this event is sent, user-123 will be substituted into the topic, and the event will be sent to private-message/user-123.

---

Payload Mapper

You can transform the payload before it's sent using setPayloadMapper. This is useful for adding metadata, formatting data, or encrypting messages:

const sendMessage = socketInstance
  .createEmitter<{ message: string }>()({
    endpoint: "chat-message",
  })
  .setPayloadMapper((payload) => ({
    ...payload,
    timestamp: Date.now(),
    version: "v2",
  }));

---

Congratulations!

You've learned how to emit events with Hyper-Fetch Sockets!

• You can create an emitter for a specific event topic.
• You can send data using .setPayload() or by passing it directly to .emit().
• You can use parameters in topics to send events to dynamic endpoints.