Port+ – Advanced Web Messaging Primitives

[![npm version][npm-version-src]][npm-version-href]
[![bundle][bundle-src]][bundle-href]
[![License][license-src]][license-href]

Port+ is an upgrade to the web's port-based messaging APIs — MessagePort, MessageChannel, BroadcastChannel – and an onboarding of the
WebSocket API into the same port-based messaging model.

This README takes you from installation to the design concepts and, ultimately, to the added capabilities implied by Port+.

---

Install

``bash
npm i @webqit/port-plus
`

`js
import { MessageChannelPlus, BroadcastChannelPlus, WebSocketPort, StarPort, RelayPort, Observer } from '@webqit/port-plus';
`

CDN Include

`html



`

---

Design Concepts

Port+ is an API mirror of the Web Messaging APIs built for advanced use cases. An instance of BroadcastChannelPlus, for example, is the same BroadcastChannel instance, but one that lets you do more.

To see that changed, here is the existing set of Web Messaging APIs. Next, is the Port+ equivalent.

$3

#### 1. MessageChannel

`
MessageChannel (mch)
├─ mch.port1 ──► MessageEvent (e) ──► e.ports
└─ mch.port2 ──► MessageEvent (e) ──► e.ports
`

In this structure:

* mch.port1 and mch.port2 are each a message port (MessagePort)
* messages (e) arrive as message events (MessageEvent)
* e.ports are each a message port (MessagePort)

#### 2. BroadcastChannel

`
BroadcastChannel (brc) ──► MessageEvent (e)
`

In this structure:

* the BroadcastChannel interface is the message port – the equivalent of MessagePort
* messages (e) arrive as message events (MessageEvent)
* no reply ports; e.ports is empty; not implemented in BroadcastChannel

#### 3. WebSocket

`
WebSocket ──► MessageEvent (e)
`

In this structure:

* the WebSocket interface is partly a message port (having addEventListener()) and partly not (no postMessage())
* messages (e) arrive as message events (MessageEvent)
* no reply ports; e.ports is empty; not implemented in WebSocket
* no API parity with MessagePort / BroadcastChannel in all

$3

#### 1. MessageChannelPlus

`
MessageChannelPlus (mch)
├─ mch.port1+ ──► MessageEventPlus (e) ──► e.ports+
└─ mch.port2+ ──► MessageEventPlus (e) ──► e.ports+
`

In this structure:

* mch.port1+ and mch.port2+ are Port+ interfaces (MessagePortPlus)
* messages arrive as MessageEventPlus
* e.ports+ recursively expose Port+ interfaces
* reply ports support advanced features (requests, live objects, relays)

#### 2. BroadcastChannelPlus

`
BroadcastChannelPlus (brc) ──► MessageEventPlus (e) ──► e.ports+
`

In this structure:

* BroadcastChannelPlus acts as a full Port+ interface
* messages arrive as MessageEventPlus
* e.ports+ enables reply channels where native BroadcastChannel does not
* broadcast semantics are preserved while extending capabilities

#### 3. WebSocketPort (WebSocket)

`
WebSocketPort ──► MessageEventPlus (e) ──► e.ports+
`

In this structure:

* WebSocketPort wraps a WebSocket as a Port+ interface
* postMessage() replaces ad-hoc send() usage
* messages arrive as MessageEventPlus
* e.ports+ enables reply channels over WebSockets
* lifecycle and messaging semantics align with other Port+ interfaces

$3

Port+ unifies the messaging model across all three and extends the port interfaces and MessageEvent interface for advanced use cases.

General mental model:

`
port+ ──► MessageEventPlus ──► e.ports+
`

Meaning: Port+ interfaces emit MessageEventPlus, which recursively exposes Port+ interface over at e.ports.

---

The Port+ API Overview

$3

| API / Feature | Port+ | Msg. Ports | WS |
| :--------------------------------- | :--------------- | :---------------- | :------------ |
| postMessage() | ✓ (advanced) | ✓ (basic) | ✗ (send()) |
| postRequest() | ✓ | ✗ | ✗ |
| addEventListener() / onmessage | ✓ | ✓ | ✓ |
| addRequestListener() | ✓ | ✗ | ✗ |
| readyState | ✓ | ✗ | ✓ |
| readyStateChange() | ✓ | ✗ | ✗ |
| relay() | ✓ | ✗ | ✗ |
| channel() | ✓ | ✗ | ✗ |
| projectMutations() | ✓ | ✗ | ✗ |
| close() | ✓ | ✓ | ✓ |
| Live Objects** | ✓ | ✗ | ✗ |

In this table:

* Port+ → MessagePortPlus, BroadcastChannelPlus, WebSocketPort
* Msg. Ports → MessagePort, BroadcastChannel
* WS → WebSocket
* → All-new concept

$3

| API / Feature | Port+ | Msg. Event | WS |
| :--------------------------- | :----------------------------- | :---------------------------- | :--------------------- |
| data | ✓ (_Live Objects_ support) | ✓ (no _Live Objects_) | ✓ (typically string) |
| type | ✓ | ✓ | ✓ |
| ports | ✓ (Port+) | ✓ | ✗ |
| preventDefault() | ✓ | ✓ | ✗** |
| defaultPrevented | ✓ | ✓ | ✗** |
| stopPropagation() | ✓ | ✓ | ✗** |
| stopImmediatePropagation() | ✓ | ✓ | ✗** |
| respondWith() | ✓ | ✗ | ✗ |
| eventID | ✓ | ✗ | ✗ |
| live | ✓ | ✗ | ✗ |
| relayedFrom | ✓ | ✗ | ✗ |

In this table:

* Port+ → MessageEventPlus
* Msg. Event → MessageEvent
* WS → WebSocket's MessageEvent
* → May be present, but may not be implemented

---

Entry Points

The APIs below are the entry points to a Port+-based messaging system.

`js
const mch = new MessageChannelPlus();
const brc = new BroadcastChannelPlus('channel-name');
const soc = new WebSocketPort(url); // or new WebSocketPort(ws)
`

Above, WebSocketPort also takes a WebSocket instance – letting you create a port from an existing WebSocket connection:

`js
const ws = new WebSocket(url);
const port = new WebSocketPort(ws);
`

On a WebSocket server, for example, you can do:

`js
const wss = new WebSocketServer({ server });
wss.on('connection', (ws) => {
// The basic way
ws.send('something');

// The unified way
const port = new WebSocketPort(ws);
port.postMessage('something');
});
`

Whatever the port+ type, every Port+ instance exposes the same interface and capabilities. For example, with WebSocketPort you get an event.ports implementation over web sockets consistent with the rest.

All Port+ interfaces also support live state projection, lifecycle coordination, request/response semantics, and routing.

---

Live State Projection (Live Objects)

Port+ extends message passing with the ability to project state across a port connection and keep that state synchronized over time.

This capability is referred to as Live State Projection, and the projected objects are called Live Objects.

Live State Projection is established via the same .postMessage() API:

Sender:

`js
const state = { count: 0 };

