starknet 10.6.7 → 10.6.8

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

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.
@@ -5153,6 +5163,15 @@ declare class WebSocketChannel {
     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;
@@ -5228,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.

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;
     }
   };
 
@@ -12620,6 +12646,15 @@ ${indent}}` : "}";
     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();
@@ -12816,6 +12851,7 @@ ${indent}}` : "}";
       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);
     }
     /**
@@ -12840,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.
@@ -12859,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);
       });
     }
     /**
@@ -12933,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);
@@ -13002,6 +13069,7 @@ ${indent}}` : "}";
       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();
@@ -13023,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);