Class: Subscription<T>
Defined in: src/channel/ws/subscription.ts:63
Represents an active WebSocket subscription.
This class should not be instantiated directly. It is returned by the
subscribe methods on the WebSocketChannel.
Example
const channel = new WebSocketChannel({ nodeUrl: 'YOUR_NODE_URL' });
await channel.waitForConnection();
// The 'sub' object is an instance of the Subscription class.
const sub = await channel.subscribeNewHeads();
sub.on((data) => {
console.log('Received new head:', data);
});
// ... later
await sub.unsubscribe();
Type Parameters
T
T = any
The type of data expected from the subscription event.
Constructors
Constructor
new Subscription<
T>(options):Subscription<T>
Defined in: src/channel/ws/subscription.ts:105
Internal
Parameters
options
Subscription configuration options
Returns
Subscription<T>
Properties
channel
channel:
SubscriptionOwner
Defined in: src/channel/ws/subscription.ts:68
Internal
The channel that created this subscription.
method
method:
string
Defined in: src/channel/ws/subscription.ts:74
Internal
The JSON-RPC method used to create this subscription.
params
params:
any
Defined in: src/channel/ws/subscription.ts:80
Internal
The parameters used to create this subscription.
id
id:
string
Defined in: src/channel/ws/subscription.ts:86
Internal
The unique identifier for this subscription.
Accessors
isClosed
Get Signature
get isClosed():
boolean
Defined in: src/channel/ws/subscription.ts:117
Indicates if the subscription has been closed.
Returns
boolean
true if unsubscribed, false otherwise.
Methods
onClose()
onClose(
listener): () =>void
Defined in: src/channel/ws/subscription.ts:132
Registers a listener for this subscription's closure, whatever causes it: an explicit
unsubscribe(), or the channel giving up on re-establishing it after a reconnection.
The second case is the reason this exists. A subscription killed by a refused restore stops
delivering while the connection stays up, so the transport's statechange says nothing about
it and a consumer would wait forever on events that can no longer come.
Parameters
listener
() => void
Called once, when the subscription closes.
Returns
the detach function, so the pair matches useSyncExternalStore's subscribe contract.
() => void
_markClosed()
_markClosed():
void
Defined in: src/channel/ws/subscription.ts:153
Internal
Closes the subscription locally, without contacting the node.
Used when the channel knows the subscription is gone and cannot be recovered — a re-subscribe refused after a reconnection, for instance. Without it the object would keep reporting itself as open while no event could ever reach its handler again.
Returns
void
_handleEvent()
_handleEvent(
data):void
Defined in: src/channel/ws/subscription.ts:169
Internal
Internal method to handle incoming events from the WebSocket channel. If a handler is attached, it's invoked immediately. Otherwise, the event is buffered.
Parameters
data
T
The event data.
Returns
void
on()
on(
handler):void
Defined in: src/channel/ws/subscription.ts:194
Attaches a handler function to be called for each event.
When a handler is attached, any buffered events will be passed to it sequentially. Subsequent events will be passed directly as they arrive.
Re-attaching the same handler is a no-op: React StrictMode invokes an effect twice, and throwing there would fail a correct component. A different handler while one is attached is still refused — that is a genuine mistake, not a lifecycle artefact.
Parameters
handler
(data) => void
The function to call with event data.
Returns
void
Throws
If a different handler is already attached to this subscription.
off()
off():
void
Defined in: src/channel/ws/subscription.ts:223
Detaches the current handler.
Events arriving afterwards are buffered again, so a later on() receives them: the
subscription itself is untouched, only the delivery is paused. This is what a React effect
cleanup needs — dropping the handler without tearing down a subscription the component may
re-attach to on its next mount.
Returns
void
unsubscribe()
unsubscribe():
Promise<boolean>
Defined in: src/channel/ws/subscription.ts:231
Sends an unsubscribe request to the node and cleans up local resources.
Returns
Promise<boolean>
A Promise that resolves to true if the unsubscription was successful.