bare-broadcast-channel

bare-broadcast-channel — Multi-producer, multi-consumer inter-thread broadcast messaging for JavaScript. It is a native addon. Unlike bare-channel, which is single-producer / single-consumer over a fixed port pair, any number of ports (up to BroadcastChannel.MAX_PORTS) can connect to the same channel; each write is broadcast to every other connected port, and a port never receives the messages it wrote itself.

npm i bare-broadcast-channel

Usage

const BroadcastChannel = require('bare-broadcast-channel')
const { Thread } = Bare

const channel = new BroadcastChannel()

const consumer = (label) =>
  new Thread(__filename, { data: { handle: channel.handle, label } }, async ({ handle, label }) => {
    const BroadcastChannel = require('bare-broadcast-channel')
    const port = BroadcastChannel.from(handle).connect()
    console.log(label, 'got', await port.read())
    await port.close()
  })

const a = consumer('a')
const b = consumer('b')

const port = channel.connect()

while (port.peers < 2) await new Promise((r) => setTimeout(r, 10))

await port.write('hello')
await port.close()

a.join()
b.join()

API

BroadcastChannel

new BroadcastChannel(opts?: BroadcastChannelOptions)

Create a new broadcast channel. The channel is backed by a SharedArrayBuffer exposed as channel.handle that can be passed to other threads to share the channel across them.

Parameters

BroadcastChannel.from

BroadcastChannel.from(handle: SharedArrayBuffer, opts?: BroadcastChannelOptions): BroadcastChannel

Restore a channel from its SharedArrayBuffer handle. options accepts the same fields as the constructor, except for handle.

Parameters

Returns BroadcastChannel — A channel backed by the given handle.

BroadcastChannel.MAX_PORTS: number

Maximum number of ports that may be concurrently connected to a single channel. A port's slot is released for reuse once the port holding it has fully torn down.

connect(): Port<T>

Connect a new port to the channel. Throws if MAX_PORTS ports are already connected. Port slots are reused, so the cap applies to the number of concurrently connected ports, not the total number of connections over the channel's lifetime; a slot is released for a later connection once the port holding it has fully torn down.

Returns Port<T> — A new port connected to the channel.

handle: SharedArrayBuffer

The SharedArrayBuffer backing the channel. Pass this to other threads to share the channel.

interfaces: SerializableConstructor[]

The serializable and transferable interfaces registered on the channel.

Port

new Port(channel: BroadcastChannel<T>)

Parameters

close(): Promise<void>

createReadStream(opts?: ReadableOptions<Port<T>>): Readable

Parameters

createStream(opts?: DuplexOptions<Port<T>>): Duplex

Parameters

createWriteStream(opts?: WritableOptions<Port<T>>): Writable

Parameters

peers: number

read(): Promise<T | null>

readSync(): T | null

ref(): void

unref(): void

write(value: T): Promise<boolean>

Broadcast a structured-cloneable value to every other port connected to the channel. A port never receives the messages it wrote itself.

Parameters

Returns Promise<boolean> — Whether the write flushed.

writeSync(value: T): boolean

Broadcast a structured-cloneable value to every other port connected to the channel. A port never receives the messages it wrote itself.

Parameters

Returns boolean — Whether the write flushed.

Types

BroadcastChannelOptions

interface BroadcastChannelOptions {
  handle?: SharedArrayBuffer
  interfaces?: SerializableConstructor[]
  portCapacity?: number
}

PortEvents

interface PortEvents {
  peers: [count: number]
  close: []
}

See also

• Builds on bare-events, bare-stream, and bare-structured-clone.
• Bare modules — the full bare-* catalog.
• Bare runtime API — the runtime these modules extend.