iosignal 3.0.0 → 3.0.1

package/src/client/IOWS.js

@@ -1,4 +1,5 @@
 import { IOCore } from "./IOCore.js";
+import { STATES } from "../common/constants.js";
 import { WebSocket } from "ws";
 
 //  Node.js 'ws' websocket
@@ -10,32 +11,28 @@ export class IOWS extends IOCore {
 
 
 
+  /**
+   * Closes ws WebSocket and cleans resources.
+   */
   close() {
     if (this.socket) {
-      this.socket.onclose = null
-      this.socket.onmessage = null
-      this.socket.onerror = null
-      this.socket.close();
-      this.socket = null;
+      this.socket.removeAllListeners();
+      if (this.socket.readyState !== WebSocket.CLOSED) {
+        this.socket.close();
+      }
     }
-    this.emit('close')
+    super.close();
   }
 
 
-
-  stop() {
-    this.close()
-    clearInterval(this.connectionCheckerIntervalID);
-    this.connectionCheckerIntervalID = null
-  }
-
   keepAlive() {
-    if (!this.socket || this.socket?.readyState === 3) {
+    if (!this.autoReconnect) return;
+    // Reconnect only if the socket is closed and the state reflects that.
+    if ((!this.socket || this.socket.readyState === WebSocket.CLOSED) && this.state === STATES.CLOSED) {
       this.open();
     }
   }
 
-
   createConnection(url) {
     // node WebSocket
     this.socket = new WebSocket(url);

package/src/client/browser/IOWebSocket.js

@@ -3,23 +3,79 @@ import { IOCore } from "../IOCore.js";
 import Boho from 'boho'
 import * as constants from '../../common/constants.js'
 
+/**
+ * @typedef {import("boho").Boho} Boho
+ * @typedef {import("boho").MBP} MBP
+ * @typedef {import("boho").Buffer} Buffer
+ */
+
 const Buffer = Boho.Buffer
 
-// Browser WebSocket
+/**
+ * Browser WebSocket client extending IOCore.
+ * @augments {IOCore}
+ */
 export default class IO extends IOCore {
+  /**
+   * The version of the client.
+   * @type {string}
+   */
   static version = version
+  /**
+   * The binary type for WebSocket messages.
+   * @type {string}
+   */
   static binaryType = "arraybuffer"
+  /**
+   * The Boho library instance.
+   * @type {Boho}
+   */
   static Boho = Boho;
+  /**
+   * The MBP (MessagePack-Boho) instance.
+   * @type {MBP}
+   */
   static MBP = Boho.MBP;
+  /**
+   * The Buffer class from Boho.
+   * @type {Buffer}
+   */
   static Buffer = Boho.Buffer;
+  /**
+   * Constants used by the client.
+   * @type {object}
+   */
   static constants = constants
 
+  /**
+   * Tracks the number of IO instances created.
+   * @type {number}
+   */
+  static instanceCount = 0;
+
+  /**
+   * Tracks the number of WebSocket objects created.
+   * @type {number}
+   */
+  static webSocketCount = 0;
+
+
+
+  /**
+   * Creates an instance of IO.
+   * @param {string} url - The WebSocket URL to connect to.
+   */
   constructor(url) {
     super(url);
-    document.addEventListener('visibilitychange', this.browserVisiblePing.bind(this));
+    IO.instanceCount++;
+    this.boundBrowserVisiblePing = this.browserVisiblePing.bind(this)
+    document.addEventListener('visibilitychange', this.boundBrowserVisiblePing);
     if (url) this.open();
   }
 
+  /**
+   * Pings the server when the browser tab becomes visible.
+   */
   browserVisiblePing() {
     if (document.visibilityState === 'visible') {
       this.ping()
@@ -27,41 +83,72 @@ export default class IO extends IOCore {
   }
 
 
+  /**
+   * Closes the WebSocket connection and cleans up its event handlers.
+   * This is intended for temporary disconnections, and the connection might be re-established by keepAlive.
+   */
   close() {
     if (this.socket) {
-      this.socket.onclose = null
-      this.socket.onmessage = null
-      this.socket.onerror = null
-      this.socket.close();
-      this.socket = null;
+      this.socket.onopen = null;
+      this.socket.onclose = null;
+      this.socket.onmessage = null;
+      this.socket.onerror = null;
+      if (this.socket.readyState === WebSocket.OPEN || this.socket.readyState === WebSocket.CONNECTING) {
+        this.socket.close();
+      }
     }
-    this.emit('close')
+    super.close();
   }
 
-
+  /**
+   * Permanently stops the connection and cleans up its specific resources.
+   * For complete cleanup and to make the instance unusable, use destroy().
+   */
   stop() {
-    this.close()
-    clearInterval(this.connectionCheckerIntervalID);
-    this.connectionCheckerIntervalID = null
+    super.stop();
+  }
+
+  /**
+   * Permanently destroys the instance, cleaning up all resources including global event listeners.
+   * The instance will not be usable after this.
+   */
+  destroy() {
+    document.removeEventListener('visibilitychange', this.boundBrowserVisiblePing);
+    super.destroy();
   }
 
 
+  /**
+   * Keeps the connection alive by re-opening if closed.
+   */
   keepAlive() {
-    if (!this.socket || this.socket?.readyState === 3) {
+    if (!this.autoReconnect) return;
+    // Reconnect only if the socket is closed and the state reflects that.
+    if ((!this.socket || this.socket.readyState === WebSocket.CLOSED) && this.state === IO.constants.STATES.CLOSED) {
       this.open();
     }
   }
 
 
 
+  /**
+   * Creates a new WebSocket connection.
+   * @param {string} url - The WebSocket URL to connect to.
+   */
   createConnection(url) {
     // Web Browser WebSocket
+    IO.webSocketCount++;
     this.socket = new WebSocket(url);
     this.socket.binaryType = IO.binaryType
 
     this.stateChange('opening')
 
     this.socket.onopen = () => {
+
+      if (!this.socket) {
+        return;
+      }
+
       if (this.socket.binaryType == "arraybuffer") {
         this.socket.onmessage = this.onWebSocketMessage.bind(this);
       } else {  // blob
@@ -79,6 +166,10 @@ export default class IO extends IOCore {
     }
   }
 
+  /**
+   * Handles incoming WebSocket messages (arraybuffer type).
+   * @param {MessageEvent} event - The WebSocket message event.
+   */
   onWebSocketMessage(event) {
     // event.data is arrayBuffer  or text_message
     this.rxCounter++;
@@ -88,6 +179,10 @@ export default class IO extends IOCore {
     this.emit('socket_data', buffer);
   }
 
+  /**
+   * Handles incoming WebSocket messages (blob type).
+   * @param {MessageEvent} event - The WebSocket message event.
+   */
   async onWebSocketMessageBlob(event) {
     // event.data is Blob or text_message
     this.rxCounter++;
@@ -103,6 +198,10 @@ export default class IO extends IOCore {
     this.emit('socket_data', buffer);
   }
 
+  /**
+   * Sends data over the WebSocket.
+   * @param {BufferSource} data - The data to send.
+   */
   socket_send(data) {
     if (this.socket?.readyState === 1) {
       this.socket.send(data)

package/src/common/constants.js

@@ -1,4 +1,16 @@
 
+/**
+ * @typedef {object} STATES
+ * @property {number} OPENING
+ * @property {number} OPEN
+ * @property {number} CLOSING
+ * @property {number} CLOSED
+ * @property {number} SERVER_READY
+ * @property {number} AUTH_FAIL
+ * @property {number} AUTH_READY
+ * @property {number} READY
+ * @property {number} REDIRECTING
+ */
 // Client STATES: name and number
 export const STATES = {
   OPENING: 0,
@@ -13,7 +25,17 @@ export const STATES = {
 }
 for (let c in STATES) { STATES[STATES[c]] = c }
 
-// server side client state
+/**
+ * @typedef {object} CLIENT_STATE
+ * @property {number} INIT
+ * @property {number} SENT_SERVER_READY
+ * @property {number} RECV_AUTH_REQ
+ * @property {number} SENT_SERVER_NONCE
+ * @property {number} RECV_AUTH_HMAC
+ * @property {number} AUTH_FAIL
+ * @property {number} AUTH_READY
+ * @property {number} CID_READY
+ */
 export const CLIENT_STATE = {
   INIT: 0,
   SENT_SERVER_READY: 1,
@@ -26,6 +48,12 @@ export const CLIENT_STATE = {
 }
 for (let c in CLIENT_STATE) { CLIENT_STATE[CLIENT_STATE[c]] = c }
 
+/**
+ * @typedef {object} ENC_MODE
+ * @property {number} NO
+ * @property {number} YES
+ * @property {number} AUTO
+ */
 export let ENC_MODE = {
   NO: 0,
   YES: 1,
@@ -35,6 +63,15 @@ export let ENC_MODE = {
 for (let c in ENC_MODE) { ENC_MODE[ENC_MODE[c]] = c }
 
 
+/**
+ * @typedef {object} SIZE_LIMIT
+ * @property {number} TAG_LEN1
+ * @property {number} TAG_LEN2
+ * @property {number} CONNECTION_CHECKER_PERIOD
+ * @property {number} PROMISE_TIMEOUT
+ * @property {number} DID
+ * @property {number} CID
+ */
 export const SIZE_LIMIT = {
   TAG_LEN1: 255,
   TAG_LEN2: 65535,
@@ -44,6 +81,15 @@ export const SIZE_LIMIT = {
   CID: 12
 }
 
+/**
+ * @typedef {object} PAYLOAD_TYPE
+ * @property {number} EMPTY
+ * @property {number} TEXT
+ * @property {number} BINARY
+ * @property {number} OBJECT
+ * @property {number} MJSON
+ * @property {number} MBA
+ */
 export let PAYLOAD_TYPE = {
   EMPTY: 0,
   TEXT: 1,
@@ -55,6 +101,40 @@ export let PAYLOAD_TYPE = {
 for (let c in PAYLOAD_TYPE) { PAYLOAD_TYPE[PAYLOAD_TYPE[c]] = c }
 
 
+/**
+ * @typedef {object} IOMsg
+ * @property {number} SERVER_READY
+ * @property {number} CID_REQ
+ * @property {number} CID_RES
+ * @property {number} QUOTA_LEVEL
+ * @property {number} SERVER_CLEAR_AUTH
+ * @property {number} SERVER_REDIRECT
+ * @property {number} LOOP
+ * @property {number} ECHO
+ * @property {number} PING
+ * @property {number} PONG
+ * @property {number} CLOSE
+ * @property {number} SIGNAL
+ * @property {number} SIGNAL_REQ
+ * @property {number} SIGNAL_E2E
+ * @property {number} SUBSCRIBE
+ * @property {number} SUBSCRIBE_REQ
+ * @property {number} UNSUBSCRIBE
+ * @property {number} SERVER_SIGNAL
+ * @property {number} IAM
+ * @property {number} IAM_RES
+ * @property {number} SET
+ * @property {number} RESPONSE_CODE
+ * @property {number} RESPONSE_MBP
+ * @property {number} REQUEST
+ * @property {number} RESPONSE
+ * @property {number} FLOW_MODE
+ * @property {number} WAIT
+ * @property {number} RESUME
+ * @property {number} TIME_OUT
+ * @property {number} OVER_SIZE
+ * @property {number} OVER_FLOW
+ */
 // IO message's one-byte headers.
 export let IOMsg = {
 
@@ -134,11 +214,21 @@ export let IOMsg = {
 for (let c in IOMsg) { IOMsg[IOMsg[c]] = c }
 // console.log( IOMsg );
 
+/**
+ * @typedef {object} API_TYPE
+ * @property {string} REQUEST_RESPONSE
+ * @property {string} ONE_WAY
+ */
 export const API_TYPE = {
   'REQUEST_RESPONSE': 'requet_response',
   'ONE_WAY': 'one_way'
 }
 
+/**
+ * @typedef {object} STATUS
+ * @property {number} OK
+ * @property {number} ERROR
+ */
 // api response status code
 export const STATUS = {
   OK: 0,

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist/types",
+    "allowJs": true,
+    "moduleResolution": "node",
+    "target": "es2015",
+    "lib": ["es2020", "dom"],
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": ["src/*"]
+    }
+  },
+  "include": [
+    "src/client/browser/IOWebSocket.js",
+    "src/client/IOCore.js",
+    "src/common/constants.js",
+    "package.json"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}