starknet 10.6.6 → 10.6.8

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [10.6.8](https://github.com/starknet-io/starknet.js/compare/v10.6.7...v10.6.8) (2026-08-07)
+
+### Bug Fixes
+
+- **ws:** close the subscription lifecycle races ([c242c76](https://github.com/starknet-io/starknet.js/commit/c242c76ab73f508ecd454d1d7eb2fde8728c4f9d))
+
+## [10.6.7](https://github.com/starknet-io/starknet.js/compare/v10.6.6...v10.6.7) (2026-08-06)
+
+### Bug Fixes
+
+- **ws:** settle in-flight requests when the connection drops ([8eae9c9](https://github.com/starknet-io/starknet.js/commit/8eae9c9457befe6e0c3f4fd30a56025fe5455fd8))
+
 ## [10.6.6](https://github.com/starknet-io/starknet.js/compare/v10.6.5...v10.6.6) (2026-08-05)
 
 ### Bug Fixes

package/dist/index.d.ts

@@ -4962,6 +4962,7 @@ declare class Subscription<T = any> {
     private maxBufferSize;
     private handler;
     private _isClosed;
+    private pendingUnsubscribe;
     /**
      * @internal
      * @param options - Subscription configuration options
@@ -4972,6 +4973,15 @@ declare class Subscription<T = any> {
      * @returns {boolean} `true` if unsubscribed, `false` otherwise.
      */
     get isClosed(): boolean;
+    /**
+     * Closes the subscription locally, without contacting the node.
+     *
+     * Used when the channel knows the subscription is gone and cannot be recovered — a
+     * re-subscribe refused after a reconnection, for instance. Without it the object would keep
+     * reporting itself as open while no event could ever reach its handler again.
+     * @internal
+     */
+    _markClosed(): void;
     /**
      * Internal method to handle incoming events from the WebSocket channel.
      * If a handler is attached, it's invoked immediately. Otherwise, the event is buffered.
@@ -5151,6 +5161,17 @@ declare class WebSocketChannel {
     private reconnectTimeoutId;
     private reconnectStabilityTimeoutId;
     private requestQueue;
+    /** Abort handles for the requests currently on the wire, one per pending `sendReceive`. */
+    private inFlight;
+    /**
+     * Callers blocked in `waitForUnsubscription`, keyed by subscription id.
+     *
+     * Held here rather than as `unsubscribe` event listeners because that event only ever
+     * announces success: a waiter attached to it cannot learn that the node refused the
+     * unsubscribe or that the connection went away, and would wait forever with no timeout of
+     * its own to fall back on.
+     */
+    private unsubscribeWaiters;
     private events;
     private openListener;
     private closeListener;
@@ -5226,6 +5247,15 @@ declare class WebSocketChannel {
      * @returns {Promise<boolean>} A Promise that resolves with `true` if the unsubscription was successful.
      */
     unsubscribe(subscriptionId: SUBSCRIPTION_ID): Promise<boolean>;
+    /** Settles every caller waiting on one subscription id: resolved, or rejected with `error`. */
+    private _settleUnsubscribeWaiters;
+    /**
+     * Rejects every caller still waiting on any subscription.
+     *
+     * Once the connection is gone, no unsubscribe can be observed on it: a reconnection restores
+     * each subscription under a fresh id, so the id being waited on will never be announced.
+     */
+    private _rejectUnsubscribeWaiters;
     /**
      * Returns a Promise that resolves when a specific subscription is successfully unsubscribed.
      * @param {SUBSCRIPTION_ID} targetId - The ID of the subscription to wait for.
@@ -5253,6 +5283,15 @@ declare class WebSocketChannel {
      * could rescue them. Settling them here is the only way out.
      */
     private _rejectRequestQueue;
+    /**
+     * Settle every request already on the wire.
+     *
+     * The counterpart of `_rejectRequestQueue`, for requests past the queue. Their only other
+     * exit is the `requestTimeout` timer, so without this the caller waits the whole timeout —
+     * 60s by default — for a reply that can no longer arrive, and that pending timer keeps the
+     * Node event loop alive for just as long.
+     */
+    private _rejectInFlight;
     private _restoreSubscriptions;
     /**
      * Reset the reconnection attempt counter, but only once the current connection has

package/dist/index.global.js

@@ -12516,6 +12516,8 @@ ${indent}}` : "}";
     maxBufferSize;
     handler = null;
     _isClosed = false;
+    // The unsubscribe request currently on the wire, shared by concurrent callers.
+    pendingUnsubscribe = null;
     /**
      * @internal
      * @param options - Subscription configuration options
@@ -12534,6 +12536,20 @@ ${indent}}` : "}";
     get isClosed() {
       return this._isClosed;
     }
+    /**
+     * Closes the subscription locally, without contacting the node.
+     *
+     * Used when the channel knows the subscription is gone and cannot be recovered — a
+     * re-subscribe refused after a reconnection, for instance. Without it the object would keep
+     * reporting itself as open while no event could ever reach its handler again.
+     * @internal
+     */
+    _markClosed() {
+      if (this._isClosed) return;
+      this._isClosed = true;
+      this.events.emit("unsubscribe", void 0);
+      this.events.clear();
+    }
     /**
      * Internal method to handle incoming events from the WebSocket channel.
      * If a handler is attached, it's invoked immediately. Otherwise, the event is buffered.
@@ -12580,14 +12596,24 @@ ${indent}}` : "}";
       if (this._isClosed) {
         return true;
       }
-      const success = await this.channel.unsubscribe(this.id);
-      if (success) {
-        this._isClosed = true;
-        this.channel.removeSubscription(this.id);
-        this.events.emit("unsubscribe", void 0);
-        this.events.clear();
+      if (this.pendingUnsubscribe) {
+        return this.pendingUnsubscribe;
       }
-      return success;
+      this.pendingUnsubscribe = (async () => {
+        try {
+          const success = await this.channel.unsubscribe(this.id);
+          if (success) {
+            this._isClosed = true;
+            this.channel.removeSubscription(this.id);
+            this.events.emit("unsubscribe", void 0);
+            this.events.clear();
+          }
+          return success;
+        } finally {
+          this.pendingUnsubscribe = null;
+        }
+      })();
+      return this.pendingUnsubscribe;
     }
   };
 
@@ -12618,6 +12644,17 @@ ${indent}}` : "}";
     // resetting the reconnection attempt counter.
     reconnectStabilityTimeoutId = null;
     requestQueue = [];
+    /** Abort handles for the requests currently on the wire, one per pending `sendReceive`. */
+    inFlight = /* @__PURE__ */ new Set();
+    /**
+     * Callers blocked in `waitForUnsubscription`, keyed by subscription id.
+     *
+     * Held here rather than as `unsubscribe` event listeners because that event only ever
+     * announces success: a waiter attached to it cannot learn that the node refused the
+     * unsubscribe or that the connection went away, and would wait forever with no timeout of
+     * its own to fall back on.
+     */
+    unsubscribeWaiters = /* @__PURE__ */ new Map();
     events = new EventEmitter();
     openListener = (ev) => {
       this.scheduleReconnectAttemptsReset();
@@ -12701,12 +12738,19 @@ ${indent}}` : "}";
         });
       }
       const sendId = this.send(method, params);
+      const socket = this.websocket;
       return new Promise((resolve, reject) => {
-        let timeoutId;
-        if (!this.websocket || this.websocket.readyState !== ws_default.OPEN) {
+        if (socket.readyState !== ws_default.OPEN) {
           reject(new WebSocketNotConnectedError("WebSocket not available or not connected."));
           return;
         }
+        let timeoutId;
+        const settle = () => {
+          clearTimeout(timeoutId);
+          socket.removeEventListener("message", messageHandler);
+          socket.removeEventListener("error", errorHandler);
+          this.inFlight.delete(abort);
+        };
         const messageHandler = (event) => {
           if (!isString(event.data)) {
             logger.warn("WebSocket received non-string message data:", event.data);
@@ -12721,34 +12765,35 @@ ${indent}}` : "}";
             );
             return;
           }
-          if (message.id === sendId) {
-            clearTimeout(timeoutId);
-            this.websocket.removeEventListener("message", messageHandler);
-            this.websocket.removeEventListener("error", errorHandler);
-            if ("result" in message) {
-              resolve(message.result);
-            } else {
-              reject(
-                new Error(`Error on ${method} (id: ${sendId}): ${JSON.stringify(message.error)}`)
-              );
-            }
+          if (message.id !== sendId) return;
+          settle();
+          if ("result" in message) {
+            resolve(message.result);
+          } else {
+            reject(new Error(`Error on ${method} (id: ${sendId}): ${JSON.stringify(message.error)}`));
           }
         };
         const errorHandler = (event) => {
-          clearTimeout(timeoutId);
-          this.websocket.removeEventListener("message", messageHandler);
-          this.websocket.removeEventListener("error", errorHandler);
+          settle();
           reject(
             new Error(
               `WebSocket error during ${method} (id: ${sendId}): ${event.type || "Unknown error"}`
             )
           );
         };
-        this.websocket.addEventListener("message", messageHandler);
-        this.websocket.addEventListener("error", errorHandler);
+        const abort = (reason) => {
+          settle();
+          reject(
+            new WebSocketNotConnectedError(
+              `Request ${method} (id: ${sendId}) went unanswered: ${reason}`
+            )
+          );
+        };
+        socket.addEventListener("message", messageHandler);
+        socket.addEventListener("error", errorHandler);
+        this.inFlight.add(abort);
         timeoutId = setTimeout(() => {
-          this.websocket.removeEventListener("message", messageHandler);
-          this.websocket.removeEventListener("error", errorHandler);
+          settle();
           reject(
             new TimeoutError(
               `Request ${method} (id: ${sendId}) timed out after ${this.requestTimeout}ms`
@@ -12805,6 +12850,8 @@ ${indent}}` : "}";
       this.userInitiatedClose = true;
       this.isReconnecting = false;
       this._rejectRequestQueue("the connection was closed by the user");
+      this._rejectInFlight("the connection was closed by the user");
+      this._rejectUnsubscribeWaiters("the connection was closed by the user");
       this.websocket.close(code, reason);
     }
     /**
@@ -12829,14 +12876,48 @@ ${indent}}` : "}";
      * @returns {Promise<boolean>} A Promise that resolves with `true` if the unsubscription was successful.
      */
     async unsubscribe(subscriptionId) {
-      const status = await this.sendReceive("starknet_unsubscribe", {
-        subscription_id: subscriptionId
-      });
+      let status;
+      try {
+        status = await this.sendReceive("starknet_unsubscribe", {
+          subscription_id: subscriptionId
+        });
+      } catch (error) {
+        this._settleUnsubscribeWaiters(subscriptionId, error);
+        throw error;
+      }
       if (status) {
         this.events.emit("unsubscribe", subscriptionId);
+        this._settleUnsubscribeWaiters(subscriptionId);
+      } else {
+        this._settleUnsubscribeWaiters(
+          subscriptionId,
+          new Error(`Node refused to unsubscribe subscription ${subscriptionId}`)
+        );
       }
       return status;
     }
+    /** Settles every caller waiting on one subscription id: resolved, or rejected with `error`. */
+    _settleUnsubscribeWaiters(subscriptionId, error) {
+      const waiters = this.unsubscribeWaiters.get(subscriptionId);
+      if (!waiters) return;
+      this.unsubscribeWaiters.delete(subscriptionId);
+      waiters.forEach((waiter) => error ? waiter.reject(error) : waiter.resolve());
+    }
+    /**
+     * Rejects every caller still waiting on any subscription.
+     *
+     * Once the connection is gone, no unsubscribe can be observed on it: a reconnection restores
+     * each subscription under a fresh id, so the id being waited on will never be announced.
+     */
+    _rejectUnsubscribeWaiters(reason) {
+      if (this.unsubscribeWaiters.size === 0) return;
+      Array.from(this.unsubscribeWaiters.keys()).forEach(
+        (id) => this._settleUnsubscribeWaiters(
+          id,
+          new WebSocketNotConnectedError(`Subscription ${id} was never unsubscribed: ${reason}`)
+        )
+      );
+    }
     /**
      * Returns a Promise that resolves when a specific subscription is successfully unsubscribed.
      * @param {SUBSCRIPTION_ID} targetId - The ID of the subscription to wait for.
@@ -12848,14 +12929,10 @@ ${indent}}` : "}";
      * ```
      */
     waitForUnsubscription(targetId) {
-      return new Promise((resolve) => {
-        const listener = (unsubId) => {
-          if (unsubId === targetId) {
-            this.events.off("unsubscribe", listener);
-            resolve();
-          }
-        };
-        this.events.on("unsubscribe", listener);
+      return new Promise((resolve, reject) => {
+        const waiters = this.unsubscribeWaiters.get(targetId) ?? /* @__PURE__ */ new Set();
+        waiters.add({ resolve, reject });
+        this.unsubscribeWaiters.set(targetId, waiters);
       });
     }
     /**
@@ -12896,6 +12973,21 @@ ${indent}}` : "}";
         reject(new WebSocketNotConnectedError(`Request ${method} was never sent: ${reason}`));
       });
     }
+    /**
+     * Settle every request already on the wire.
+     *
+     * The counterpart of `_rejectRequestQueue`, for requests past the queue. Their only other
+     * exit is the `requestTimeout` timer, so without this the caller waits the whole timeout —
+     * 60s by default — for a reply that can no longer arrive, and that pending timer keeps the
+     * Node event loop alive for just as long.
+     */
+    _rejectInFlight(reason) {
+      if (this.inFlight.size === 0) return;
+      const pending = Array.from(this.inFlight);
+      this.inFlight.clear();
+      logger.info(`WebSocket: Rejecting ${pending.length} in-flight request(s). Reason: ${reason}.`);
+      pending.forEach((abort) => abort(reason));
+    }
     async _restoreSubscriptions() {
       const oldSubscriptions = Array.from(this.activeSubscriptions.values());
       this.activeSubscriptions.clear();
@@ -12907,6 +12999,7 @@ ${indent}}` : "}";
           logger.info(`Subscription ${sub.method} restored with new ID: ${newSubId}`);
         } catch (error) {
           logger.error(`Failed to restore subscription ${sub.method}:`, error);
+          sub._markClosed();
         }
       });
       await Promise.all(restorePromises);
@@ -12949,18 +13042,24 @@ ${indent}}` : "}";
           `WebSocket: Connection lost. Attempting to reconnect... (${this.reconnectAttempts}/${this.reconnectOptions.retries})`
         );
         this.reconnect();
+        let attemptSettled = false;
+        const scheduleRetry = () => {
+          if (attemptSettled || !this.isReconnecting) return;
+          attemptSettled = true;
+          const delay = this.reconnectOptions.exponential ? this.reconnectOptions.delay * 2 ** (this.reconnectAttempts - 1) : this.reconnectOptions.delay;
+          logger.info(`WebSocket: Reconnect attempt failed. Retrying in ${delay}ms.`);
+          this.reconnectTimeoutId = setTimeout(tryReconnect, delay);
+        };
         this.websocket.onopen = async () => {
           logger.info("WebSocket: Reconnection successful.");
+          attemptSettled = true;
           this.isReconnecting = false;
           await this._restoreSubscriptions();
           this._processRequestQueue();
           this.events.emit("open", new Event("open"));
         };
-        this.websocket.onerror = () => {
-          const delay = this.reconnectOptions.exponential ? this.reconnectOptions.delay * 2 ** (this.reconnectAttempts - 1) : this.reconnectOptions.delay;
-          logger.info(`WebSocket: Reconnect attempt failed. Retrying in ${delay}ms.`);
-          this.reconnectTimeoutId = setTimeout(tryReconnect, delay);
-        };
+        this.websocket.onerror = scheduleRetry;
+        this.websocket.addEventListener("close", scheduleRetry);
       };
       tryReconnect();
     }
@@ -12969,6 +13068,8 @@ ${indent}}` : "}";
       this.websocket.removeEventListener("close", this.closeListener);
       this.websocket.removeEventListener("message", this.messageListener);
       this.websocket.removeEventListener("error", this.errorListener);
+      this._rejectInFlight("the connection was closed");
+      this._rejectUnsubscribeWaiters("the connection was closed");
       this.events.emit("close", ev);
       if (!this.userInitiatedClose) {
         this._startReconnect();
@@ -12990,9 +13091,16 @@ ${indent}}` : "}";
         if (subscription) {
           subscription._handleEvent(result);
         } else {
-          logger.warn(
-            `WebSocketChannel: Received event for untracked subscription ID: ${subscription_id}.`
-          );
+          queueMicrotask(() => {
+            const registered = this.activeSubscriptions.get(subscription_id);
+            if (registered) {
+              registered._handleEvent(result);
+            } else {
+              logger.warn(
+                `WebSocketChannel: Received event for untracked subscription ID: ${subscription_id}.`
+              );
+            }
+          });
         }
       }
       logger.debug("onMessageProxy:", event.data);