port.postMessage({ state }, { live: true });
`

Receiver:

`js
port.addEventListener('message', (e) => {
if (e.live) console.log('Live object received');
const { state } = e.data;
});
`

In live mode, continuity of the original object is achieved. Every mutation on the sender side automatically converges on the received copy, and those mustations are observable:


Sender:

`js
setInterval(() => {
Observer.set(state, 'count', state.count + 1;
}, 1000);
`

Receiver:

`js
Observer.observe(state, () => {
console.log(state.count);
});
`

$3

When an object is sent with { live: true }, Port+ establishes a projection with the following behavior:

* mutations on the source object are observed using using the Observer API
* differential updates are sent over a private channel; they converge on the same object on the other side

Projection is bound to the lifecycle of the port. It begins once the message is delivered and terminates automatically when the port closes. After closure, the target object remains usable but no longer receives updates.

$3

In some cases, live state must be projected independently of a specific message. Port+ supports this through a .projectMutations() API.

Instead of deriving identity from a message event, both sides explicitly agree on a shared object identity and a propagation channel over which to project mutations.

Below, both sides agree on a certain object identity – 'counter' – and a propagation channel anique to the object: 'counter'.

Sender

`js
const state = { count: 0 };

const stop = port.projectMutations({
from: state,
to: 'counter'
});

setInterval(() => {
Observer.set(state, 'count', state.count + 1);
}, 1000);
`

Receiver:

`js
const state = {};

const stop = port.projectMutations({
from: 'counter',
to: state
});

Observer.observe(state, () => {
console.log(state.count);
});
`

In each case, the return value of projectMutations() is a cleanup function:

`js
stop(); // terminates the projection
`

Calling it stops mutation tracking and synchronization without closing the port.

This lower-level API is intended for advanced scenarios where object identity and lifetime are managed outside the messaging system.

$3

Live State Projection enables a shared reactive model across execution contexts.

Rather than exchanging updated values, both sides operate on corresponding objects that maintain:

* shared identity — distinct objects representing the same logical entity
* continuity — stable object references over time
* deterministic convergence — ordered, differential mutation application
* lifecycle scoping — synchronization exists only while the port exists

This allows state to be treated as persistent and reactive across a messaging boundary, without polling, replacement, or manual reconciliation.

---

Lifecycles

This section covers important phases in the life of a Port+ instance. Understanding Port+ lifecycles is recommended for coordinating a Port+ messaging system.

$3

Every Port+ instance transitions through different states in its lifetime:

- connecting: The port is being established or is waiting for a connection to be established.
- open: The port is ready for interaction.
- closed: The port is closed.

At any given point in time, a port is in exactly one of these states. This state is exposed via the .readyState property.

State transitions (observable milestones) can be observed imperatively using .readyStateChange():

`js
// The port is ready for interaction.
await port.readyStateChange('open');

// The port has sent its first message.
await port.readyStateChange('messaging');

// The port is closed.
await port.readyStateChange('close');
`

> [!TIP]
> The readyState property reflects the current state as a descriptive value (e.g. 'closed'), while readyStateChange() listens for lifecycle transitions using event-style names (e.g. 'close').

$3

Native web messaging APIs do not expose Ready State information consistently. While WebSockets expose transport-level Ready State (connecting -> open -> closing -> closed), MessagePorts and BroadcastChannels expose no readiness signal at all. Consequently, the default Ready State behaviour acorss port types is:

| Port Type | Ready State |
| --- | --- |
| WebSocket | open (when a connection is established) -> messaging (when the first message is sent) -> close (when the connection is closed) |
| MessagePort | open (immediately on instantiation) -> messaging (when the first message is sent) -> close (when the port is closed) |
| BroadcastChannel | open (immediately on instantiation) -> messaging (when the first message is sent) -> close (when the channel is closed) |

Here, only WebSockets can tell when the other side of the port is connected. For the others, the open state is really about the local end of the port itself, not about the remote end.

Not knowing when the other side of the port is connected can be a limitation when multiple lifecycles need to be coordinated.

Port+ addresses this by introducing an explicit handshake phase that applies uniformly across all port types. You opt-in via options.handshake:

`js
// An example for a BroadcastChannel port
const port = new BroadcastChannel(channel, { handshake: 1 });
`

options.handshake is a number between 0 and 2. When 0 – the default – no handshake takes place. When 1 or 2, the port goes through the Port+ handshake phase.

$3

Port+'s handshake model is designed to guarantee the readiness of the remote end of the port – rather than the readiness of the local end itself. In this mode, the port only transitions to the open state after each end of the port has ascertained that the other end is ready to interact – not just alive. Messages sent at this point are more likely to be read by "someone".

Either end begins the process by sending a "readinnes" signal and waits for it to be acknoledged. If the other end also acknoledges with "readinnes", both ends transitions to the open state. Otherwise, the originating end waits for an explicit "readinnes" signal from the other end. The transition to the open state happens when both ends have successfully exchanged "readinnes".

A Port+ instance self-signifies "readiness" on exactly one condition: when .start() is called. It says by that: "I'm ready to interact, not just alive". The options.handshake parameter, however, lets you say that either explicitly or implicitly:

+ When 1, handshake begins on the first interaction with:
+ addEventListener() – including higher level APIs that may trigger it
+ postMessage() – including, also, higher level APIs that may trigger it
This behaviour is called Readinnes by Interaction.
+ When 2, handshake begins on an explicit call to start()

`js
// An example for a BroadcastChannel port
const port = new BroadcastChannel(channel, { handshake: 1 });

port.addEventListener('message', handle); // Implicitly triggers start()
`

$3

Ports may be configured to implicitly await the open Ready State before sending messages. In this mode, outbound messages are automatically queued until the port is open.

`js
// An example for a BroadcastChannel port
const port = new BroadcastChannel(channel, { handshake: 1, postAwaitsOpen: true });

port.postMessage('hello');
// Queued until port is open.
// But { handshake: 1 } also lets postMessage() trigger the handshake process.
// Port is open – and messages flush – when the other end says "ready". Until then, queued

await port.readyStateChange('open');
// delivered by now
`

This allows application code to send messages with guaranteed coordination.

---

$3

Each Port+ transport participates in the handshake model differently, while exposing the same observable states.

#### MessagePortPlus via MessageChannelPlus

MessagePorts follow a symmetric, point-to-point handshake.

The port transitions to the open state when:

1. .start() is triggered explicitly or by interaction – on both ends
2. peer acknowledgment is recieved

The port closes via an explicit .close() call on either side. Closure on one end automatically triggers closure on the other – via a control message. Ready State transitions to closed.

#### BroadcastChannelPlus

BroadcastChannels form a many-to-many port topology and require additional coordination to make readiness meaningful.

Port+ supports two modes.

##### (a) Default (Peer Mode)

In default mode, each participant becomes open when:

1. .start() is triggered explicitly or by interaction
2. an acknowledgment is recieved from at least one peer in the shared channel

A participant closes via an explicit .close() call. Its Ready State transitions to closed.

##### (b) Client / Server Mode

While readiness is synchronized in the default mode – as with other port types – closure is not. A participant's closure has no effect on the others, by default.

To support use cases that require synchronized closure across participants, Port+ introduces an optional client/server operational model for BroadcastChannels.

The client/server model establishes explicit role semantics. Here, one participant is assigned a server role – the "control plane" – and the others are assigned a client role:

`js
const server = new BroadcastChannelPlus('room', {
clientServerMode: 'server'
});

const client1 = new BroadcastChannelPlus('room', {
clientServerMode: 'client'
});

const client2 = new BroadcastChannelPlus('room', {
clientServerMode: 'client'
});
`

Both server and clients can join the channel in any order, but the server:

+ maintains a reference to all connected clients
+ automatically triggers closure across all clients when closed
+ automatically closes when all clients leave – but if options.autoClose is enabled

By contrast, a client:

* closes alone when closed

This mode exists because BroadcastChannel’s native semantics do not provide coordinated teardown or authoritative control. Without it, participants cannot reliably know when a session has ended. Client/server mode enables explicit ownership, deterministic shutdown, and presence-aware coordination over a many-to-many topology.

#### WebSocketPort

WebSockets have a native Ready State system inspectable via an instance's .readyState property.

By default, Port+ lets the WebSocket’s native Ready State be the authoritative Ready State.

In this mode:

* The WebSocketPort's open and closed states are based on the WebSocket's native open and closed states
* no handshake takes place
* readiness is assumed once the socket opens

On choosing the explicit handshake model via options.handshake, the open state is determined differently.

`js
const port = new WebSocketPort(ws, { handshake: 1 });
`

In this mode, each side transitions to the open state when:

1. .start() is triggered explicitly or by interaction – on both ends
2. peer acknowledgment is recieved

This allows WebSocketPort to behave identically to MessagePortPlus and BroadcastChannelPlus with respect to readiness and cleanup.

---

Composition and Topology

Port+ is not limited to point-to-point messaging. Ports can be composed into higher-level structures that define how messages flow, where they propagate, and which connections participate.

$3

A StarPort is a fan-in / fan-out proxy over multiple ports.

It acts as a central aggregation point where:

messages received* by child ports bubble up to the star
messages sent* by the star fan out to all child ports

`js
const star = new StarPort();

star.addPort(port1);
star.addPort(port2);
star.addPort(port3);
`

#### Message Flow Semantics

##### Inbound (Bubbling)

As with every port, when a connected port receives a message from its remote peer, it receives a MessageEventPlus. Internally that comes as an event dispatched on the port:

`js
port1.dispatchEvent(new MessageEventPlus(data));
`

The event:

1. is dispatched on port1
2. bubbles up to the StarPort; thus, re-dispatched on star

The star port essentially makes it possible to listen to all messages received by any of its child ports:

`js
star.addEventListener('message', (e) => {
// receives messages from any child port
});
`

##### Outbound (Fan-Out)

A .start() call on the Star Port is a .start() call on all connected ports.
A .close() call on the Star Port is a .close() call on all connected ports.
A .postMessage() call on the Star Port is a .postMessage() call on all connected ports.

`js
star.postMessage(data);
`

This makes StarPort a true proxy: a single observable endpoint over many independent ports.

#### Lifecycle Behavior

A Star Port automatically transitions to the open state by default. But when options.handshake is enabled, its Ready State is controlled by that of its child ports:

* transitions to the open state when at least a child port exists and has Ready State open
* transitions to the closed state when the last child closes or is removed – but if options.autoClose is enabled

Regardless of options.handshake:

+ Closed ports are removed automatically.
+ Child ports added after .start() are automatically started.
+ Attempting to add a child port after .close() fails with an error.

#### Typical Uses

* centralized coordination
* shared state distribution
* transport-agnostic hubs

$3

A RelayPort is a router that forwards messages between sibling ports.

It is an extension of StarPort and inherits all of its properties, methods, and lifecycle behavior.

`js
const relay = new RelayPort('room');

relay.addPort(port1);
relay.addPort(port2);
relay.addPort(port3);
`

#### Message Flow Semantics

##### Inbound Routing

As with every port, when a connected port receives a message from its remote peer, it receives a MessageEventPlus. Internally that comes as an event dispatched on the port:

`js
port1.dispatchEvent(new MessageEventPlus(data));
`

Bubbling behaviour works as with a star port. In addition, the relay forwards it to all other connected ports as a .postMessage() call – excluding the originating port.
Each connected port sees the message as if it were sent directly by its peer.

This creates peer-to-peer fan-out.

##### Outbound Broadcast

As with the Star Port, a .postMessage() call on the relay port is a .postMessage() call to all connected ports.

##### Join / Leave Signaling

When a port joins (via relay.addPort()) or leaves (via relay.removePort() or via port closure), a synthetic join/leave message is routed to peers.

This enables presence-aware systems (e.g. chat rooms).

#### Typical Uses

* chat rooms
* collaborative sessions
* event fan-out
* decoupled peer coordination

$3

port.channel() is a universal instance method on all port types that creates a logical sub-port scoped to a message type or namespace over that port.

`js
const chat = port.channel('chat');
const system = port.channel('system');
`

A channel:

* filters inbound messages by the specified namespace (e.g. chat above)
* automatically namespaces outbound messages with the same

`js
chat.postMessage({ text: 'hello' });
// Equivalent to:
chat.postMessage({ text: 'hello' }, { type: 'chat:message' });
`

`js
chat.addEventListener('message', (e) => {
// receives only 'chat' messages
});
// Equivalent to:
chat.addEventListener('chat:message', (e) => {
// handle 'chat' messages
});
`

Channels are namespaces within the same port.

Channels compose naturally with StarPort and RelayPort.

$3

port.relay() is a universal instance method on all port types that establishes explicit routing relationships between ports.

`js
portA.relay({
to: portB,
channel: 'chat',
bidirectional: true
});
`

This means:

* messages received by portA on channel chat
→ are forwarded to portB
* optionally in both directions
* respecting lifecycle, and teardown rules – relay relationships are automatically torn down when either port closes

Use port.relay() to chain ports together transparently.

`js
// Forward Port A -> Port B
portA.relay({ to: portB });

// Bidirectional A <-> B
portA.relay({ to: portB, bidirectional: true });
`

Use RelayPort when:

* routing is shared across many ports
* join/leave semantics matter
* topology is explicit

$3

Live objects propagate through composition transparently.

* events bubble, or route, as defined
* mutation convergence follows routing paths
* projection terminates when required links close

This allows shared reactive state to exist across entire topologies, not just between endpoints.

---

Messaging Patterns

Port+ supports a small number of messaging patterns. These patterns are not separate APIs — they are ways of structuring interactions using the same port abstraction.

$3

Use this pattern when you need to notify the other side, without waiting for a response.

`js
port.postMessage({ op: 'invalidate-cache' });
`

This is appropriate when:

* ordering matters, but acknowledgment does not
* the sender does not depend on the receiver’s result
* failure can be handled independently

$3

Use this pattern when the sender expects a result and wants deterministic correlation.

`js
const result = await port.postRequest({
op: 'multiply',
args: [6, 7]
});
`

On the receiving side:

`js
port.addEventListener('request', (e) => {
if (e.data.op === 'multiply') {
return e.data.args[0] * e.data.args[1];
}
});
`

This pattern provides:

* automatic request correlation
* promise-based control flow
* rejection on timeout or port closure

Use this for command execution, queries, and remote procedure calls.

$3

Some interactions are not single exchanges, but conversations.

In these cases, Port+ provides reply ports — temporary, private ports scoped to a specific message. This is what .postRequest() and .addRequestListener() do under the hood.

`js
const messageChannel = new MessageChannelPlus;

// Listen on the reply port
messageChannel.port2.addEventListener('message', (e) => {
// handle reply
console.log('reply', e.data);
});

// Send the message with the reply port
const result = await port.postRequest(
{
op: 'multiply',
args: [6, 7]
},
[messageChannel.port1] // Transfer the reply port
);
`

On the receiving side:

`js
port.addEventListener('message', (e) => {
const reply = e.ports[0];

reply.postMessage(e.data.args[0] * e.data.args[1]);

// Continue the conversation
reply.addEventListener('message', (e) => {
console.log('follow-up:', e.data);
});
});
`

Reply ports:

* form a symmetric 1:1 connection
* close automatically when either side closes

Use reply ports when:

* responses are multi-step
* data streams over time
* isolation from other traffic matters

$3

Use channels to separate independent flows over the same port. Channels also use reply ports under the hood.

`js
const chat = port.channel('chat');
const system = port.channel('system');
`

`js
chat.postMessage({ text: 'hello' });
system.postMessage({ action: 'sync' });
`

Channels provide:

* logical namespacing
* inbound filtering
* outbound tagging

They do not create new connections and compose naturally with routing and topology.

$3

Use this pattern when two sides must stay synchronized over time.

`js
port.postMessage(state, { live: true });
`

On the receiving side:

`js
port.addEventListener('message', (e) => {
if (e.live) {
Observer.observe(e.data, () => {
render(e.data);
});
}
});
`

This pattern enables:

* shared identity across contexts
* differential mutation propagation
* lifecycle-bound reactivity

It is the foundation for collaborative state, projections, and reactive coordination.

(Detailed semantics are covered in the Live Objects section.)

---

API Reference

This section defines the formal API contract for Port+.
Conceptual behavior, lifecycle semantics, and usage patterns are documented in earlier sections.

1. MessagePortPlus (Base & Concrete Interfaces)
2. MessageEventPlus

$3

All Port+ implementations – MessagePortPlus, BroadcastChannelPlus, WebSocketPort, StarPort, RelayPort – conform to the MessagePortPlus interface.

$3

+ MessageChannelPlus
+ BroadcastChannelPlus
+ WebSocketPort
+ StarPort
+ RelayPort

#### MessageChannelPlus

`js
new MessageChannelPlus({
handshake?: number,
postAwaitsOpen?: boolean
});
`

| Option | Default | Description |
| ---------------- | ------- | ----------------------------------------------------- |
| handshake | 0 | Conduct a handshake process to coordinate Ready State |
| postAwaitsOpen | false | Queue messages until the port is open |

#### BroadcastChannelPlus

`js
new BroadcastChannelPlus(name, {
handshake?: number,
postAwaitsOpen?: boolean,
clientServerMode?: 'server' | 'client' | null,
autoClose?: boolean
});
`

| Option | Default | Description |
| ------------------ | ------- | --------------------------------------------- |
| handshake | 0 | Conduct a handshake process to coordinate Ready State |
| postAwaitsOpen | false | Queue messages until readiness |
| clientServerMode | null | Can be one of 'server', 'client' or null |
| autoClose | false | Auto-close server when all clients disconnect |

#### WebSocketPort

`js
new WebSocketPort(wsOrUrl, {
handshake?: number,
postAwaitsOpen?: boolean
});
`

| Option | Default | Description |
| ---------------- | ------- | ------------------------------------ |
| handshake | 0 | Conduct a handshake process to coordinate Ready State |
| postAwaitsOpen | false | Queue messages until readiness |

#### StarPort

`js
new StarPort({
handshake?: number,
postAwaitsOpen?: boolean,
autoClose?: boolean
});
`

| Option | Default | Description |
| ---------------- | ------- | ------------------------------------ |
| handshake | 0 | Conduct a handshake process to coordinate Ready State |
| postAwaitsOpen | false | Queue messages until readiness |
| autoClose | false | Auto-close when all clients close or are removed |

#### RelayPort

`js
new RelayPort(channelSpec?, {
handshake?: number,
postAwaitsOpen?: boolean,
autoClose?: boolean
});
`

| Option | Default | Description |
| ---------------- | ------- | ------------------------------------ |
| handshake | 0 | Conduct a handshake process to coordinate Ready State |
| postAwaitsOpen | false | Queue messages until readiness |
| autoClose | false | Auto-close when all clients close or are removed |

$3

* start()
* close()
* readyState
* readyStateChange()

#### start(): void

Explicitly initiates the interaction handshake.

* Required when options.handshake is 2
* Signals readiness to the remote side

#### close(): void

Closes the port.

* Sends a control close signal
* Triggers teardown of dependent ports and projections
* Transitions readyState to closed

#### readyState: 'connecting' | 'open' | 'closed'

Current lifecycle state of the port.

#### readyStateChange(state: 'open' | 'close' | 'messaging'): Promise

Resolves when the port transitions into the specified state.

* 'open': handshake completed
* 'messaging': first outbound message sent
* 'close': port fully closed

> [!TIP]
>
> This is the recommended way to listen for port lifecycle changes compared to using addEventListener('close', ...).
> While a corresponding open and close events are dispatched at the same time as the readyStateChange promise, those events may also be simulated manually via dispatchEvent() or postMessage(). By contrast, readyStateChange is system-managed.
> Code that depends on port lifecycle changes should always rely on readyState or readyStateChange().

$3

+ postMessage()
+ postRequest()
+ addEventListener()
+ addRequestListener()

#### postMessage(data: any, options?): void

Sends a message over the port. options are:

| Option | Type | Description |
| ---------- | ------- | ----------------------------------------- |
| type | string | Message event type (default: 'message') |
| live | boolean | Enable live object projection |
| transfer | Array | Transferable objects |

#### postRequest(data: any, options?): Promise

Sends a request and awaits a response. options are:

| Option | Type | Description |
| --------- | ----------- | ------------------------------------- |
| timeout | number | Reject if no response within duration |
| signal | AbortSignal | Abort the request |

* Rejects automatically if the port closes
* Uses a private ephemeral reply channel internally

#### addEventListener(type: string, handler, options?): void

Registers a handler for a specific message type. options are:

| Option | Type | Description |
| --------- | ----------- | ------------------------------------- |
| once | boolean | Remove listener after first invocation |
| signal | AbortSignal | Abort the request |

Receives MessageEventPlus instances.

#### addRequestListener(type: string, handler, options?): void

Registers a request handler for a specific message type. options are:

| Option | Type | Description |
| --------- | ----------- | ------------------------------------- |
| once | boolean | Remove listener after first invocation |
| signal | AbortSignal | Abort the request |

* Return value (or resolved promise) is sent as the response
* Thrown errors reject the requester

$3

+ channel()
+ relay()

#### channel(name: string): MessagePortPlus

Creates a logical sub-port scoped to a message namespace.

* Filters inbound messages
* Tags outbound messages
* Shares lifecycle with the parent port

#### relay(config): () => void

Establishes explicit routing between ports. config is:

| Config Option | Type | Description |
| ---------------- | --------------- | ------------------------- |
| to | MessagePortPlus | Target port |
| channel | string | object | Channel filter |
| bidirectional | boolean | Relay in both directions |
| resolveMessage | function | Transform message payload |

If channel is specified, it may be a string or a { from, to } mapping. Only messages of the specified channel are relayed. If specified as a from -> to mapping, incoming messages are matched for from and outgoing messages are namespaced with to – effectively a channel mapping.

Returns a cleanup function that removes the relay.

$3

+ projectMutations()

#### projectMutations(options): () => void

Projects mutations between objects across a port. options are:

| Option | Type | Description |
| ------ | --------------- | -------------------------- |
| from | object | string | Source object or shared ID |
| to | string | object | Target ID or local object |

* Must be called on both ends with complementary from / to
* Returns a function that terminates the projection

$3

All message events dispatched by Port+ ports.

#### Properties

| Property | Type | Description |
| ------------- | --- | ------------------------------- |
| data | any | Message payload |
| type | string | Event type |
| eventID | string | Stable message identifier |
| ports | MessagePortPlus[] | Reply ports. |
| live | boolean | Indicates a live object payload |
| relayedFrom | MessagePortPlus | Originating port (if routed) |

#### Methods

| Method | Description |
| --------------- | ------------------------------- |
| respondWith() | Sends a response through attached reply ports. data and options are as is with postMessage. |

#### respondWith(data, options?): boolean

Sends a response through attached reply ports. data and options are as is with postMessage.

Returns true` if one or more reply ports were present.

---

License

MIT.

[npm-version-src]: https://img.shields.io/npm/v/@webqit/port-plus?style=flat&colorA=18181B&colorB=F0DB4F
[npm-version-href]: https://npmjs.com/package/@webqit/port-plus
[bundle-src]: https://img.shields.io/bundlephobia/minzip/@webqit/port-plus?style=flat&colorA=18181B&colorB=F0DB4F
[bundle-href]: https://bundlephobia.com/result?p=@webqit/port-plus
[license-src]: https://img.shields.io/github/license/webqit/port-plus.svg?style=flat&colorA=18181B&colorB=F0DB4F
[license-href]: https://github.com/webqit/port-plus/blob/master/LICENSE