iosignal 7.1.0 → 7.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,7 +17,7 @@ var fs = require('fs');
17
17
  var process$1 = require('process');
18
18
  var path = require('path');
19
19
 
20
- var version$1 = "7.1.0";
20
+ var version$1 = "7.2.0";
21
21
  var pkg = {
22
22
  version: version$1};
23
23
 
@@ -785,6 +785,22 @@ function encodeTag(tag, allowEmpty = true) {
785
785
  return encoded
786
786
  }
787
787
 
788
+ // Direct-receive tags are local event names, never server subscriptions.
789
+ function encodeSubscriptionTags(tag) {
790
+ const encoded = encodeTag(tag);
791
+ if (tag.split(',').some(part => part.startsWith('@'))) {
792
+ throw TypeError("direct signal tags need no subscription; use on/listen/link and off/unlink")
793
+ }
794
+ return encoded
795
+ }
796
+
797
+ function sendSubscription(io, tag) {
798
+ const encoded = encodeSubscriptionTags(tag);
799
+ io.send_enc_mode(Buffer$1.concat([
800
+ $$1.NB('8', IOMsg.SUBSCRIBE), $$1.NB('8', encoded.byteLength), encoded
801
+ ]));
802
+ }
803
+
788
804
  function byteToUrl(buffer) {
789
805
  //ipv4(4bytes) , port(2bytes)
790
806
  if (buffer.byteLength != 6) return
@@ -943,6 +959,12 @@ class IOCore extends EventEmitter {
943
959
  * @type {Map<string, Set<string>>}
944
960
  */
945
961
  this.linkMap = new Map();
962
+ /** @private @type {Map<string, Map<string, Set<Function>>>} */
963
+ this._linkHandlers = new Map();
964
+ /** @private @type {Set<string>} */
965
+ this._listenTags = new Set();
966
+ /** @private @type {Set<string>} */
967
+ this._manualSubscriptions = new Set();
946
968
 
947
969
  /**
948
970
  * Indicates if auto-reconnect is enabled.
@@ -1008,6 +1030,7 @@ class IOCore extends EventEmitter {
1008
1030
  reject(error);
1009
1031
  }
1010
1032
  this.promiseMap.clear();
1033
+ this._manualSubscriptions.clear();
1011
1034
  this.cid = '';
1012
1035
  if (this.boho) this.boho.isAuthorized = false;
1013
1036
  if (this.state !== STATE.STOP && this.stateChange('closed')) {
@@ -1036,6 +1059,9 @@ class IOCore extends EventEmitter {
1036
1059
 
1037
1060
  this.channels.clear();
1038
1061
  this.linkMap.clear();
1062
+ this._linkHandlers.clear();
1063
+ this._listenTags.clear();
1064
+ this._manualSubscriptions.clear();
1039
1065
 
1040
1066
  // Help GC
1041
1067
  this.boho = null;
@@ -1329,8 +1355,10 @@ class IOCore extends EventEmitter {
1329
1355
  switch (payloadType) {
1330
1356
 
1331
1357
  case PAYLOAD_TYPE.EMPTY:
1332
- if (tag.indexOf('@') === 0) this.emit('@', tag);
1333
- else {
1358
+ if (tag.indexOf('@') === 0) {
1359
+ this.emit('@', tag);
1360
+ if (tag !== '@') this.emit(tag, tag);
1361
+ } else {
1334
1362
  this.emit(tag, tag);
1335
1363
  this.emit('message', tag);
1336
1364
  }
@@ -1344,16 +1372,20 @@ class IOCore extends EventEmitter {
1344
1372
  payloadStringWithoutNull = payloadBuffer.subarray(0, payloadBuffer.byteLength - 1);
1345
1373
  }
1346
1374
  let oneString = decoder$4.decode(payloadStringWithoutNull);
1347
- if (tag.indexOf('@') === 0) this.emit('@', tag, oneString);
1348
- else {
1375
+ if (tag.indexOf('@') === 0) {
1376
+ this.emit('@', tag, oneString);
1377
+ if (tag !== '@') this.emit(tag, tag, oneString);
1378
+ } else {
1349
1379
  this.emit(tag, tag, oneString);
1350
1380
  this.emit('message', tag, oneString);
1351
1381
  }
1352
1382
  break;
1353
1383
 
1354
1384
  case PAYLOAD_TYPE.BINARY:
1355
- if (tag.indexOf('@') === 0) this.emit('@', tag, payloadBuffer);
1356
- else {
1385
+ if (tag.indexOf('@') === 0) {
1386
+ this.emit('@', tag, payloadBuffer);
1387
+ if (tag !== '@') this.emit(tag, tag, payloadBuffer);
1388
+ } else {
1357
1389
  this.emit(tag, tag, payloadBuffer);
1358
1390
  this.emit('message', tag, payloadBuffer);
1359
1391
  }
@@ -1362,8 +1394,10 @@ class IOCore extends EventEmitter {
1362
1394
  case PAYLOAD_TYPE.OBJECT:
1363
1395
  let oneObjectBuffer = decoder$4.decode(payloadBuffer);
1364
1396
  let oneJSONObject = JSON.parse(oneObjectBuffer);
1365
- if (tag.indexOf('@') === 0) this.emit('@', tag, oneJSONObject);
1366
- else {
1397
+ if (tag.indexOf('@') === 0) {
1398
+ this.emit('@', tag, oneJSONObject);
1399
+ if (tag !== '@') this.emit(tag, tag, oneJSONObject);
1400
+ } else {
1367
1401
  this.emit(tag, tag, oneJSONObject);
1368
1402
  this.emit('message', tag, oneJSONObject);
1369
1403
  }
@@ -1372,8 +1406,10 @@ class IOCore extends EventEmitter {
1372
1406
  case PAYLOAD_TYPE.MJSON:
1373
1407
  let mjsonBuffer = decoder$4.decode(payloadBuffer);
1374
1408
  let mjson = JSON.parse(mjsonBuffer);
1375
- if (tag.indexOf('@') === 0) this.emit('@', tag, ...mjson);
1376
- else {
1409
+ if (tag.indexOf('@') === 0) {
1410
+ this.emit('@', tag, ...mjson);
1411
+ if (tag !== '@') this.emit(tag, tag, ...mjson);
1412
+ } else {
1377
1413
  this.emit(tag, tag, ...mjson);
1378
1414
  this.emit('message', tag, ...mjson);
1379
1415
  }
@@ -1381,8 +1417,10 @@ class IOCore extends EventEmitter {
1381
1417
 
1382
1418
  case PAYLOAD_TYPE.MBA:
1383
1419
  let mbaObject = $$1.unpack(payloadBuffer);
1384
- if (tag.indexOf('@') === 0) this.emit('@', tag, ...mbaObject.args);
1385
- else {
1420
+ if (tag.indexOf('@') === 0) {
1421
+ this.emit('@', tag, ...mbaObject.args);
1422
+ if (tag !== '@') this.emit(tag, tag, ...mbaObject.args);
1423
+ } else {
1386
1424
  this.emit(tag, tag, ...mbaObject.args);
1387
1425
  this.emit('message', tag, ...mbaObject.args);
1388
1426
  }
@@ -1727,14 +1765,11 @@ class IOCore extends EventEmitter {
1727
1765
  /**
1728
1766
  * Subscribes to a channel or channels.
1729
1767
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
1730
- * @throws {TypeError} If tag is not a string or exceeds length limit.
1768
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
1731
1769
  */
1732
1770
  subscribe(tag) {
1733
- const tagEncoded = encodeTag(tag);
1734
- this.send_enc_mode(Buffer$1.concat([
1735
- $$1.NB('8', IOMsg.SUBSCRIBE),
1736
- $$1.NB('8', tagEncoded.byteLength),
1737
- tagEncoded]));
1771
+ sendSubscription(this, tag);
1772
+ for (const part of tag.split(',')) this._manualSubscriptions.add(part);
1738
1773
  }
1739
1774
 
1740
1775
 
@@ -1747,7 +1782,7 @@ class IOCore extends EventEmitter {
1747
1782
  // Validate the entire list first, then split only at tag boundaries.
1748
1783
  // Preserve comma-separated entries accepted by existing registration APIs.
1749
1784
  const tags = Array.from(this.channels).join(',').split(',');
1750
- const sizes = tags.map(tag => encodeTag(tag).byteLength);
1785
+ const sizes = tags.map(tag => encodeSubscriptionTags(tag).byteLength);
1751
1786
  const batches = [];
1752
1787
  let batch = [], bytes = 0;
1753
1788
  tags.forEach((tag, i) => {
@@ -1760,23 +1795,27 @@ class IOCore extends EventEmitter {
1760
1795
  batch.push(tag);
1761
1796
  });
1762
1797
  if (batch.length) batches.push(batch.join(','));
1763
- batches.forEach(tag => this.subscribe(tag));
1798
+ batches.forEach(tag => sendSubscription(this, tag));
1764
1799
  }
1765
1800
 
1766
1801
  /**
1767
1802
  * Unsubscribes from a channel or channels.
1768
1803
  * @param {string} [tag=""] - The tag(s) of the channel(s) to unsubscribe from (comma-separated). If empty, unsubscribes from all.
1769
- * @throws {TypeError} If tag is not a string or exceeds length limit.
1804
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
1770
1805
  */
1771
1806
  unsubscribe(tag = "") {
1772
- const tagEncoded = encodeTag(tag);
1807
+ const tagEncoded = encodeSubscriptionTags(tag);
1773
1808
 
1774
1809
  if (tag == "") { // blank tag means unsubscribe all
1775
1810
  this.channels.clear();
1811
+ this._listenTags.clear();
1812
+ this._manualSubscriptions.clear();
1776
1813
  } else {
1777
1814
  let tagList = tag.split(',');
1778
1815
  tagList.forEach(tag => {
1779
1816
  this.channels.delete(tag);
1817
+ this._listenTags.delete(tag);
1818
+ this._manualSubscriptions.delete(tag);
1780
1819
  });
1781
1820
  }
1782
1821
 
@@ -1790,12 +1829,17 @@ class IOCore extends EventEmitter {
1790
1829
 
1791
1830
  /**
1792
1831
  * Convenience API for simple clients (for example, CLI tools): register a
1793
- * tag handler once and remember its subscription in channels. Register before
1794
- * connection readiness; the CID-ready flow subscribes on initial connection
1832
+ * tag handler once and remember its subscription in channels. For subscription
1833
+ * tags, register before connection readiness; the CID-ready flow subscribes on initial connection
1795
1834
  * and again after reconnect, without application-level ready/subscribe code.
1796
1835
  * This does not send a subscription immediately, even if already ready.
1797
1836
  * For precise subscription/send ordering or dynamic subscriptions, use
1798
- * on() with subscribe() in a ready handler instead. Direct signals use on('@').
1837
+ * on() with subscribe() in a ready handler instead.
1838
+ * Direct signals need no subscription: use on/listen('@') for all direct
1839
+ * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
1840
+ * registered before or after readiness, before the message arrives.
1841
+ * Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
1842
+ * Returning false does not cancel dispatch; a thrown error interrupts it.
1799
1843
  * @param {string} tag - The tag to listen on.
1800
1844
  * @param {Function} handler - The callback function to handle the signal.
1801
1845
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
@@ -1806,7 +1850,9 @@ class IOCore extends EventEmitter {
1806
1850
  if (typeof handler !== 'function') throw TypeError('handler is not a function.')
1807
1851
 
1808
1852
  if (tag.indexOf('@') !== 0) {
1853
+ encodeSubscriptionTags(tag);
1809
1854
  this.channels.add(tag);
1855
+ this._listenTags.add(tag);
1810
1856
  }
1811
1857
  this.on(tag, handler);
1812
1858
  // Subscribe from the CID-ready flow, initially and after reconnect.
@@ -1817,81 +1863,82 @@ class IOCore extends EventEmitter {
1817
1863
 
1818
1864
 
1819
1865
  /**
1820
- * Links a local target to a remote tag and sets up a handler.
1821
- * @param {string} to - The local link target.
1822
- * @param {string} tag - The remote tag.
1823
- * @param {Function} handler - The callback function to handle the signal.
1824
- * @throws {TypeError} If 'to' or 'tag' are not strings, handler is not a function, or tag length is invalid.
1866
+ * Associates handlers with a local component for scoped teardown.
1867
+ * Direct tags (@ or @topic) only register local handlers. Other tags also
1868
+ * subscribe now and are remembered for reconnection.
1869
+ * @param {string} to - The local component identifier, not a server target.
1870
+ * @param {string} tag - The exact event tag.
1871
+ * @param {Function} handler - The callback receiving (tag, ...args).
1872
+ * @throws {TypeError} If the arguments or subscription tags are invalid.
1825
1873
  */
1826
1874
  link(to, tag, handler) {
1827
1875
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1828
- if (typeof tag !== 'string') throw TypeError('tag is not a string.')
1829
1876
  encodeTag(tag, false);
1830
1877
  if (typeof handler !== 'function') throw TypeError('handler is not a function.')
1831
-
1832
- if (tag.indexOf('@') !== 0) {
1878
+ const direct = tag.startsWith('@');
1879
+ if (!direct) encodeSubscriptionTags(tag);
1880
+
1881
+ let tags = this._linkHandlers.get(to);
1882
+ if (!tags) this._linkHandlers.set(to, tags = new Map());
1883
+ let handlers = tags.get(tag);
1884
+ if (!handlers) tags.set(tag, handlers = new Set());
1885
+ // Each registration owns its wrapper, even if components share a callback.
1886
+ const linkedHandler = (...args) => handler.apply(this, args);
1887
+ handlers.add(linkedHandler);
1888
+ let linkSet = this.linkMap.get(to);
1889
+ if (!linkSet) this.linkMap.set(to, linkSet = new Set());
1890
+ linkSet.add(tag);
1891
+ this.on(tag, linkedHandler);
1892
+ if (!direct) {
1833
1893
  this.channels.add(tag);
1894
+ sendSubscription(this, tag);
1834
1895
  }
1835
-
1836
- let linkSet;
1837
- if (this.linkMap.has(to)) {
1838
- linkSet = this.linkMap.get(to);
1839
- } else {
1840
- linkSet = new Set();
1841
- }
1842
-
1843
- linkSet.add(tag);
1844
- this.linkMap.set(to, linkSet);
1845
- this.on(tag, handler);
1846
- this.subscribe(tag);
1847
-
1848
1896
  }
1849
1897
 
1850
-
1851
1898
  /**
1852
- * Unlinks a specific tag from a local target.
1853
- * @param {string} to - The local link target.
1854
- * @param {string} tag - The tag to unlink.
1855
- * @throws {TypeError} If 'to' or 'tag' are not strings or tag length is invalid.
1899
+ * Removes only one local component's handlers for a tag. Direct tags never
1900
+ * send an unsubscribe. Shared subscriptions and explicit subscriptions remain.
1901
+ * @param {string} to - The local component identifier.
1902
+ * @param {string} tag - The exact linked tag.
1903
+ * @throws {TypeError} If the arguments are invalid.
1856
1904
  */
1857
1905
  unlink(to, tag) {
1858
1906
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1859
- if (typeof tag !== 'string') throw TypeError('tag is not a string.')
1860
1907
  encodeTag(tag, false);
1861
-
1908
+ const tags = this._linkHandlers.get(to);
1909
+ const handlers = tags?.get(tag);
1910
+ if (!handlers) return
1911
+ for (const handler of handlers) this.removeListener(tag, handler);
1912
+ tags.delete(tag);
1862
1913
  const linkSet = this.linkMap.get(to);
1863
- if (!linkSet || !linkSet.has(tag)) return;
1864
-
1865
- this.unsubscribe(tag);
1866
- this.removeAllListeners(tag);
1867
1914
  linkSet.delete(tag);
1868
-
1869
- if (linkSet.size === 0) {
1915
+ if (tags.size === 0) {
1916
+ this._linkHandlers.delete(to);
1870
1917
  this.linkMap.delete(to);
1871
1918
  }
1919
+ if (tag.startsWith('@')) return
1920
+
1921
+ const linkedElsewhere = [...this._linkHandlers.values()].some(other => other.has(tag));
1922
+ if (!linkedElsewhere && !this._listenTags.has(tag)) this.channels.delete(tag);
1923
+ const remembered = new Set([...this.channels].flatMap(entry => entry.split(',')));
1924
+ const unused = tag.split(',').filter(part =>
1925
+ !remembered.has(part) && !this._manualSubscriptions.has(part));
1926
+ if (unused.length) this.unsubscribe(unused.join(','));
1872
1927
  }
1873
1928
 
1874
1929
  /**
1875
- * Unlinks all tags from a local target.
1876
- * @param {string} to - The local link target.
1877
- * @throws {TypeError} If 'to' is not a string.
1930
+ * Removes this local component's links without removing other listeners.
1931
+ * @param {string} to - The local component identifier.
1932
+ * @throws {TypeError} If the component identifier is not a string.
1878
1933
  */
1879
1934
  unlinkAll(to) {
1880
1935
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1881
-
1882
- const linkSet = this.linkMap.get(to);
1883
- if (!linkSet) return;
1884
-
1885
- for (const tag of linkSet) {
1886
- this.unsubscribe(tag);
1887
- this.removeAllListeners(tag);
1888
- }
1889
-
1890
- this.linkMap.delete(to);
1936
+ const tags = this._linkHandlers.get(to);
1937
+ if (!tags) return
1938
+ for (const tag of [...tags.keys()]) this.unlink(to, tag);
1891
1939
  }
1892
1940
 
1893
1941
 
1894
-
1895
1942
  /**
1896
1943
  * Gets connection metrics.
1897
1944
  * @returns {{tx: number, rx: number, txb: number, rxb: number, last: number}}
@@ -302,6 +302,12 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
302
302
  * @type {Map<string, Set<string>>}
303
303
  */
304
304
  linkMap: Map<string, Set<string>>;
305
+ /** @private @type {Map<string, Map<string, Set<Function>>>} */
306
+ private _linkHandlers;
307
+ /** @private @type {Set<string>} */
308
+ private _listenTags;
309
+ /** @private @type {Set<string>} */
310
+ private _manualSubscriptions;
305
311
  /**
306
312
  * Indicates if auto-reconnect is enabled.
307
313
  * @type {boolean}
@@ -479,7 +485,7 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
479
485
  /**
480
486
  * Subscribes to a channel or channels.
481
487
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
482
- * @throws {TypeError} If tag is not a string or exceeds length limit.
488
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
483
489
  */
484
490
  subscribe(tag: string): void;
485
491
  /**
@@ -490,41 +496,49 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
490
496
  /**
491
497
  * Unsubscribes from a channel or channels.
492
498
  * @param {string} [tag=""] - The tag(s) of the channel(s) to unsubscribe from (comma-separated). If empty, unsubscribes from all.
493
- * @throws {TypeError} If tag is not a string or exceeds length limit.
499
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
494
500
  */
495
501
  unsubscribe(tag?: string): void;
496
502
  /**
497
503
  * Convenience API for simple clients (for example, CLI tools): register a
498
- * tag handler once and remember its subscription in channels. Register before
499
- * connection readiness; the CID-ready flow subscribes on initial connection
504
+ * tag handler once and remember its subscription in channels. For subscription
505
+ * tags, register before connection readiness; the CID-ready flow subscribes on initial connection
500
506
  * and again after reconnect, without application-level ready/subscribe code.
501
507
  * This does not send a subscription immediately, even if already ready.
502
508
  * For precise subscription/send ordering or dynamic subscriptions, use
503
- * on() with subscribe() in a ready handler instead. Direct signals use on('@').
509
+ * on() with subscribe() in a ready handler instead.
510
+ * Direct signals need no subscription: use on/listen('@') for all direct
511
+ * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
512
+ * registered before or after readiness, before the message arrives.
513
+ * Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
514
+ * Returning false does not cancel dispatch; a thrown error interrupts it.
504
515
  * @param {string} tag - The tag to listen on.
505
516
  * @param {Function} handler - The callback function to handle the signal.
506
517
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
507
518
  */
508
519
  listen(tag: string, handler: Function): void;
509
520
  /**
510
- * Links a local target to a remote tag and sets up a handler.
511
- * @param {string} to - The local link target.
512
- * @param {string} tag - The remote tag.
513
- * @param {Function} handler - The callback function to handle the signal.
514
- * @throws {TypeError} If 'to' or 'tag' are not strings, handler is not a function, or tag length is invalid.
521
+ * Associates handlers with a local component for scoped teardown.
522
+ * Direct tags (@ or @topic) only register local handlers. Other tags also
523
+ * subscribe now and are remembered for reconnection.
524
+ * @param {string} to - The local component identifier, not a server target.
525
+ * @param {string} tag - The exact event tag.
526
+ * @param {Function} handler - The callback receiving (tag, ...args).
527
+ * @throws {TypeError} If the arguments or subscription tags are invalid.
515
528
  */
516
529
  link(to: string, tag: string, handler: Function): void;
517
530
  /**
518
- * Unlinks a specific tag from a local target.
519
- * @param {string} to - The local link target.
520
- * @param {string} tag - The tag to unlink.
521
- * @throws {TypeError} If 'to' or 'tag' are not strings or tag length is invalid.
531
+ * Removes only one local component's handlers for a tag. Direct tags never
532
+ * send an unsubscribe. Shared subscriptions and explicit subscriptions remain.
533
+ * @param {string} to - The local component identifier.
534
+ * @param {string} tag - The exact linked tag.
535
+ * @throws {TypeError} If the arguments are invalid.
522
536
  */
523
537
  unlink(to: string, tag: string): void;
524
538
  /**
525
- * Unlinks all tags from a local target.
526
- * @param {string} to - The local link target.
527
- * @throws {TypeError} If 'to' is not a string.
539
+ * Removes this local component's links without removing other listeners.
540
+ * @param {string} to - The local component identifier.
541
+ * @throws {TypeError} If the component identifier is not a string.
528
542
  */
529
543
  unlinkAll(to: string): void;
530
544
  /**
@@ -302,6 +302,12 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
302
302
  * @type {Map<string, Set<string>>}
303
303
  */
304
304
  linkMap: Map<string, Set<string>>;
305
+ /** @private @type {Map<string, Map<string, Set<Function>>>} */
306
+ private _linkHandlers;
307
+ /** @private @type {Set<string>} */
308
+ private _listenTags;
309
+ /** @private @type {Set<string>} */
310
+ private _manualSubscriptions;
305
311
  /**
306
312
  * Indicates if auto-reconnect is enabled.
307
313
  * @type {boolean}
@@ -479,7 +485,7 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
479
485
  /**
480
486
  * Subscribes to a channel or channels.
481
487
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
482
- * @throws {TypeError} If tag is not a string or exceeds length limit.
488
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
483
489
  */
484
490
  subscribe(tag: string): void;
485
491
  /**
@@ -490,41 +496,49 @@ declare class IOCore extends EventEmitter<string | symbol, any> {
490
496
  /**
491
497
  * Unsubscribes from a channel or channels.
492
498
  * @param {string} [tag=""] - The tag(s) of the channel(s) to unsubscribe from (comma-separated). If empty, unsubscribes from all.
493
- * @throws {TypeError} If tag is not a string or exceeds length limit.
499
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
494
500
  */
495
501
  unsubscribe(tag?: string): void;
496
502
  /**
497
503
  * Convenience API for simple clients (for example, CLI tools): register a
498
- * tag handler once and remember its subscription in channels. Register before
499
- * connection readiness; the CID-ready flow subscribes on initial connection
504
+ * tag handler once and remember its subscription in channels. For subscription
505
+ * tags, register before connection readiness; the CID-ready flow subscribes on initial connection
500
506
  * and again after reconnect, without application-level ready/subscribe code.
501
507
  * This does not send a subscription immediately, even if already ready.
502
508
  * For precise subscription/send ordering or dynamic subscriptions, use
503
- * on() with subscribe() in a ready handler instead. Direct signals use on('@').
509
+ * on() with subscribe() in a ready handler instead.
510
+ * Direct signals need no subscription: use on/listen('@') for all direct
511
+ * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
512
+ * registered before or after readiness, before the message arrives.
513
+ * Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
514
+ * Returning false does not cancel dispatch; a thrown error interrupts it.
504
515
  * @param {string} tag - The tag to listen on.
505
516
  * @param {Function} handler - The callback function to handle the signal.
506
517
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
507
518
  */
508
519
  listen(tag: string, handler: Function): void;
509
520
  /**
510
- * Links a local target to a remote tag and sets up a handler.
511
- * @param {string} to - The local link target.
512
- * @param {string} tag - The remote tag.
513
- * @param {Function} handler - The callback function to handle the signal.
514
- * @throws {TypeError} If 'to' or 'tag' are not strings, handler is not a function, or tag length is invalid.
521
+ * Associates handlers with a local component for scoped teardown.
522
+ * Direct tags (@ or @topic) only register local handlers. Other tags also
523
+ * subscribe now and are remembered for reconnection.
524
+ * @param {string} to - The local component identifier, not a server target.
525
+ * @param {string} tag - The exact event tag.
526
+ * @param {Function} handler - The callback receiving (tag, ...args).
527
+ * @throws {TypeError} If the arguments or subscription tags are invalid.
515
528
  */
516
529
  link(to: string, tag: string, handler: Function): void;
517
530
  /**
518
- * Unlinks a specific tag from a local target.
519
- * @param {string} to - The local link target.
520
- * @param {string} tag - The tag to unlink.
521
- * @throws {TypeError} If 'to' or 'tag' are not strings or tag length is invalid.
531
+ * Removes only one local component's handlers for a tag. Direct tags never
532
+ * send an unsubscribe. Shared subscriptions and explicit subscriptions remain.
533
+ * @param {string} to - The local component identifier.
534
+ * @param {string} tag - The exact linked tag.
535
+ * @throws {TypeError} If the arguments are invalid.
522
536
  */
523
537
  unlink(to: string, tag: string): void;
524
538
  /**
525
- * Unlinks all tags from a local target.
526
- * @param {string} to - The local link target.
527
- * @throws {TypeError} If 'to' is not a string.
539
+ * Removes this local component's links without removing other listeners.
540
+ * @param {string} to - The local component identifier.
541
+ * @throws {TypeError} If the component identifier is not a string.
528
542
  */
529
543
  unlinkAll(to: string): void;
530
544
  /**