💡Getting Started

Install the package. It's only ~1.9kb at the time of writing.

npm i hypercast

Topics

Hypercast instances have many topics, which are kind of like a channel that a group of Hypercast clients connect to and communicate through. So to use Hypercast, you need to create and manage one or more topics.

The easiest way to do this is with the Operator class:

import { Operator } from 'hypercast/client'

const operator = new Operator()
const { topic } = await operator.createTopic()

Once you have a topic, you can instantiate a Hypercast client.

const hypercast = operator.connect(topic)

Other times, you'll have the topic already and can stand up a client directly.

import { Hypercast } from 'hypercast/client'

const hypercast = new Hypercast(topic)

Sending Messages

With your Hypercast client you can now send and receive messages from other clients connected to the same topic. Clients don't receive messages their own messages, only those that originated from other connections.

hypercast.on('message', ({ data }) => {
  console.log('received', data)
})

hypercast.send('hello')

You can send any serializable message you wish. Arrays, objects, numbers, and strings are all fair game. The client instance will internally stringify what you pass it, so no need to run JSON.stringify unless you have non-standard stuff like circular references.

hypercast.send({ message: 'hello' })

Full(ish) example

import { Operator } from 'hypercast/client'

enum Event {
  Connect = 'connect',
  Message = 'message',
}

type Events = {
  type: Event.Connect
  data: { name: string },
} | {
  type: Event.Message,
  data: { value: string },
}

const operator = new Operator<Events>('...')
const { topic } = await operator.createTopic()
const hypercast = operator.connect(topic)

hypercast.on('message', ({ type, data }) => {
  switch (type) {
    case Event.Connect:
      setName(data.name)
      break
    case Event.Message:
      setMessages(state => [...state, data.value])
  }
})

const ack = hypercast.send({
  type: Event.Connect,
  data: { name: 'Jane' },
})

await ack