Interface: MessageChannel

Public interface for a bi-directional communication channel between client and server.

MessageChannels are obtained from Session.availableMessageChannels and provide methods to send messages to the server and receive messages asynchronously.

Channels are opened automatically on the first sendServerMessage() or receiveMessage() call.

Example

// Get first available channel
const channel = session.availableMessageChannels[0];
if (channel) {
  // Option 1: Send first (auto-opens channel)
  const message = new TextEncoder().encode("Hello Server");
  channel.sendServerMessage(message);

  // Option 2: Receive first (also auto-opens channel)
  const data = await channel.receiveMessage();

  // Receive messages in a loop (simple API)
  while (true) {
    const data = await channel.receiveMessage();
    if (data === null) break; // Channel closed
    console.log('Received:', new TextDecoder().decode(data));
  }

  // Alternative: Use stream directly (advanced)
  const reader = channel.receivedMessageStream.getReader();
  const { done, value } = await reader.read();

  // Close when done
  channel.disconnect();
}

// Option 3: Use `using` for automatic cleanup
using channel = session.availableMessageChannels[0];
if (channel) {
  await channel.sendServerMessage(data);
  // Channel automatically disconnects when exiting scope
}

Extends

• Disposable

Properties

uuid

readonly uuid: Uint8Array

Unique identifier for this channel (defined by server). Use this UUID to identify the channel in your application logic.

---

status

readonly status: MessageChannelStatus

Current status of the channel.

• NotInitialized: Channel announced but not yet opened

• Ready: Channel is open and operational

• Closed: Channel terminated

---

receivedMessageStream

readonly receivedMessageStream: ReadableStream<Uint8Array<ArrayBufferLike>>

Stream for receiving messages from the server.

For advanced use cases requiring stream control (e.g., backpressure, transformations). For simple cases, use receiveMessage() instead.

Example

// Advanced: Transform stream
const decoder = new TextDecoderStream();
const textStream = channel.receivedMessageStream.pipeThrough(decoder);

for await (const text of textStream) {
  console.log('Received:', text);
}

Methods

sendServerMessage()

sendServerMessage(data): boolean

Sends a message to the server on this channel.

Automatically opens the channel on first send if not already open.

Parameters

data

Uint8Array

The message data to send

Returns

boolean

true if the message was sent successfully, false otherwise

Remarks

• First call will send OPEN control message and transition to Ready state

• Subsequent calls send data directly

• Returns false if channel is Closed

Example

const message = new TextEncoder().encode("Hello Server");
if (channel.sendServerMessage(message)) {
  console.log('Message sent successfully');
} else {
  console.log('Failed to send message');
}

---

receiveMessage()

receiveMessage(): Promise<Uint8Array<ArrayBufferLike> | null>

Receives the next message from the server asynchronously.

This is a convenience method that wraps receivedMessageStream. Each call waits for the next message from the server.

The channel is automatically opened on the first call if not already open.

Returns

Promise<Uint8Array<ArrayBufferLike> | null>

A promise that resolves to the received message data, or null if the channel is closed

Example

// Simple message loop - channel opens automatically on first call
while (true) {
  const message = await channel.receiveMessage();
  if (message === null) {
    console.log('Channel closed');
    break;
  }
  console.log('Received:', new TextDecoder().decode(message));
}

---

disconnect()

disconnect(): void

Closes the channel.

Sends CLOSE control message and transitions to Closed state. After calling disconnect(), the channel can no longer send or receive messages.

Returns

void

Example

// Close when done
channel.disconnect();
console.log('Channel closed');