iosignal 7.0.4 → 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.0.4";
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;
@@ -1205,6 +1231,7 @@ class IOCore extends EventEmitter {
1205
1231
  break;
1206
1232
 
1207
1233
  case IOMsg.PONG:
1234
+ this.emit('pong');
1208
1235
  break;
1209
1236
 
1210
1237
  case IOMsg.ECHO:
@@ -1328,8 +1355,10 @@ class IOCore extends EventEmitter {
1328
1355
  switch (payloadType) {
1329
1356
 
1330
1357
  case PAYLOAD_TYPE.EMPTY:
1331
- if (tag.indexOf('@') === 0) this.emit('@', tag);
1332
- else {
1358
+ if (tag.indexOf('@') === 0) {
1359
+ this.emit('@', tag);
1360
+ if (tag !== '@') this.emit(tag, tag);
1361
+ } else {
1333
1362
  this.emit(tag, tag);
1334
1363
  this.emit('message', tag);
1335
1364
  }
@@ -1343,16 +1372,20 @@ class IOCore extends EventEmitter {
1343
1372
  payloadStringWithoutNull = payloadBuffer.subarray(0, payloadBuffer.byteLength - 1);
1344
1373
  }
1345
1374
  let oneString = decoder$4.decode(payloadStringWithoutNull);
1346
- if (tag.indexOf('@') === 0) this.emit('@', tag, oneString);
1347
- else {
1375
+ if (tag.indexOf('@') === 0) {
1376
+ this.emit('@', tag, oneString);
1377
+ if (tag !== '@') this.emit(tag, tag, oneString);
1378
+ } else {
1348
1379
  this.emit(tag, tag, oneString);
1349
1380
  this.emit('message', tag, oneString);
1350
1381
  }
1351
1382
  break;
1352
1383
 
1353
1384
  case PAYLOAD_TYPE.BINARY:
1354
- if (tag.indexOf('@') === 0) this.emit('@', tag, payloadBuffer);
1355
- else {
1385
+ if (tag.indexOf('@') === 0) {
1386
+ this.emit('@', tag, payloadBuffer);
1387
+ if (tag !== '@') this.emit(tag, tag, payloadBuffer);
1388
+ } else {
1356
1389
  this.emit(tag, tag, payloadBuffer);
1357
1390
  this.emit('message', tag, payloadBuffer);
1358
1391
  }
@@ -1361,8 +1394,10 @@ class IOCore extends EventEmitter {
1361
1394
  case PAYLOAD_TYPE.OBJECT:
1362
1395
  let oneObjectBuffer = decoder$4.decode(payloadBuffer);
1363
1396
  let oneJSONObject = JSON.parse(oneObjectBuffer);
1364
- if (tag.indexOf('@') === 0) this.emit('@', tag, oneJSONObject);
1365
- else {
1397
+ if (tag.indexOf('@') === 0) {
1398
+ this.emit('@', tag, oneJSONObject);
1399
+ if (tag !== '@') this.emit(tag, tag, oneJSONObject);
1400
+ } else {
1366
1401
  this.emit(tag, tag, oneJSONObject);
1367
1402
  this.emit('message', tag, oneJSONObject);
1368
1403
  }
@@ -1371,8 +1406,10 @@ class IOCore extends EventEmitter {
1371
1406
  case PAYLOAD_TYPE.MJSON:
1372
1407
  let mjsonBuffer = decoder$4.decode(payloadBuffer);
1373
1408
  let mjson = JSON.parse(mjsonBuffer);
1374
- if (tag.indexOf('@') === 0) this.emit('@', tag, ...mjson);
1375
- else {
1409
+ if (tag.indexOf('@') === 0) {
1410
+ this.emit('@', tag, ...mjson);
1411
+ if (tag !== '@') this.emit(tag, tag, ...mjson);
1412
+ } else {
1376
1413
  this.emit(tag, tag, ...mjson);
1377
1414
  this.emit('message', tag, ...mjson);
1378
1415
  }
@@ -1380,8 +1417,10 @@ class IOCore extends EventEmitter {
1380
1417
 
1381
1418
  case PAYLOAD_TYPE.MBA:
1382
1419
  let mbaObject = $$1.unpack(payloadBuffer);
1383
- if (tag.indexOf('@') === 0) this.emit('@', tag, ...mbaObject.args);
1384
- else {
1420
+ if (tag.indexOf('@') === 0) {
1421
+ this.emit('@', tag, ...mbaObject.args);
1422
+ if (tag !== '@') this.emit(tag, tag, ...mbaObject.args);
1423
+ } else {
1385
1424
  this.emit(tag, tag, ...mbaObject.args);
1386
1425
  this.emit('message', tag, ...mbaObject.args);
1387
1426
  }
@@ -1726,14 +1765,11 @@ class IOCore extends EventEmitter {
1726
1765
  /**
1727
1766
  * Subscribes to a channel or channels.
1728
1767
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
1729
- * @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.
1730
1769
  */
1731
1770
  subscribe(tag) {
1732
- const tagEncoded = encodeTag(tag);
1733
- this.send_enc_mode(Buffer$1.concat([
1734
- $$1.NB('8', IOMsg.SUBSCRIBE),
1735
- $$1.NB('8', tagEncoded.byteLength),
1736
- tagEncoded]));
1771
+ sendSubscription(this, tag);
1772
+ for (const part of tag.split(',')) this._manualSubscriptions.add(part);
1737
1773
  }
1738
1774
 
1739
1775
 
@@ -1746,7 +1782,7 @@ class IOCore extends EventEmitter {
1746
1782
  // Validate the entire list first, then split only at tag boundaries.
1747
1783
  // Preserve comma-separated entries accepted by existing registration APIs.
1748
1784
  const tags = Array.from(this.channels).join(',').split(',');
1749
- const sizes = tags.map(tag => encodeTag(tag).byteLength);
1785
+ const sizes = tags.map(tag => encodeSubscriptionTags(tag).byteLength);
1750
1786
  const batches = [];
1751
1787
  let batch = [], bytes = 0;
1752
1788
  tags.forEach((tag, i) => {
@@ -1759,23 +1795,27 @@ class IOCore extends EventEmitter {
1759
1795
  batch.push(tag);
1760
1796
  });
1761
1797
  if (batch.length) batches.push(batch.join(','));
1762
- batches.forEach(tag => this.subscribe(tag));
1798
+ batches.forEach(tag => sendSubscription(this, tag));
1763
1799
  }
1764
1800
 
1765
1801
  /**
1766
1802
  * Unsubscribes from a channel or channels.
1767
1803
  * @param {string} [tag=""] - The tag(s) of the channel(s) to unsubscribe from (comma-separated). If empty, unsubscribes from all.
1768
- * @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.
1769
1805
  */
1770
1806
  unsubscribe(tag = "") {
1771
- const tagEncoded = encodeTag(tag);
1807
+ const tagEncoded = encodeSubscriptionTags(tag);
1772
1808
 
1773
1809
  if (tag == "") { // blank tag means unsubscribe all
1774
1810
  this.channels.clear();
1811
+ this._listenTags.clear();
1812
+ this._manualSubscriptions.clear();
1775
1813
  } else {
1776
1814
  let tagList = tag.split(',');
1777
1815
  tagList.forEach(tag => {
1778
1816
  this.channels.delete(tag);
1817
+ this._listenTags.delete(tag);
1818
+ this._manualSubscriptions.delete(tag);
1779
1819
  });
1780
1820
  }
1781
1821
 
@@ -1789,12 +1829,17 @@ class IOCore extends EventEmitter {
1789
1829
 
1790
1830
  /**
1791
1831
  * Convenience API for simple clients (for example, CLI tools): register a
1792
- * tag handler once and remember its subscription in channels. Register before
1793
- * 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
1794
1834
  * and again after reconnect, without application-level ready/subscribe code.
1795
1835
  * This does not send a subscription immediately, even if already ready.
1796
1836
  * For precise subscription/send ordering or dynamic subscriptions, use
1797
- * 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.
1798
1843
  * @param {string} tag - The tag to listen on.
1799
1844
  * @param {Function} handler - The callback function to handle the signal.
1800
1845
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
@@ -1805,7 +1850,9 @@ class IOCore extends EventEmitter {
1805
1850
  if (typeof handler !== 'function') throw TypeError('handler is not a function.')
1806
1851
 
1807
1852
  if (tag.indexOf('@') !== 0) {
1853
+ encodeSubscriptionTags(tag);
1808
1854
  this.channels.add(tag);
1855
+ this._listenTags.add(tag);
1809
1856
  }
1810
1857
  this.on(tag, handler);
1811
1858
  // Subscribe from the CID-ready flow, initially and after reconnect.
@@ -1816,81 +1863,82 @@ class IOCore extends EventEmitter {
1816
1863
 
1817
1864
 
1818
1865
  /**
1819
- * Links a local target to a remote tag and sets up a handler.
1820
- * @param {string} to - The local link target.
1821
- * @param {string} tag - The remote tag.
1822
- * @param {Function} handler - The callback function to handle the signal.
1823
- * @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.
1824
1873
  */
1825
1874
  link(to, tag, handler) {
1826
1875
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1827
- if (typeof tag !== 'string') throw TypeError('tag is not a string.')
1828
1876
  encodeTag(tag, false);
1829
1877
  if (typeof handler !== 'function') throw TypeError('handler is not a function.')
1830
-
1831
- 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) {
1832
1893
  this.channels.add(tag);
1894
+ sendSubscription(this, tag);
1833
1895
  }
1834
-
1835
- let linkSet;
1836
- if (this.linkMap.has(to)) {
1837
- linkSet = this.linkMap.get(to);
1838
- } else {
1839
- linkSet = new Set();
1840
- }
1841
-
1842
- linkSet.add(tag);
1843
- this.linkMap.set(to, linkSet);
1844
- this.on(tag, handler);
1845
- this.subscribe(tag);
1846
-
1847
1896
  }
1848
1897
 
1849
-
1850
1898
  /**
1851
- * Unlinks a specific tag from a local target.
1852
- * @param {string} to - The local link target.
1853
- * @param {string} tag - The tag to unlink.
1854
- * @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.
1855
1904
  */
1856
1905
  unlink(to, tag) {
1857
1906
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1858
- if (typeof tag !== 'string') throw TypeError('tag is not a string.')
1859
1907
  encodeTag(tag, false);
1860
-
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);
1861
1913
  const linkSet = this.linkMap.get(to);
1862
- if (!linkSet || !linkSet.has(tag)) return;
1863
-
1864
- this.unsubscribe(tag);
1865
- this.removeAllListeners(tag);
1866
1914
  linkSet.delete(tag);
1867
-
1868
- if (linkSet.size === 0) {
1915
+ if (tags.size === 0) {
1916
+ this._linkHandlers.delete(to);
1869
1917
  this.linkMap.delete(to);
1870
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(','));
1871
1927
  }
1872
1928
 
1873
1929
  /**
1874
- * Unlinks all tags from a local target.
1875
- * @param {string} to - The local link target.
1876
- * @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.
1877
1933
  */
1878
1934
  unlinkAll(to) {
1879
1935
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1880
-
1881
- const linkSet = this.linkMap.get(to);
1882
- if (!linkSet) return;
1883
-
1884
- for (const tag of linkSet) {
1885
- this.unsubscribe(tag);
1886
- this.removeAllListeners(tag);
1887
- }
1888
-
1889
- 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);
1890
1939
  }
1891
1940
 
1892
1941
 
1893
-
1894
1942
  /**
1895
1943
  * Gets connection metrics.
1896
1944
  * @returns {{tx: number, rx: number, txb: number, rxb: number, last: number}}
@@ -7625,7 +7673,8 @@ class RemoteCore {
7625
7673
 
7626
7674
  switch (msgType) {
7627
7675
  case IOMsg.PING:
7628
- this.pong();
7676
+ // Reply in the IOSignal protocol; browser JS cannot observe WS control PONG.
7677
+ this.send(Buffer.from([IOMsg.PONG]));
7629
7678
  break;
7630
7679
 
7631
7680
  case IOMsg.PONG:
@@ -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
  /**