@das-fed/upf-utils 6.4.0-dev.291 → 6.4.0-dev.292

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@das-fed/upf-utils",
-  "version": "6.4.0-dev.291",
+  "version": "6.4.0-dev.292",
   "description": "",
   "type": "module",
   "main": "./index.js",
@@ -22,8 +22,8 @@
   },
   "devDependencies": {
     "@babel/preset-env": "7.26.0",
-    "@das-fed/upf-cli": "6.4.0-dev.291",
-    "@das-fed/upf-web": "6.4.0-dev.291",
+    "@das-fed/upf-cli": "6.4.0-dev.292",
+    "@das-fed/upf-web": "6.4.0-dev.292",
     "@rollup/plugin-babel": "6.0.4",
     "@types/js-cookie": "^3.0.6",
     "@types/lodash-es": "^4.17.12",
@@ -51,13 +51,13 @@
   },
   "upfReleaseMeta": {
     "packageName": "@das-fed/upf-utils",
-    "releaseVersion": "6.4.0-dev.291",
+    "releaseVersion": "6.4.0-dev.292",
     "distTag": "dev",
     "releaseType": "publish",
-    "publishedAt": "2026-07-13T02:00:37.590Z",
+    "publishedAt": "2026-07-14T06:46:37.761Z",
     "sourceBranch": "dev",
-    "sourceCommit": "14810ecd88ae0e6ec2d3e6eb686b3fddde26e908",
-    "gitTag": "upf-release/v6.4.0-dev.291",
+    "sourceCommit": "9766fa3af4bca90be90632cab0c7653f16f56bfe",
+    "gitTag": "upf-release/v6.4.0-dev.292",
     "gitRemote": "origin",
     "gitRemoteUrl": "http://gitlab.dasiot.cn/foundation/frontend/framework.git",
     "releaseStatus": "success"

package/realtime-connection/es5.d.ts

@@ -1,8 +1,11 @@
 export type RealtimeSocketState = 'idle' | 'waiting-token' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'unsupported';
 export type RealtimeSocketHeartbeatOptions = {
     message: string | (() => string);
+    /** 心跳间隔（毫秒），仅接受浏览器定时器支持范围内的正数。 */
     interval: number;
+    /** 等待 response 的超时时间（毫秒）；未配置 response 时不启用应答超时。 */
     timeout?: number;
+    /** 服务端心跳响应内容，可配置一个或多个精确匹配值。 */
     response?: string | string[];
 };
 export type RealtimeSocketReconnectOptions = {
@@ -37,7 +40,9 @@ export declare class RealtimeSocketClient<T = unknown> {
     private reconnectAttempts;
     private manualClosed;
     private started;
-    private lastHeartbeatAck;
+    private opening;
+    private openVersion;
+    private heartbeatSequence;
     constructor(options: RealtimeSocketClientOptions<T>);
     /** 获取当前连接状态，供业务显示或调试兜底使用。 */
     getState(): RealtimeSocketState;
@@ -53,13 +58,19 @@ export declare class RealtimeSocketClient<T = unknown> {
     private handleMessage;
     private handleClose;
     private handleError;
+    /** 启动单实例心跳；等待应答期间不重复发送，避免 interval 与 timeout 竞争。 */
     private startHeartbeat;
+    /** 心跳发送或应答超时后，仅关闭当前连接并进入既有重连流程。 */
+    private handleHeartbeatFailure;
     private scheduleReconnect;
     private getReconnectDelay;
     private handleOnline;
     private handleOffline;
     private setState;
     private closeSocket;
+    private cancelPendingOpen;
+    private isCurrentOpen;
+    private isCurrentSocket;
     private clearTimers;
     private clearHeartbeatTimers;
     private clearHeartbeatTimeoutTimer;

package/realtime-connection/es5.js

@@ -15,38 +15,45 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 var config = require('@das-fed/upf-utils/config/es5');
 var commonTools = require('@das-fed/upf-utils/common-tools/es5');
-var l = 3e3,
-  u = 3e4,
-  m = function m() {
-    var i = config.getConfig(),
-      t = i.wsBaseURL || i.baseURL || location.origin;
-    return String(t || "").replace(/^https:/i, "wss:").replace(/^http:/i, "ws:").replace(/\/+$/, "");
+var m = 3e3,
+  d = 3e4,
+  f = 2147483647,
+  p = function p() {
+    var n = config.getConfig(),
+      e = n.wsBaseURL || n.baseURL || location.origin;
+    return String(e || "").replace(/^https:/i, "wss:").replace(/^http:/i, "ws:").replace(/\/+$/, "");
   },
-  d = function d(i) {
-    return /^wss?:\/\//i.test(i);
+  T = function T(n) {
+    return /^wss?:\/\//i.test(n);
   },
-  f = function f(i) {
-    return /^https?:\/\//i.test(i);
+  S = function S(n) {
+    return /^https?:\/\//i.test(n);
   },
-  p = function p(i, t) {
-    var e = String(i || "").trim(),
-      s = d(e) ? e : f(e) ? e.replace(/^https:/i, "wss:").replace(/^http:/i, "ws:") : "".concat(m()).concat(e.startsWith("/") ? e : "/".concat(e)),
-      r = commonTools.objectToUrlparams(t);
-    return r ? "".concat(s).concat(s.includes("?") ? "&" : "?").concat(r) : s;
+  g = function g(n, e) {
+    var t = String(n || "").trim(),
+      s = T(t) ? t : S(t) ? t.replace(/^https:/i, "wss:").replace(/^http:/i, "ws:") : "".concat(p()).concat(t.startsWith("/") ? t : "/".concat(t)),
+      i = commonTools.objectToUrlparams(e);
+    return i ? "".concat(s).concat(s.includes("?") ? "&" : "?").concat(i) : s;
   },
-  T = function T(i, t) {
-    return t ? (Array.isArray(t) ? t : [t]).includes(String(i !== null && i !== void 0 ? i : "")) : false;
+  b = function b(n, e) {
+    return e ? (Array.isArray(e) ? e : [e]).includes(String(n !== null && n !== void 0 ? n : "")) : false;
   },
-  b = function b(i) {
-    return typeof i.data == "string" ? JSON.parse(i.data) : i.data;
+  w = function w(n) {
+    return (Array.isArray(n) || typeof n == "string") && n.length > 0;
+  },
+  c = function c(n) {
+    return Number.isFinite(n) && n >= 1 && n <= f;
+  },
+  k = function k(n) {
+    return typeof n.data == "string" ? JSON.parse(n.data) : n.data;
   };
-var S = /*#__PURE__*/function () {
-  function S(t) {
-    _classCallCheck(this, S);
-    this.ws = null, this.state = "idle", this.heartbeatTimer = null, this.heartbeatTimeoutTimer = null, this.reconnectTimer = null, this.reconnectAttempts = 0, this.manualClosed = false, this.started = false, this.lastHeartbeatAck = true, this.options = t, this.handleOnline = this.handleOnline.bind(this), this.handleOffline = this.handleOffline.bind(this);
+var y = /*#__PURE__*/function () {
+  function y(e) {
+    _classCallCheck(this, y);
+    this.ws = null, this.state = "idle", this.heartbeatTimer = null, this.heartbeatTimeoutTimer = null, this.reconnectTimer = null, this.reconnectAttempts = 0, this.manualClosed = false, this.started = false, this.opening = false, this.openVersion = 0, this.heartbeatSequence = 0, this.options = e, this.handleOnline = this.handleOnline.bind(this), this.handleOffline = this.handleOffline.bind(this);
   }
   /** 获取当前连接状态，供业务显示或调试兜底使用。 */
-  return _createClass(S, [{
+  return _createClass(y, [{
     key: "getState",
     value: function getState() {
       return this.state;
@@ -59,7 +66,7 @@ var S = /*#__PURE__*/function () {
         return _regenerator().w(function (_context) {
           while (1) switch (_context.n) {
             case 0:
-              if (this.started && (this.state === "connecting" || this.state === "open" || this.state === "reconnecting")) {
+              if (this.started && (this.state === "waiting-token" || this.state === "connecting" || this.state === "open" || this.state === "reconnecting")) {
                 _context.n = 2;
                 break;
               }
@@ -85,63 +92,94 @@ var S = /*#__PURE__*/function () {
     }() /** 仅在连接已打开时发送消息，失败时返回 false。 */)
   }, {
     key: "send",
-    value: function send(t) {
-      var e;
-      return ((e = this.ws) == null ? undefined : e.readyState) !== WebSocket.OPEN ? false : (this.ws.send(t), true);
+    value: function send(e) {
+      var t = this.ws;
+      if (!t || t.readyState !== WebSocket.OPEN) return false;
+      try {
+        return t.send(e), !0;
+      } catch (_unused) {
+        return false;
+      }
     }
     /** 主动关闭连接，并清理心跳、重连和网络监听。 */
   }, {
     key: "close",
     value: function close() {
-      this.manualClosed = true, this.started = false, this.clearTimers(), this.removeNetworkListeners(), this.closeSocket(), this.setState("closed");
+      this.manualClosed = true, this.started = false, this.cancelPendingOpen(), this.clearTimers(), this.removeNetworkListeners(), this.closeSocket(), this.setState("closed");
     }
   }, {
     key: "openSocket",
     value: function () {
       var _openSocket = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
         var _this = this;
-        var s, r, t, e, n;
+        var i, o, e, t, s, r, _t;
         return _regenerator().w(function (_context2) {
-          while (1) switch (_context2.n) {
+          while (1) switch (_context2.p = _context2.n) {
             case 0:
-              if (!this.manualClosed) {
+              if (!(!this.started || this.manualClosed || this.opening)) {
                 _context2.n = 1;
                 break;
               }
               return _context2.a(2);
             case 1:
-              this.clearReconnectTimer(), this.closeSocket(), this.setState(this.reconnectAttempts > 0 ? "reconnecting" : "connecting");
-              t = _objectSpread({}, this.options.params || {});
-              _context2.n = 2;
-              return this.resolveToken();
-            case 2:
-              e = _context2.v;
-              if (!(this.options.tokenProvider && !e)) {
-                _context2.n = 3;
+              if (!((typeof navigator === "undefined" ? "undefined" : _typeof(navigator)) < "u" && navigator.onLine === false)) {
+                _context2.n = 2;
                 break;
               }
-              this.scheduleReconnect("waiting-token");
+              this.setState(this.reconnectAttempts > 0 ? "reconnecting" : "waiting-token");
               return _context2.a(2);
+            case 2:
+              e = ++this.openVersion;
+              this.opening = true, this.clearReconnectTimer(), this.clearHeartbeatTimers(), this.closeSocket(), this.setState(this.reconnectAttempts > 0 ? "reconnecting" : "connecting");
+              t = _objectSpread({}, this.options.params || {});
+              _context2.n = 3;
+              return this.resolveToken();
             case 3:
-              e && (t[this.options.tokenParamName || "access_token"] = e);
-              try {
-                n = new WebSocket(p(this.options.url, t));
-                this.ws = n, n.onopen = function (o) {
-                  return _this.handleOpen(o);
-                }, n.onmessage = function (o) {
-                  return _this.handleMessage(o);
-                }, n.onclose = function (o) {
-                  return _this.handleClose(o);
-                }, n.onerror = function (o) {
-                  return _this.handleError(o);
-                };
-              } catch (n) {
-                (r = (s = this.options).onInvalidMessage) == null || r.call(s, n, {}), this.scheduleReconnect();
+              s = _context2.v;
+              if (!this.isCurrentOpen(e)) {
+                _context2.n = 9;
+                break;
               }
+              if (!(this.options.tokenProvider && !s)) {
+                _context2.n = 4;
+                break;
+              }
+              this.opening = false, this.scheduleReconnect("waiting-token");
+              return _context2.a(2);
             case 4:
+              s && (t[this.options.tokenParamName || "access_token"] = s);
+              _context2.p = 5;
+              r = new WebSocket(g(this.options.url, t));
+              if (this.isCurrentOpen(e)) {
+                _context2.n = 6;
+                break;
+              }
+              r.close();
+              return _context2.a(2);
+            case 6:
+              this.ws = r, r.onopen = function (a) {
+                return _this.handleOpen(r, a);
+              }, r.onmessage = function (a) {
+                return _this.handleMessage(r, a);
+              }, r.onclose = function (a) {
+                return _this.handleClose(r, a);
+              }, r.onerror = function (a) {
+                return _this.handleError(r, a);
+              };
+              _context2.n = 8;
+              break;
+            case 7:
+              _context2.p = 7;
+              _t = _context2.v;
+              this.isCurrentOpen(e) && ((o = (i = this.options).onInvalidMessage) == null || o.call(i, _t, {}), this.scheduleReconnect());
+            case 8:
+              _context2.p = 8;
+              this.openVersion === e && (this.opening = false);
+              return _context2.f(8);
+            case 9:
               return _context2.a(2);
           }
-        }, _callee2, this);
+        }, _callee2, this, [[5, 7, 8, 9]]);
       }));
       function openSocket() {
         return _openSocket.apply(this, arguments);
@@ -152,7 +190,7 @@ var S = /*#__PURE__*/function () {
     key: "resolveToken",
     value: function () {
       var _resolveToken = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3() {
-        var _t, _t2, _t3;
+        var _t2, _t3, _t4;
         return _regenerator().w(function (_context3) {
           while (1) switch (_context3.p = _context3.n) {
             case 0:
@@ -163,21 +201,21 @@ var S = /*#__PURE__*/function () {
               return _context3.a(2, "");
             case 1:
               _context3.p = 1;
-              _t = String;
+              _t2 = String;
               _context3.n = 2;
               return this.options.tokenProvider();
             case 2:
-              _t2 = _context3.v;
-              if (_t2) {
+              _t3 = _context3.v;
+              if (_t3) {
                 _context3.n = 3;
                 break;
               }
-              _t2 = "";
+              _t3 = "";
             case 3:
-              return _context3.a(2, _t(_t2).trim());
+              return _context3.a(2, _t2(_t3).trim());
             case 4:
               _context3.p = 4;
-              _t3 = _context3.v;
+              _t4 = _context3.v;
               return _context3.a(2, "");
           }
         }, _callee3, this, [[1, 4]]);
@@ -189,122 +227,160 @@ var S = /*#__PURE__*/function () {
     }()
   }, {
     key: "handleOpen",
-    value: function handleOpen(t) {
-      var e, s;
-      this.reconnectAttempts = 0, this.lastHeartbeatAck = true, this.setState("open"), (s = (e = this.options).onOpen) == null || s.call(e, t), this.startHeartbeat();
+    value: function handleOpen(e, t) {
+      var s, i;
+      this.isCurrentSocket(e) && (this.reconnectAttempts = 0, this.setState("open"), (i = (s = this.options).onOpen) == null || i.call(s, t), this.startHeartbeat());
     }
   }, {
     key: "handleMessage",
-    value: function handleMessage(t) {
-      var e, s, r, n, o;
-      if (T(t.data, (e = this.options.heartbeat) == null ? undefined : e.response)) {
-        this.lastHeartbeatAck = true, this.clearHeartbeatTimeoutTimer();
-        return;
-      }
-      try {
-        var a = this.options.parser || b;
-        (r = (s = this.options).onMessage) == null || r.call(s, a(t), t);
-      } catch (a) {
-        (o = (n = this.options).onInvalidMessage) == null || o.call(n, a, t);
+    value: function handleMessage(e, t) {
+      var s, i, o, r, a;
+      if (this.isCurrentSocket(e)) {
+        if (b(t.data, (s = this.options.heartbeat) == null ? undefined : s.response)) {
+          this.clearHeartbeatTimeoutTimer();
+          return;
+        }
+        try {
+          var h = this.options.parser || k;
+          (o = (i = this.options).onMessage) == null || o.call(i, h(t), t);
+        } catch (h) {
+          (a = (r = this.options).onInvalidMessage) == null || a.call(r, h, t);
+        }
       }
     }
   }, {
     key: "handleClose",
-    value: function handleClose(t) {
-      var e, s;
-      if (this.clearHeartbeatTimers(), (s = (e = this.options).onClose) == null || s.call(e, t), this.manualClosed) {
-        this.setState("closed");
-        return;
+    value: function handleClose(e, t) {
+      var s, i;
+      if (this.isCurrentSocket(e)) {
+        if (this.clearHeartbeatTimers(), this.ws = null, (i = (s = this.options).onClose) == null || i.call(s, t), this.manualClosed) {
+          this.setState("closed");
+          return;
+        }
+        this.scheduleReconnect();
       }
-      this.scheduleReconnect();
     }
   }, {
     key: "handleError",
-    value: function handleError(t) {
-      var e, s;
-      (s = (e = this.options).onError) == null || s.call(e, t);
+    value: function handleError(e, t) {
+      var s, i;
+      this.isCurrentSocket(e) && ((i = (s = this.options).onError) == null || i.call(s, t));
     }
+    /** 启动单实例心跳；等待应答期间不重复发送，避免 interval 与 timeout 竞争。 */
   }, {
     key: "startHeartbeat",
     value: function startHeartbeat() {
       var _this2 = this;
-      var t = this.options.heartbeat;
-      !(t != null && t.message) || !t.interval || (this.clearHeartbeatTimers(), this.heartbeatTimer = setInterval(function () {
-        if (!_this2.ws || _this2.ws.readyState !== WebSocket.OPEN) return;
-        if (t.timeout && !_this2.lastHeartbeatAck) {
-          _this2.closeSocket(), _this2.scheduleReconnect();
+      var e = this.options.heartbeat,
+        t = Number(e == null ? undefined : e.interval);
+      if (!(e != null && e.message) || !c(t)) return;
+      var s = Number(e.timeout),
+        i = w(e.response) && c(s);
+      this.clearHeartbeatTimers(), this.heartbeatTimer = setInterval(function () {
+        var o = _this2.ws;
+        if (!o || o.readyState !== WebSocket.OPEN || i && _this2.heartbeatTimeoutTimer !== null) return;
+        var r;
+        try {
+          r = typeof e.message == "function" ? e.message() : e.message;
+        } catch (_unused3) {
+          _this2.handleHeartbeatFailure(o);
+          return;
+        }
+        if (!_this2.send(r)) {
+          _this2.handleHeartbeatFailure(o);
           return;
         }
-        var e = typeof t.message == "function" ? t.message() : t.message;
-        _this2.lastHeartbeatAck = false, _this2.send(e), t.timeout && (_this2.clearHeartbeatTimeoutTimer(), _this2.heartbeatTimeoutTimer = setTimeout(function () {
-          _this2.lastHeartbeatAck || _this2.manualClosed || (_this2.closeSocket(), _this2.scheduleReconnect());
-        }, t.timeout));
-      }, t.interval));
+        if (!i) return;
+        _this2.clearHeartbeatTimeoutTimer();
+        var a = _this2.heartbeatSequence;
+        _this2.heartbeatTimeoutTimer = setTimeout(function () {
+          _this2.heartbeatSequence !== a || _this2.manualClosed || !_this2.isCurrentSocket(o) || _this2.handleHeartbeatFailure(o);
+        }, s);
+      }, t);
+    }
+    /** 心跳发送或应答超时后，仅关闭当前连接并进入既有重连流程。 */
+  }, {
+    key: "handleHeartbeatFailure",
+    value: function handleHeartbeatFailure(e) {
+      this.manualClosed || !this.isCurrentSocket(e) || (this.clearHeartbeatTimers(), this.closeSocket(), this.scheduleReconnect());
     }
   }, {
     key: "scheduleReconnect",
     value: function scheduleReconnect() {
       var _this3 = this;
-      var t = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "reconnecting";
-      var n;
-      if (this.manualClosed || !((n = this.options.reconnect) != null && n.enabled)) {
+      var e = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : "reconnecting";
+      var o;
+      if (this.manualClosed || !((o = this.options.reconnect) != null && o.enabled)) {
         this.setState("closed");
         return;
       }
       if ((typeof navigator === "undefined" ? "undefined" : _typeof(navigator)) < "u" && navigator.onLine === false) {
-        this.setState(t);
+        this.setState(e);
+        return;
+      }
+      if (this.reconnectTimer) {
+        this.setState(e);
         return;
       }
       var _this$options$reconne = this.options.reconnect,
-        e = _this$options$reconne.maxAttempts,
+        t = _this$options$reconne.maxAttempts,
         s = _this$options$reconne.jitter;
-      if (typeof e == "number" && e >= 0 && this.reconnectAttempts >= e) {
+      if (typeof t == "number" && t >= 0 && this.reconnectAttempts >= t) {
         this.setState("closed");
         return;
       }
       this.reconnectAttempts += 1;
-      var r = this.getReconnectDelay();
-      this.setState(t), this.clearReconnectTimer(), this.reconnectTimer = setTimeout(function () {
-        if (s) {
-          setTimeout(function () {
-            return _this3.openSocket();
-          }, Math.floor(Math.random() * 300));
-          return;
-        }
-        _this3.openSocket();
-      }, r);
+      var i = this.getReconnectDelay();
+      this.setState(e), this.clearReconnectTimer(), this.reconnectTimer = setTimeout(function () {
+        _this3.reconnectTimer = null, _this3.openSocket();
+      }, i + (s ? Math.floor(Math.random() * 300) : 0));
     }
   }, {
     key: "getReconnectDelay",
     value: function getReconnectDelay() {
-      var t = this.options.reconnect || {
+      var e = this.options.reconnect || {
           enabled: false
         },
-        e = t.delay || l,
-        s = t.maxDelay || u;
-      return Math.min(e * Math.pow(2, Math.max(0, this.reconnectAttempts - 1)), s);
+        t = e.delay || m,
+        s = e.maxDelay || d;
+      return Math.min(t * Math.pow(2, Math.max(0, this.reconnectAttempts - 1)), s);
     }
   }, {
     key: "handleOnline",
     value: function handleOnline() {
-      !this.started || this.manualClosed || this.state === "open" || this.state === "connecting" || this.openSocket();
+      !this.started || this.manualClosed || this.opening || this.state === "open" || this.state === "connecting" || this.openSocket();
     }
   }, {
     key: "handleOffline",
     value: function handleOffline() {
-      this.manualClosed || (this.clearReconnectTimer(), this.closeSocket(), this.setState("reconnecting"));
+      this.manualClosed || (this.cancelPendingOpen(), this.clearTimers(), this.closeSocket(), this.setState("reconnecting"));
     }
   }, {
     key: "setState",
-    value: function setState(t) {
-      var e, s;
-      this.state !== t && (this.state = t, (s = (e = this.options).onStateChange) == null || s.call(e, t));
+    value: function setState(e) {
+      var t, s;
+      this.state !== e && (this.state = e, (s = (t = this.options).onStateChange) == null || s.call(t, e));
     }
   }, {
     key: "closeSocket",
     value: function closeSocket() {
-      var t = this.ws;
-      t && (t.onopen = null, t.onmessage = null, t.onclose = null, t.onerror = null, (t.readyState === WebSocket.OPEN || t.readyState === WebSocket.CONNECTING) && t.close(), this.ws = null);
+      var e = this.ws;
+      e && (e.onopen = null, e.onmessage = null, e.onclose = null, e.onerror = null, (e.readyState === WebSocket.OPEN || e.readyState === WebSocket.CONNECTING) && e.close(), this.ws = null);
+    }
+  }, {
+    key: "cancelPendingOpen",
+    value: function cancelPendingOpen() {
+      this.openVersion += 1, this.opening = false;
+    }
+  }, {
+    key: "isCurrentOpen",
+    value: function isCurrentOpen(e) {
+      return this.started && !this.manualClosed && this.openVersion === e;
+    }
+  }, {
+    key: "isCurrentSocket",
+    value: function isCurrentSocket(e) {
+      return this.ws === e;
     }
   }, {
     key: "clearTimers",
@@ -314,12 +390,12 @@ var S = /*#__PURE__*/function () {
   }, {
     key: "clearHeartbeatTimers",
     value: function clearHeartbeatTimers() {
-      this.heartbeatTimer && clearInterval(this.heartbeatTimer), this.heartbeatTimer = null, this.clearHeartbeatTimeoutTimer();
+      this.heartbeatTimer !== null && clearInterval(this.heartbeatTimer), this.heartbeatTimer = null, this.clearHeartbeatTimeoutTimer();
     }
   }, {
     key: "clearHeartbeatTimeoutTimer",
     value: function clearHeartbeatTimeoutTimer() {
-      this.heartbeatTimeoutTimer && clearTimeout(this.heartbeatTimeoutTimer), this.heartbeatTimeoutTimer = null;
+      this.heartbeatSequence += 1, this.heartbeatTimeoutTimer !== null && clearTimeout(this.heartbeatTimeoutTimer), this.heartbeatTimeoutTimer = null;
     }
   }, {
     key: "clearReconnectTimer",
@@ -333,8 +409,8 @@ var S = /*#__PURE__*/function () {
     }
   }]);
 }();
-var g = function g(i) {
-  return new S(i);
+var A = function A(n) {
+  return new y(n);
 };
-exports.RealtimeSocketClient = S;
-exports.createRealtimeSocketClient = g;
+exports.RealtimeSocketClient = y;
+exports.createRealtimeSocketClient = A;

package/realtime-connection/index.d.ts

@@ -1,8 +1,11 @@
 export type RealtimeSocketState = 'idle' | 'waiting-token' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'unsupported';
 export type RealtimeSocketHeartbeatOptions = {
     message: string | (() => string);
+    /** 心跳间隔（毫秒），仅接受浏览器定时器支持范围内的正数。 */
     interval: number;
+    /** 等待 response 的超时时间（毫秒）；未配置 response 时不启用应答超时。 */
     timeout?: number;
+    /** 服务端心跳响应内容，可配置一个或多个精确匹配值。 */
     response?: string | string[];
 };
 export type RealtimeSocketReconnectOptions = {
@@ -37,7 +40,9 @@ export declare class RealtimeSocketClient<T = unknown> {
     private reconnectAttempts;
     private manualClosed;
     private started;
-    private lastHeartbeatAck;
+    private opening;
+    private openVersion;
+    private heartbeatSequence;
     constructor(options: RealtimeSocketClientOptions<T>);
     /** 获取当前连接状态，供业务显示或调试兜底使用。 */
     getState(): RealtimeSocketState;
@@ -53,13 +58,19 @@ export declare class RealtimeSocketClient<T = unknown> {
     private handleMessage;
     private handleClose;
     private handleError;
+    /** 启动单实例心跳；等待应答期间不重复发送，避免 interval 与 timeout 竞争。 */
     private startHeartbeat;
+    /** 心跳发送或应答超时后，仅关闭当前连接并进入既有重连流程。 */
+    private handleHeartbeatFailure;
     private scheduleReconnect;
     private getReconnectDelay;
     private handleOnline;
     private handleOffline;
     private setState;
     private closeSocket;
+    private cancelPendingOpen;
+    private isCurrentOpen;
+    private isCurrentSocket;
     private clearTimers;
     private clearHeartbeatTimers;
     private clearHeartbeatTimeoutTimer;