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.
@@ -15,7 +15,7 @@ import fs, { readFileSync } from 'fs';
15
15
  import { memoryUsage } from 'process';
16
16
  import path from 'path';
17
17
 
18
- var version$1 = "7.1.0";
18
+ var version$1 = "7.2.0";
19
19
  var pkg = {
20
20
  version: version$1};
21
21
 
@@ -783,6 +783,22 @@ function encodeTag(tag, allowEmpty = true) {
783
783
  return encoded
784
784
  }
785
785
 
786
+ // Direct-receive tags are local event names, never server subscriptions.
787
+ function encodeSubscriptionTags(tag) {
788
+ const encoded = encodeTag(tag);
789
+ if (tag.split(',').some(part => part.startsWith('@'))) {
790
+ throw TypeError("direct signal tags need no subscription; use on/listen/link and off/unlink")
791
+ }
792
+ return encoded
793
+ }
794
+
795
+ function sendSubscription(io, tag) {
796
+ const encoded = encodeSubscriptionTags(tag);
797
+ io.send_enc_mode(Buffer$1.concat([
798
+ $$1.NB('8', IOMsg.SUBSCRIBE), $$1.NB('8', encoded.byteLength), encoded
799
+ ]));
800
+ }
801
+
786
802
  function byteToUrl(buffer) {
787
803
  //ipv4(4bytes) , port(2bytes)
788
804
  if (buffer.byteLength != 6) return
@@ -941,6 +957,12 @@ class IOCore extends EventEmitter {
941
957
  * @type {Map<string, Set<string>>}
942
958
  */
943
959
  this.linkMap = new Map();
960
+ /** @private @type {Map<string, Map<string, Set<Function>>>} */
961
+ this._linkHandlers = new Map();
962
+ /** @private @type {Set<string>} */
963
+ this._listenTags = new Set();
964
+ /** @private @type {Set<string>} */
965
+ this._manualSubscriptions = new Set();
944
966
 
945
967
  /**
946
968
  * Indicates if auto-reconnect is enabled.
@@ -1006,6 +1028,7 @@ class IOCore extends EventEmitter {
1006
1028
  reject(error);
1007
1029
  }
1008
1030
  this.promiseMap.clear();
1031
+ this._manualSubscriptions.clear();
1009
1032
  this.cid = '';
1010
1033
  if (this.boho) this.boho.isAuthorized = false;
1011
1034
  if (this.state !== STATE.STOP && this.stateChange('closed')) {
@@ -1034,6 +1057,9 @@ class IOCore extends EventEmitter {
1034
1057
 
1035
1058
  this.channels.clear();
1036
1059
  this.linkMap.clear();
1060
+ this._linkHandlers.clear();
1061
+ this._listenTags.clear();
1062
+ this._manualSubscriptions.clear();
1037
1063
 
1038
1064
  // Help GC
1039
1065
  this.boho = null;
@@ -1327,8 +1353,10 @@ class IOCore extends EventEmitter {
1327
1353
  switch (payloadType) {
1328
1354
 
1329
1355
  case PAYLOAD_TYPE.EMPTY:
1330
- if (tag.indexOf('@') === 0) this.emit('@', tag);
1331
- else {
1356
+ if (tag.indexOf('@') === 0) {
1357
+ this.emit('@', tag);
1358
+ if (tag !== '@') this.emit(tag, tag);
1359
+ } else {
1332
1360
  this.emit(tag, tag);
1333
1361
  this.emit('message', tag);
1334
1362
  }
@@ -1342,16 +1370,20 @@ class IOCore extends EventEmitter {
1342
1370
  payloadStringWithoutNull = payloadBuffer.subarray(0, payloadBuffer.byteLength - 1);
1343
1371
  }
1344
1372
  let oneString = decoder$4.decode(payloadStringWithoutNull);
1345
- if (tag.indexOf('@') === 0) this.emit('@', tag, oneString);
1346
- else {
1373
+ if (tag.indexOf('@') === 0) {
1374
+ this.emit('@', tag, oneString);
1375
+ if (tag !== '@') this.emit(tag, tag, oneString);
1376
+ } else {
1347
1377
  this.emit(tag, tag, oneString);
1348
1378
  this.emit('message', tag, oneString);
1349
1379
  }
1350
1380
  break;
1351
1381
 
1352
1382
  case PAYLOAD_TYPE.BINARY:
1353
- if (tag.indexOf('@') === 0) this.emit('@', tag, payloadBuffer);
1354
- else {
1383
+ if (tag.indexOf('@') === 0) {
1384
+ this.emit('@', tag, payloadBuffer);
1385
+ if (tag !== '@') this.emit(tag, tag, payloadBuffer);
1386
+ } else {
1355
1387
  this.emit(tag, tag, payloadBuffer);
1356
1388
  this.emit('message', tag, payloadBuffer);
1357
1389
  }
@@ -1360,8 +1392,10 @@ class IOCore extends EventEmitter {
1360
1392
  case PAYLOAD_TYPE.OBJECT:
1361
1393
  let oneObjectBuffer = decoder$4.decode(payloadBuffer);
1362
1394
  let oneJSONObject = JSON.parse(oneObjectBuffer);
1363
- if (tag.indexOf('@') === 0) this.emit('@', tag, oneJSONObject);
1364
- else {
1395
+ if (tag.indexOf('@') === 0) {
1396
+ this.emit('@', tag, oneJSONObject);
1397
+ if (tag !== '@') this.emit(tag, tag, oneJSONObject);
1398
+ } else {
1365
1399
  this.emit(tag, tag, oneJSONObject);
1366
1400
  this.emit('message', tag, oneJSONObject);
1367
1401
  }
@@ -1370,8 +1404,10 @@ class IOCore extends EventEmitter {
1370
1404
  case PAYLOAD_TYPE.MJSON:
1371
1405
  let mjsonBuffer = decoder$4.decode(payloadBuffer);
1372
1406
  let mjson = JSON.parse(mjsonBuffer);
1373
- if (tag.indexOf('@') === 0) this.emit('@', tag, ...mjson);
1374
- else {
1407
+ if (tag.indexOf('@') === 0) {
1408
+ this.emit('@', tag, ...mjson);
1409
+ if (tag !== '@') this.emit(tag, tag, ...mjson);
1410
+ } else {
1375
1411
  this.emit(tag, tag, ...mjson);
1376
1412
  this.emit('message', tag, ...mjson);
1377
1413
  }
@@ -1379,8 +1415,10 @@ class IOCore extends EventEmitter {
1379
1415
 
1380
1416
  case PAYLOAD_TYPE.MBA:
1381
1417
  let mbaObject = $$1.unpack(payloadBuffer);
1382
- if (tag.indexOf('@') === 0) this.emit('@', tag, ...mbaObject.args);
1383
- else {
1418
+ if (tag.indexOf('@') === 0) {
1419
+ this.emit('@', tag, ...mbaObject.args);
1420
+ if (tag !== '@') this.emit(tag, tag, ...mbaObject.args);
1421
+ } else {
1384
1422
  this.emit(tag, tag, ...mbaObject.args);
1385
1423
  this.emit('message', tag, ...mbaObject.args);
1386
1424
  }
@@ -1725,14 +1763,11 @@ class IOCore extends EventEmitter {
1725
1763
  /**
1726
1764
  * Subscribes to a channel or channels.
1727
1765
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
1728
- * @throws {TypeError} If tag is not a string or exceeds length limit.
1766
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
1729
1767
  */
1730
1768
  subscribe(tag) {
1731
- const tagEncoded = encodeTag(tag);
1732
- this.send_enc_mode(Buffer$1.concat([
1733
- $$1.NB('8', IOMsg.SUBSCRIBE),
1734
- $$1.NB('8', tagEncoded.byteLength),
1735
- tagEncoded]));
1769
+ sendSubscription(this, tag);
1770
+ for (const part of tag.split(',')) this._manualSubscriptions.add(part);
1736
1771
  }
1737
1772
 
1738
1773
 
@@ -1745,7 +1780,7 @@ class IOCore extends EventEmitter {
1745
1780
  // Validate the entire list first, then split only at tag boundaries.
1746
1781
  // Preserve comma-separated entries accepted by existing registration APIs.
1747
1782
  const tags = Array.from(this.channels).join(',').split(',');
1748
- const sizes = tags.map(tag => encodeTag(tag).byteLength);
1783
+ const sizes = tags.map(tag => encodeSubscriptionTags(tag).byteLength);
1749
1784
  const batches = [];
1750
1785
  let batch = [], bytes = 0;
1751
1786
  tags.forEach((tag, i) => {
@@ -1758,23 +1793,27 @@ class IOCore extends EventEmitter {
1758
1793
  batch.push(tag);
1759
1794
  });
1760
1795
  if (batch.length) batches.push(batch.join(','));
1761
- batches.forEach(tag => this.subscribe(tag));
1796
+ batches.forEach(tag => sendSubscription(this, tag));
1762
1797
  }
1763
1798
 
1764
1799
  /**
1765
1800
  * Unsubscribes from a channel or channels.
1766
1801
  * @param {string} [tag=""] - The tag(s) of the channel(s) to unsubscribe from (comma-separated). If empty, unsubscribes from all.
1767
- * @throws {TypeError} If tag is not a string or exceeds length limit.
1802
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
1768
1803
  */
1769
1804
  unsubscribe(tag = "") {
1770
- const tagEncoded = encodeTag(tag);
1805
+ const tagEncoded = encodeSubscriptionTags(tag);
1771
1806
 
1772
1807
  if (tag == "") { // blank tag means unsubscribe all
1773
1808
  this.channels.clear();
1809
+ this._listenTags.clear();
1810
+ this._manualSubscriptions.clear();
1774
1811
  } else {
1775
1812
  let tagList = tag.split(',');
1776
1813
  tagList.forEach(tag => {
1777
1814
  this.channels.delete(tag);
1815
+ this._listenTags.delete(tag);
1816
+ this._manualSubscriptions.delete(tag);
1778
1817
  });
1779
1818
  }
1780
1819
 
@@ -1788,12 +1827,17 @@ class IOCore extends EventEmitter {
1788
1827
 
1789
1828
  /**
1790
1829
  * Convenience API for simple clients (for example, CLI tools): register a
1791
- * tag handler once and remember its subscription in channels. Register before
1792
- * connection readiness; the CID-ready flow subscribes on initial connection
1830
+ * tag handler once and remember its subscription in channels. For subscription
1831
+ * tags, register before connection readiness; the CID-ready flow subscribes on initial connection
1793
1832
  * and again after reconnect, without application-level ready/subscribe code.
1794
1833
  * This does not send a subscription immediately, even if already ready.
1795
1834
  * For precise subscription/send ordering or dynamic subscriptions, use
1796
- * on() with subscribe() in a ready handler instead. Direct signals use on('@').
1835
+ * on() with subscribe() in a ready handler instead.
1836
+ * Direct signals need no subscription: use on/listen('@') for all direct
1837
+ * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
1838
+ * registered before or after readiness, before the message arrives.
1839
+ * Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
1840
+ * Returning false does not cancel dispatch; a thrown error interrupts it.
1797
1841
  * @param {string} tag - The tag to listen on.
1798
1842
  * @param {Function} handler - The callback function to handle the signal.
1799
1843
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
@@ -1804,7 +1848,9 @@ class IOCore extends EventEmitter {
1804
1848
  if (typeof handler !== 'function') throw TypeError('handler is not a function.')
1805
1849
 
1806
1850
  if (tag.indexOf('@') !== 0) {
1851
+ encodeSubscriptionTags(tag);
1807
1852
  this.channels.add(tag);
1853
+ this._listenTags.add(tag);
1808
1854
  }
1809
1855
  this.on(tag, handler);
1810
1856
  // Subscribe from the CID-ready flow, initially and after reconnect.
@@ -1815,81 +1861,82 @@ class IOCore extends EventEmitter {
1815
1861
 
1816
1862
 
1817
1863
  /**
1818
- * Links a local target to a remote tag and sets up a handler.
1819
- * @param {string} to - The local link target.
1820
- * @param {string} tag - The remote tag.
1821
- * @param {Function} handler - The callback function to handle the signal.
1822
- * @throws {TypeError} If 'to' or 'tag' are not strings, handler is not a function, or tag length is invalid.
1864
+ * Associates handlers with a local component for scoped teardown.
1865
+ * Direct tags (@ or @topic) only register local handlers. Other tags also
1866
+ * subscribe now and are remembered for reconnection.
1867
+ * @param {string} to - The local component identifier, not a server target.
1868
+ * @param {string} tag - The exact event tag.
1869
+ * @param {Function} handler - The callback receiving (tag, ...args).
1870
+ * @throws {TypeError} If the arguments or subscription tags are invalid.
1823
1871
  */
1824
1872
  link(to, tag, handler) {
1825
1873
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1826
- if (typeof tag !== 'string') throw TypeError('tag is not a string.')
1827
1874
  encodeTag(tag, false);
1828
1875
  if (typeof handler !== 'function') throw TypeError('handler is not a function.')
1829
-
1830
- if (tag.indexOf('@') !== 0) {
1876
+ const direct = tag.startsWith('@');
1877
+ if (!direct) encodeSubscriptionTags(tag);
1878
+
1879
+ let tags = this._linkHandlers.get(to);
1880
+ if (!tags) this._linkHandlers.set(to, tags = new Map());
1881
+ let handlers = tags.get(tag);
1882
+ if (!handlers) tags.set(tag, handlers = new Set());
1883
+ // Each registration owns its wrapper, even if components share a callback.
1884
+ const linkedHandler = (...args) => handler.apply(this, args);
1885
+ handlers.add(linkedHandler);
1886
+ let linkSet = this.linkMap.get(to);
1887
+ if (!linkSet) this.linkMap.set(to, linkSet = new Set());
1888
+ linkSet.add(tag);
1889
+ this.on(tag, linkedHandler);
1890
+ if (!direct) {
1831
1891
  this.channels.add(tag);
1892
+ sendSubscription(this, tag);
1832
1893
  }
1833
-
1834
- let linkSet;
1835
- if (this.linkMap.has(to)) {
1836
- linkSet = this.linkMap.get(to);
1837
- } else {
1838
- linkSet = new Set();
1839
- }
1840
-
1841
- linkSet.add(tag);
1842
- this.linkMap.set(to, linkSet);
1843
- this.on(tag, handler);
1844
- this.subscribe(tag);
1845
-
1846
1894
  }
1847
1895
 
1848
-
1849
1896
  /**
1850
- * Unlinks a specific tag from a local target.
1851
- * @param {string} to - The local link target.
1852
- * @param {string} tag - The tag to unlink.
1853
- * @throws {TypeError} If 'to' or 'tag' are not strings or tag length is invalid.
1897
+ * Removes only one local component's handlers for a tag. Direct tags never
1898
+ * send an unsubscribe. Shared subscriptions and explicit subscriptions remain.
1899
+ * @param {string} to - The local component identifier.
1900
+ * @param {string} tag - The exact linked tag.
1901
+ * @throws {TypeError} If the arguments are invalid.
1854
1902
  */
1855
1903
  unlink(to, tag) {
1856
1904
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1857
- if (typeof tag !== 'string') throw TypeError('tag is not a string.')
1858
1905
  encodeTag(tag, false);
1859
-
1906
+ const tags = this._linkHandlers.get(to);
1907
+ const handlers = tags?.get(tag);
1908
+ if (!handlers) return
1909
+ for (const handler of handlers) this.removeListener(tag, handler);
1910
+ tags.delete(tag);
1860
1911
  const linkSet = this.linkMap.get(to);
1861
- if (!linkSet || !linkSet.has(tag)) return;
1862
-
1863
- this.unsubscribe(tag);
1864
- this.removeAllListeners(tag);
1865
1912
  linkSet.delete(tag);
1866
-
1867
- if (linkSet.size === 0) {
1913
+ if (tags.size === 0) {
1914
+ this._linkHandlers.delete(to);
1868
1915
  this.linkMap.delete(to);
1869
1916
  }
1917
+ if (tag.startsWith('@')) return
1918
+
1919
+ const linkedElsewhere = [...this._linkHandlers.values()].some(other => other.has(tag));
1920
+ if (!linkedElsewhere && !this._listenTags.has(tag)) this.channels.delete(tag);
1921
+ const remembered = new Set([...this.channels].flatMap(entry => entry.split(',')));
1922
+ const unused = tag.split(',').filter(part =>
1923
+ !remembered.has(part) && !this._manualSubscriptions.has(part));
1924
+ if (unused.length) this.unsubscribe(unused.join(','));
1870
1925
  }
1871
1926
 
1872
1927
  /**
1873
- * Unlinks all tags from a local target.
1874
- * @param {string} to - The local link target.
1875
- * @throws {TypeError} If 'to' is not a string.
1928
+ * Removes this local component's links without removing other listeners.
1929
+ * @param {string} to - The local component identifier.
1930
+ * @throws {TypeError} If the component identifier is not a string.
1876
1931
  */
1877
1932
  unlinkAll(to) {
1878
1933
  if (typeof to !== 'string') throw TypeError('to(local link target) is not a string.')
1879
-
1880
- const linkSet = this.linkMap.get(to);
1881
- if (!linkSet) return;
1882
-
1883
- for (const tag of linkSet) {
1884
- this.unsubscribe(tag);
1885
- this.removeAllListeners(tag);
1886
- }
1887
-
1888
- this.linkMap.delete(to);
1934
+ const tags = this._linkHandlers.get(to);
1935
+ if (!tags) return
1936
+ for (const tag of [...tags.keys()]) this.unlink(to, tag);
1889
1937
  }
1890
1938
 
1891
1939
 
1892
-
1893
1940
  /**
1894
1941
  * Gets connection metrics.
1895
1942
  * @returns {{tx: number, rx: number, txb: number, rxb: number, last: number}}
@@ -140,6 +140,12 @@ export class IOCore extends EventEmitter<string | symbol, any> {
140
140
  * @type {Map<string, Set<string>>}
141
141
  */
142
142
  linkMap: Map<string, Set<string>>;
143
+ /** @private @type {Map<string, Map<string, Set<Function>>>} */
144
+ private _linkHandlers;
145
+ /** @private @type {Set<string>} */
146
+ private _listenTags;
147
+ /** @private @type {Set<string>} */
148
+ private _manualSubscriptions;
143
149
  /**
144
150
  * Indicates if auto-reconnect is enabled.
145
151
  * @type {boolean}
@@ -317,7 +323,7 @@ export class IOCore extends EventEmitter<string | symbol, any> {
317
323
  /**
318
324
  * Subscribes to a channel or channels.
319
325
  * @param {string} tag - The tag(s) of the channel(s) to subscribe to (comma-separated).
320
- * @throws {TypeError} If tag is not a string or exceeds length limit.
326
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
321
327
  */
322
328
  subscribe(tag: string): void;
323
329
  /**
@@ -328,41 +334,49 @@ export class IOCore extends EventEmitter<string | symbol, any> {
328
334
  /**
329
335
  * Unsubscribes from a channel or channels.
330
336
  * @param {string} [tag=""] - The tag(s) of the channel(s) to unsubscribe from (comma-separated). If empty, unsubscribes from all.
331
- * @throws {TypeError} If tag is not a string or exceeds length limit.
337
+ * @throws {TypeError} If tag is invalid, exceeds the length limit, or contains a direct-receive subscription.
332
338
  */
333
339
  unsubscribe(tag?: string): void;
334
340
  /**
335
341
  * Convenience API for simple clients (for example, CLI tools): register a
336
- * tag handler once and remember its subscription in channels. Register before
337
- * connection readiness; the CID-ready flow subscribes on initial connection
342
+ * tag handler once and remember its subscription in channels. For subscription
343
+ * tags, register before connection readiness; the CID-ready flow subscribes on initial connection
338
344
  * and again after reconnect, without application-level ready/subscribe code.
339
345
  * This does not send a subscription immediately, even if already ready.
340
346
  * For precise subscription/send ordering or dynamic subscriptions, use
341
- * on() with subscribe() in a ready handler instead. Direct signals use on('@').
347
+ * on() with subscribe() in a ready handler instead.
348
+ * Direct signals need no subscription: use on/listen('@') for all direct
349
+ * signals, or on/listen('@topic') for an exact topic. Direct handlers can be
350
+ * registered before or after readiness, before the message arrives.
351
+ * Dispatch is synchronous: '@' first, then '@topic' when tag is not '@'.
352
+ * Returning false does not cancel dispatch; a thrown error interrupts it.
342
353
  * @param {string} tag - The tag to listen on.
343
354
  * @param {Function} handler - The callback function to handle the signal.
344
355
  * @throws {TypeError} If tag is not a string, handler is not a function, or tag length is invalid.
345
356
  */
346
357
  listen(tag: string, handler: Function): void;
347
358
  /**
348
- * Links a local target to a remote tag and sets up a handler.
349
- * @param {string} to - The local link target.
350
- * @param {string} tag - The remote tag.
351
- * @param {Function} handler - The callback function to handle the signal.
352
- * @throws {TypeError} If 'to' or 'tag' are not strings, handler is not a function, or tag length is invalid.
359
+ * Associates handlers with a local component for scoped teardown.
360
+ * Direct tags (@ or @topic) only register local handlers. Other tags also
361
+ * subscribe now and are remembered for reconnection.
362
+ * @param {string} to - The local component identifier, not a server target.
363
+ * @param {string} tag - The exact event tag.
364
+ * @param {Function} handler - The callback receiving (tag, ...args).
365
+ * @throws {TypeError} If the arguments or subscription tags are invalid.
353
366
  */
354
367
  link(to: string, tag: string, handler: Function): void;
355
368
  /**
356
- * Unlinks a specific tag from a local target.
357
- * @param {string} to - The local link target.
358
- * @param {string} tag - The tag to unlink.
359
- * @throws {TypeError} If 'to' or 'tag' are not strings or tag length is invalid.
369
+ * Removes only one local component's handlers for a tag. Direct tags never
370
+ * send an unsubscribe. Shared subscriptions and explicit subscriptions remain.
371
+ * @param {string} to - The local component identifier.
372
+ * @param {string} tag - The exact linked tag.
373
+ * @throws {TypeError} If the arguments are invalid.
360
374
  */
361
375
  unlink(to: string, tag: string): void;
362
376
  /**
363
- * Unlinks all tags from a local target.
364
- * @param {string} to - The local link target.
365
- * @throws {TypeError} If 'to' is not a string.
377
+ * Removes this local component's links without removing other listeners.
378
+ * @param {string} to - The local component identifier.
379
+ * @throws {TypeError} If the component identifier is not a string.
366
380
  */
367
381
  unlinkAll(to: string): void;
368
382
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "iosignal",
3
- "version": "7.1.0",
3
+ "version": "7.2.0",
4
4
  "description": "iosignal",
5
5
  "type": "module",
6
6
  "exports": {