API reference / @chanx-js/client / core / TopicHandle

Class: TopicHandle<ToServer, ToClient>

Defined in: packages/client/src/core/topic.ts:33

A typed view of one topic on a shared connection.

Mirrors chanx's BaseTopicHandle: the topic string travels on the envelope, so several handles multiplex over the single socket their channel opened.

Type Parameters

Type Parameter	Default type
ToServer extends ChanxMessage	ChanxMessage
ToClient extends ChanxMessage	ChanxMessage

Constructors

Constructor

new TopicHandle<ToServer, ToClient>(
   host, 
   ref, 
   validate
): TopicHandle<ToServer, ToClient>;

Defined in: packages/client/src/core/topic.ts:83

Parameters

Parameter	Type
host	TopicHost
ref	TopicRef<ToServer, ToClient, string>
validate	{ inbound: boolean; outbound: boolean; }
validate.inbound	boolean
validate.outbound	boolean

Returns

TopicHandle<ToServer, ToClient>

Properties

topic

readonly topic: string;

Defined in: packages/client/src/core/topic.ts:37

Accessors

subscribed

Get Signature

get subscribed(): boolean;

Defined in: packages/client/src/core/topic.ts:54

Whether the server has confirmed this subscription on the current socket and it has not since been dropped by unsubscribe, release, or the socket being terminated.

Returns

boolean

Set Signature

set subscribed(value): void;

Defined in: packages/client/src/core/topic.ts:58

Parameters

Parameter	Type
value	boolean

Returns

void

Methods

[asyncIterator]()

asyncIterator: AsyncIterableIterator<ToClient>;

Defined in: packages/client/src/core/topic.ts:191

Returns

AsyncIterableIterator<ToClient>

---

clearHandlers()

clearHandlers(): void;

Defined in: packages/client/src/core/topic.ts:205

Internal

Called by the connection once the last consumer has released.

Returns

void

---

dispatch()

dispatch(frame): void;

Defined in: packages/client/src/core/topic.ts:218

Internal

Parameters

Parameter	Type
frame	RawFrame

Returns

void

---

endStreams()

endStreams(): void;

Defined in: packages/client/src/core/topic.ts:213

Internal

End open streams, so no for await waits on a topic that is gone.

Returns

void

---

on()

on<A>(action, handler): () => void;

Defined in: packages/client/src/core/topic.ts:157

envelope.seq orders a topic's events, e.g. a replay overlapping live ones.

Type Parameters

Type Parameter
A extends string

Parameters

Parameter	Type
action	A
handler	(message, envelope) => void

Returns

() => void

---

onAny()

onAny(handler): () => void;

Defined in: packages/client/src/core/topic.ts:164

Parameters

Parameter	Type
handler	(message, envelope) => void

Returns

() => void

---

once()

once<A>(action, options?): Promise<Extract<ToClient, {
  action: A;
}>>;

Defined in: packages/client/src/core/topic.ts:173

Resolve with the next message on this topic carrying this action.

Type Parameters

Type Parameter
A extends string

Parameters

Parameter	Type
action	A
options	{ signal?: AbortSignal; timeout?: number; }
options.signal?	AbortSignal
options.timeout?	number

Returns

Promise<Extract<ToClient, { action: A; }>>

---

onSubscribedChange()

onSubscribedChange(listener): () => void;

Defined in: packages/client/src/core/topic.ts:65

Follow subscribed as it changes, so view state cannot drift from it.

Parameters

Parameter	Type
listener	(subscribed) => void

Returns

() => void

---

onSubscribeError()

onSubscribeError(listener): () => void;

Defined in: packages/client/src/core/topic.ts:74

Every failed subscribe, including the automatic resubscribe after a reconnect, which has no caller to reject.

Parameters

Parameter	Type
listener	(error) => void

Returns

() => void

---

onUnhandled()

onUnhandled(handler): () => void;

Defined in: packages/client/src/core/topic.ts:168

Parameters

Parameter	Type
handler	(message, envelope) => void

Returns

() => void

---

release()

release(): void;

Defined in: packages/client/src/core/topic.ts:200

Drop one consumer's claim. Handlers registered through on() are torn down by the disposer it returned, not here: this handle may still be serving other consumers. Each connection.topic() call must be matched by exactly one release().

Returns

void

---

request()

request(message, options?): Promise<ChanxMessage>;

Defined in: packages/client/src/core/topic.ts:151

Send and wait for the frame carrying the same ref.

Parameters

Parameter	Type
message	ToServer
options	TopicRequestOptions

Returns

Promise<ChanxMessage>

---

send()

send(message): void;

Defined in: packages/client/src/core/topic.ts:145

Parameters

Parameter	Type
message	ToServer

Returns

void

---

stream()

stream(options?): MessageStream<ToClient>;

Defined in: packages/client/src/core/topic.ts:187

Iterate this topic's messages with for await. Ends when the last consumer releases the topic, the connection closes, or the socket is terminated.

Parameters

Parameter	Type
options	StreamOptions

Returns

MessageStream<ToClient>

---

subscribe()

subscribe(options?): Promise<ChanxMessage>;

Defined in: packages/client/src/core/topic.ts:96

Parameters

Parameter	Type
options	SubscribeOptions

Returns

Promise<ChanxMessage>

---

unsubscribe()

unsubscribe(options?): Promise<ChanxMessage>;

Defined in: packages/client/src/core/topic.ts:131

Stop receiving this topic on this handle.

Other consumers of the same socket are unaffected: the server is only told to unsubscribe once no handle on the socket still holds the topic. Within one connection, topic() hands every caller the same handle, so this stops it for all of them; use release() to drop just one caller's claim.

Parameters

Parameter	Type
options	SubscribeOptions

Returns

Promise<ChanxMessage>