Rename broadcast result property to something else (example channel) #29

Stream.broadcast() currently returns a broadcast property:

const { writer, broadcast } = Stream.broadcast();

const consumer1 = broadcast.push();
const consumer2 = broadcast.push();

This produces the repetitive expression broadcast = Stream.broadcast().
Can we name it to something else, to avoid this confusion?

Proposed API

Rename the returned property to channel

interface BroadcastResult {
  writer: Writer;
  channel: Broadcast;
}

Stream.broadcast() would return:

return {
  writer,
  channel: broadcastImpl,
};

The Broadcast interface and the Stream.broadcast() method would retain their existing names.

Motivation

channel better describes the consumer-facing side of the broadcast channel while avoiding duplicated terminology:

// Current
const { broadcast } = Stream.broadcast();

// Proposed
const { channel } = Stream.broadcast();

This also makes the relationship between the two returned endpoints easier to understand:

• writer is the producer-facing endpoint.
• channel is the consumer-facing endpoint.

Alternatives considered

Rename Stream.broadcast() to Stream.multicast()

multicast is technically accurate, but broadcast is already understandable and contrasts well with Stream.share(). It would also require a broader API migration without resolving the need to name the returned consumer-facing endpoint.

Use source

const { writer, source } = Stream.broadcast();

This describes its role but loses the useful broadcast-channel terminology and could be confused with an upstream input source.

Use readable

const { writer, readable } = Stream.broadcast();

The returned object creates multiple readable consumers rather than being a single readable stream, so readable could be misleading.