Subscriptions and component lifecycle

Baseline: IOSignal JS 7.2.0. See client API for the full method and event overview.

Manual or automatic subscriptions

Style	Best for	On connection/reconnection
subscribe() + on()	Dynamic subscriptions and precise send order	App subscribes in each ready handler
listen(tag, handler)	Declaring known tags during initialization	Library subscribes using its saved .channels list

Manual: subscribe before sending

const io = new IO();
const tag = 'channel1';
io.on('message', (receivedTag, ...args) => {
  console.log(receivedTag, ...args);
});
io.on('ready', () => {
  io.subscribe(tag);
  io.signal(tag, io.cid + ' is ready.');
});
io.open('ws://localhost:7777');

Register the handler once and subscribe on each ready. subscribe(tag) does not accept a handler and does not itself add the tag to the automatic .channels list.

Automatic: declare a tag and handler

const io = new IO();
io.listen('channel1', (tag, ...args) => {
  console.log(tag, ...args);
});
io.open('ws://localhost:7777');

For ordinary tags, listen() saves the tag and registers the handler. The library subscribes after obtaining a CID, and resubscribes after reconnecting.

Register before the first ready processing. Calling listen() does not immediately send a subscription packet. To add a new subscription while already ready, register a handler and call subscribe(tag).

Automatic subscriptions are sent after the ready event handlers run. Immediate publishing inside a ready handler can therefore precede an automatic subscription. Use the manual style when order matters.

unsubscribe(tag) removes the server subscription and its saved tag. Direct listeners use on() or listen() with @/@topic, require no subscription, and can be registered any time before the message arrives. Remove a direct listener with off('@topic', handler). Direct subscribe()/unsubscribe() calls throw TypeError, including comma lists containing a direct tag. A@topic remains a valid CID-publication subscription.

Component ownership

link(component, tag, handler) takes a local component identifier, not a server address or recipient CID. Remove linked handlers with unlink(component, tag) or unlinkAll(component). Other components using the same function or tag keep their handlers.

io.link('offer-panel', '@offer', (tag, message) => {
  console.log(tag, message);
});
// When the component is removed:
io.unlinkAll('offer-panel');

Direct @/@topic links only manage local listeners. Ordinary channel and CID-publication links also manage subscriptions and reconnection subscriptions.

Unlinking one component does not unsubscribe a tag still owned by another link, a listen() registration, or an explicit subscription. Removing the last link releases a subscription owned only by links. Explicit subscribe() ownership belongs to the current connection; automatic reconnection follows saved listen/link registrations.

Destroy an IO instance only when the departing component owns it exclusively.