AdonisJS Transmit Client is a client for the native Server-Sent-Event (SSE) module of AdonisJS. It is built on top of the EventSource API and provides a simple API to receive events from the server.

Table of Contents

• Installation
• Usage
• Creating a subscription
  • Unsubscribing
  • Subscription Request
  • Reconnecting
  • Events

Installation

Install the package from the npm registry as follows:

npm i @adonisjs/transmit-client

Usage

The module exposes a Transmit class, which can be used to connect to the server and listen for events.

import { Transmit } from '@adonisjs/transmit-client'

const transmit = new Transmit({
  baseUrl: 'http://localhost:3333',
})

Creating a subscription

The subscription method is used to create a subscription to a channel. The method accepts the channel name

const subscription = transmit.subscription('chat/1')

Then, you have to call the create method on the subscription to register it on the backend.

await subscription.create()

You can listen for events on the channel using the onMessage method. You can define as many listeners as you want on the same subscription.

subscription.onMessage((message) => {
  console.log(message)
})

You can also listen only once for a message using the onMessagetOnce method.

subscription.onMessageOnce((message) => {
  console.log('I will be called only once')
})

Note listeners are local only; you can add them before or after registering your subscription on the server.

Unsubscribing

The onMessage method returns a function to remove the message handler from the subscription.

const unsubscribe = subscription.onMessage(() => {
  console.log('message received!')
})

// later
unsubscribe()

If you want to entirely remove the subscription from the server, you can call the delete method.

await subscription.delete()

Subscription Request

You can alter the subscription request by using the beforeSubscribe or beforeUnsubscribe options.

const transmit = new Transmit({
  baseUrl: 'http://localhost:3333',
  beforeSubscribe: (_request: Request) => {
    console.log('beforeSubscribe')
  },
  beforeUnsubscribe: (_request: Request) => {
    console.log('beforeUnsubscribe')
  },
})

Reconnecting

The transmit client will automatically reconnect to the server when the connection is lost. You can change the number of retries and hook into the reconnect lifecycle as follows:

const transmit = new Transmit({
  baseUrl: 'http://localhost:3333',
  maxReconnectionAttempts: 5,
  onReconnectAttempt: (attempt) => {
    console.log('Reconnect attempt ' + attempt)
  },
  onReconnectFailed: () => {
    console.log('Reconnect failed')
  },
})

Events

TheTransmit class uses the EventTarget class to emits multiple events.

transmit.on('connected', () => {
  console.log('connected')
})

transmit.on('disconnected', () => {
  console.log('disconnected')
})

transmit.on('reconnecting', () => {
  console.log('reconnecting')
})