PUBSUB.md

PubSub API

• ipfs.pubsub.subscribe(topic, handler, [options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pubsub.unsubscribe(topic, handler, [options])
  • Parameters
  • Options
  • Returns
  • Example
  • Notes
• ipfs.pubsub.publish(topic, data, [options])
  • Returns
  • Example
• ipfs.pubsub.ls([options])
  • Parameters
  • Options
  • Returns
  • Example
• ipfs.pubsub.peers(topic, [options])
  • Returns
  • Example

ipfs.pubsub.subscribe(topic, handler, [options])

Subscribe to a pubsub topic.

Parameters

Name	Type	Description
topic	String	The topic name
handler	Function<(msg) => {}>	Event handler which will be called with a message object everytime one is received. The msg has the format {from: String, seqno: Buffer, data: Buffer, topicIDs: Array<String>}

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<void>	If action is successfully completed. Otherwise an error will be thrown

Example

const topic = 'fruit-of-the-day'
const receiveMsg = (msg) => console.log(msg.data.toString())

await ipfs.pubsub.subscribe(topic, receiveMsg)
console.log(`subscribed to ${topic}`)

A great source of examples can be found in the tests for this API.

ipfs.pubsub.unsubscribe(topic, handler, [options])

Unsubscribes from a pubsub topic.

Parameters

Name	Type	Description
topic	String	The topic to unsubscribe from
handler	Function<(msg) => {}>	The handler to remove

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<void>	If action is successfully completed. Otherwise an error will be thrown

Example

const topic = 'fruit-of-the-day'
const receiveMsg = (msg) => console.log(msg.toString())

await ipfs.pubsub.subscribe(topic, receiveMsg)
console.log(`subscribed to ${topic}`)

await ipfs.pubsub.unsubscribe(topic, receiveMsg)
console.log(`unsubscribed from ${topic}`)

Or removing all listeners:

const topic = 'fruit-of-the-day'
const receiveMsg = (msg) => console.log(msg.toString())

await ipfs.pubsub.subscribe(topic, receiveMsg);

// Will unsubscribe ALL handlers for the given topic
await ipfs.pubsub.unsubscribe(topic);

A great source of examples can be found in the tests for this API.

Notes

If the topic and handler are provided, the handler will no longer receive updates for the topic. This behaves like EventEmitter.removeListener. If the handler is not equivalent to the handler provided on subscribe, no action will be taken.

If only the topic param is provided, unsubscribe will remove all handlers for the topic. This behaves like EventEmitter.removeAllListeners. Use this if you would like to no longer receive any updates for the topic.

ipfs.pubsub.publish(topic, data, [options])

Publish a data message to a pubsub topic.

• topic: String
• data: Buffer|String - The message to send

Returns

Type	Description
Promise<void>	If action is successfully completed. Otherwise an error will be thrown

Example

const topic = 'fruit-of-the-day'
const msg = new TextEncoder().encode('banana')

await ipfs.pubsub.publish(topic, msg)

// msg was broadcasted
console.log(`published to ${topic}`)

A great source of examples can be found in the tests for this API.

ipfs.pubsub.ls([options])

Returns the list of subscriptions the peer is subscribed to.

Parameters

None

Options

An optional object which may have the following keys:

Name	Type	Default	Description
timeout	Number	undefined	A timeout in ms
signal	AbortSignal	undefined	Can be used to cancel any long running requests started as a result of this call

Returns

Type	Description
Promise<string[]>	An array of topicIDs that the peer is subscribed to

Example

const topics = await ipfs.pubsub.ls()
console.log(topics)

A great source of examples can be found in the tests for this API.

ipfs.pubsub.peers(topic, [options])

Returns the peers that are subscribed to one topic.

• topic: String

Returns

Type	Description
Promise<string[]>	An array of peer IDs subscribed to the topic

Example

const topic = 'fruit-of-the-day'

const peerIds = await ipfs.pubsub.peers(topic)
console.log(peerIds)

A great source of examples can be found in the tests for this API.