Client

PubSub.Client

You can use the Client object to build a messaging system into the browser.

Example usage:

import { PubSub } from '@signalwire/js'

const pubSubClient = new PubSub.Client({
  token: '<your pubSub token>', // get this from the REST APIs
})

await pubSubClient.subscribe([ 'mychannel1', 'mychannel2' ])

pubSubClient.on('message', (message) => {
  console.log("Received", message.content,
              "on", message.channel,
              "at", message.publishedAt)
})

await pubSubClient.publish({
  channel: 'mychannel1',
  content: 'hello world'
})

Events

Please see ClientApiEvents for the list of events emitted by a pubSub Client object.

Constructors

constructor

new Client(pubSubOptions)

Creates a new PubSub client.

Parameters

NameTypeDescription
pubSubOptionsObject-
pubSubOptions.tokenstring

SignalWire PubSub token (you can get one with the REST APIs)

Example

import { PubSub } from '@signalwire/js'

const pubSubClient = new PubSub.Client({
  token: '<your pubSub token>',
})

Methods

off

off<T>(event, fn?): EmitterContract<ClientApiEvents>

Type parameters

NameType
Textends keyof ClientApiEvents

Parameters

NameType
eventT
fn?(...args: ArgumentMap<ClientApiEvents>[Extract<T, keyof ClientApiEvents>]) => void

Returns

EmitterContract<ClientApiEvents>


on

on<T>(event, fn): EmitterContract<ClientApiEvents>

Type parameters

NameType
Textends keyof ClientApiEvents

Parameters

NameType
eventT
fn(...args: ArgumentMap<ClientApiEvents>[Extract<T, keyof ClientApiEvents>]) => void

Returns

EmitterContract<ClientApiEvents>


once

once<T>(event, fn): EmitterContract<ClientApiEvents>

Type parameters

NameType
Textends keyof ClientApiEvents

Parameters

NameType
eventT
fn(...args: ArgumentMap<ClientApiEvents>[Extract<T, keyof ClientApiEvents>]) => void

Returns

EmitterContract<ClientApiEvents>


publish

publish(params): Promise<void>

Publish a message into the specified channel.

Parameters

NameTypeDescription
paramsObject-
params.channelstring

Channel in which to send the message.

params.contentany

The message to send. This can be any JSON-serializable object.

params.meta?Record<any, any>

Metadata associated with the message. There are no requirements on the content of metadata.

Returns

Promise<void>

Examples

Publishing a message as a string:

await pubSub.publish({
  channel: 'my-channel',
  content: 'Hello, world.'
})

Publishing a message as an object:

await pubSub.publish({
  channel: 'my-channel',
  content: {
    field_one: 'value_one',
    field_two: 'value_two',
  }
})

removeAllListeners

removeAllListeners<T>(event?): EmitterContract<ClientApiEvents>

Type parameters

NameType
Textends keyof ClientApiEvents

Parameters

NameType
event?T

Returns

EmitterContract<ClientApiEvents>


subscribe

subscribe(channels): Promise<void>

List of channels for which you want to receive messages. You can only subscribe to those channels for which your token has read permission.

Note that the subscribe function is idempotent, and calling it again with a different set of channels will not unsubscribe you from the old ones. To unsubscribe, use unsubscribe.

Parameters

NameTypeDescription
channelsstring | string[]

the channels to subscribe to, either in the form of a string (for one channel) or an array of strings.

Returns

Promise<void>

Example

const pubSub = new PubSub.Client({
  token: '<your pubSub token>'
})

pubSub.on('message', m => console.log(m))

await pubSub.subscribe("my-channel")
await pubSub.subscribe(["chan-2", "chan-3"])

unsubscribe

unsubscribe(channels): Promise<void>

List of channels from which you want to unsubscribe.

Parameters

NameTypeDescription
channelsstring | string[]

the channels to unsubscribe from, either in the form of a string (for one channel) or an array of strings.

Returns

Promise<void>

Example

await pubSub.unsubscribe("my-channel")
await pubSub.unsubscribe(["chan-2", "chan-3"])

updateToken

updateToken(token): Promise<void>

Replaces the token used by the client with a new one. You can use this method to replace the token when for example it is expiring, in order to keep the session alive.

The new token can contain different channels from the previous one. In that case, you will need to subscribe to the new channels if you want to receive messages for those. Channels that were in the previous token but are not in the new one will get unsubscribed automatically.

Parameters

NameTypeDescription
tokenstring

the new token.

Returns

Promise<void>

Example

const pubSubClient = new PubSub.Client({
  token: '<your pubSub token>'
})

pubSubClient.on('session.expiring', async () => {
  const newToken = await fetchNewToken(..)

  await pubSubClient.updateToken(newToken)
})