Listener

Listener

Read the API Reference »

---

Introduction

Listener is a class that creates a template for receiving events from server. Its strength is its strict and predictable data structure which together with typescript gives a lot of confidence while developing data exchange features.

To use the listener we need to trigger the listen method with provided callback.

---

Purpose

• Configures events listeners templates
• Standardizes the system’s data schema
• Listen to server events

---

Initialization

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

import { socketInstance } from "./socket";

export const onChatMessage = socketInstance.createListener<ChatMessageType>()({
  name: "chat-message", // name of the event
});

export const onUserStatusChange = socketInstance.createListener<UserStatusType>()({
  name: "status", // name of the event
});

---

Usage

Listening

Use the listen method to start the listening for incoming events.

onChatMessage.listen((message) => {
  // message have type ChatMessageType
  console.log(message);
});

Remove listener

Use the returned method to stop listening.

const removeEvent = onChatMessage.listen((message) => console.log(message));

...

removeEvent() // We remove listener

Remove event listeners directly from the client

const callback = (message) => console.log(message);
const removeEvent = onChatMessage.listen(callback);

...

socket.client.listeners.delete(onChatMessage.name) // We remove ALL listeners from given event
socket.client.listeners.get(onChatMessage.name).delete(callback) // We remove single listener from given event

Listen to event once

const removeEvent = onChatMessage.listen((message) => {
  console.log(message);
  removeEvent(); // We listen only to single event
});

---

Methods

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

danger

Using any method on listener returns its clone! We don't return a reference!

// ❌ WRONG

const listener = getChatMessageListener;

listener.setOptions({ ... }); // Returns CLONED listener with assigned options

listener.listen(); // Error - no options will be applied

// ✅ Good

const listener = getChatMessageListener;

const listenerWithOptions = listener.setOptions({ ... }); // Returns CLONED listener with assigned options

listenerWithOptions.listen(); // Success - options applied

---

Parameters

Configuration options

{
  name: string;
  options: SocketOptions;
}