Adonis Transmit Client is a client for the native Server-Sent-Event (SSE) module of Adonis Transmit. 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
• Subscribing to channels
  • Subscription Request
  • Reconnecting
  • Unsubscribing
• Events

Installation

Install the package from the npm registry as follows:

npm i @brighthustle/transmit-client

# yarn
yarn add @brighthustle/transmit-client

# pnpm
pnpm add @brighthustle/transmit-client

Using the package as script tag on HTML:

<script src="https://www.unpkg.com/@brighthustle/[email protected]/src/transmit.js"></script>

Usage

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

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

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

Subscribing to channels

The listenOn method accepts the channel name and a callback to be invoked when the event is received from the server.

transmit.listenOn<{ message: string }>('chat/1', (payload) => {
  console.log(payload.message)
})

You can also listen from a channel only once.

transmit.listenOnce<{ message: string }>('chat/1', () => {
  console.log('first message received!')
})

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: RequestInit) => {
    console.log('beforeSubscribe')
  },
  beforeUnsubscribe: (_request: RequestInit) => {
    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')
  },
})

Unsubscribing

The listenOn method returns a function to unsubscribe from the channel.

const unsubscribe = transmit.listenOn('chat/1', () => {
  console.log('message received!')
})

// later
unsubscribe()

When unsubscribing from a channel, the client will remove the local listener for that channel. By default, it will not send a request to the server when there are no more listener to unsubscribe from the channel. You can change this behavior by setting the removeSubscriptionOnZeroListener option to true.

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

You can also change the default settings locally by passing a boolean to the unsubscribe method.

const unsubscribe = transmit.listenOn('chat/1', () => {
  console.log('message received!')
})

// later
unsubscribe(true) // or false

Events

TheTransmit class extends the EventTarget class and emits multiple events.

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

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

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