@firebase/data-connect 0.6.1-20260505164105 → 0.7.0

package/dist/index.cjs.js

@@ -8,7 +8,7 @@ var util = require('@firebase/util');
 var logger$1 = require('@firebase/logger');
 
 const name = "@firebase/data-connect";
-const version = "0.6.1-20260505164105";
+const version = "0.7.0";
 
 /**
  * @license
@@ -1664,49 +1664,128 @@ class RESTTransport extends AbstractDataConnectTransport {
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/** The request id of the first request over the stream */
+/** The Request ID of the first request over the stream */
 const FIRST_REQUEST_ID = 1;
-/** Time to wait before closing an idle connection (no active subscriptions) */
+/** Time to wait before closing an idle connection (no active subscriptions). */
 const IDLE_CONNECTION_TIMEOUT_MS = 60 * 1000; // 1 minute
+/** Initial reconnect delay in ms */
+const INITIAL_RECONNECT_DELAY_MS = 1000;
+/** Max reconnect delay in ms */
+const MAX_RECONNECT_DELAY_MS = 30000;
+/** Max random jitter to add to reconnect delay in ms */
+const MAX_RECONNECT_JITTER_MS = 500;
+/** Factor to multiply delay by on failure */
+const RECONNECT_BACKOFF_FACTOR = 1.3;
+/** Max number of reconnection attempts before giving up */
+const MAX_RECONNECT_ATTEMPTS = 10;
 /**
- * The base class for all {@link DataConnectStreamTransport | Stream Transport} implementations.
- * Handles management of logical streams (requests), authentication, data routing to query layer, etc.
+ * The base class for all Stream Transport implementations.
+ * Handles management of logical streams (requests), authentication, data routing to query layer,
+ * request optimizations, etc.
  * @internal
  */
 class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
-    constructor() {
-        super(...arguments);
-        this.pendingClose = false;
+    /** Is the stream currently waiting to close connection? */
+    get isPendingClose() {
+        return !!this.idleTimeout;
+    }
+    /** True if there are active subscriptions on the stream */
+    get hasActiveSubscriptions() {
+        return this.activeInvokeSubscribeRequests.size > 0;
+    }
+    /** True if there are active execute or mutation requests on the stream */
+    get hasActiveExecuteRequests() {
+        return (this.activeInvokeQueryRequests.size > 0 ||
+            this.activeInvokeMutationRequests.size > 0);
+    }
+    constructor(options, apiKey, appId, authProvider, appCheckProvider, transportOptions, _isUsingGen = false, _callerSdkType = CallerSdkTypeEnum.Base) {
+        super(options, apiKey, appId, authProvider, appCheckProvider, transportOptions, _isUsingGen, _callerSdkType);
+        this.apiKey = apiKey;
+        this.appId = appId;
+        this.authProvider = authProvider;
+        this.appCheckProvider = appCheckProvider;
+        this._isUsingGen = _isUsingGen;
+        this._callerSdkType = _callerSdkType;
         /** True if the transport is unable to connect to the server */
         this.isUnableToConnect = false;
-        /** The request ID of the next message to be sent. Monotonically increasing sequence number. */
+        /** The Request ID of the next message to be sent. Monotonically increasing sequence number starting at {@linkcode FIRST_REQUEST_ID}. */
         this.requestNumber = FIRST_REQUEST_ID;
         /**
-         * Map of query/variables to their active execute/resume request bodies.
+         * Map of query/variables to their active {@linkcode ExecuteStreamRequest} or {@linkcode ResumeStreamRequest}
+         * request bodies. These requests are de-duplicated by query/variables so that there is only one active
+         * request for each query/variables combination.
          */
-        this.activeQueryExecuteRequests = new Map();
+        this.activeInvokeQueryRequests = new Map();
         /**
-         * Map of mutation/variables to their active execute request bodies.
+         * Map of query/variables to the promises returned to the user, for invokeQuery requests which are
+         * queued and waiting for active request to resolve.
          */
-        this.activeMutationExecuteRequests = new Map();
+        this.queuedInvokeQueryRequests = new Map();
         /**
-         * Map of query/variables to their active subscribe request bodies.
+         * Map of mutation/variables to their active {@linkcode ExecuteStreamRequest} request bodies. Mutations
+         * can have more than one active request at a time as they are not idempotent, and therefore should
+         * not be de-duplicated.
          */
-        this.activeSubscribeRequests = new Map();
+        this.activeInvokeMutationRequests = new Map();
         /**
-         * Map of active execution RequestIds and their corresponding Promises and resolvers.
+         * Map of query/variables to their active {@linkcode SubscribeStreamRequest} request bodies. There
+         * may only be one active request for each query/variables combination.
+         */
+        this.activeInvokeSubscribeRequests = new Map();
+        /**
+         * Map of active {@linkcode ExecuteStreamRequest} RequestIds from {@linkcode invokeQuery} and {@linkcode invokeMutation},
+         * and their corresponding {@linkcode InvokeOperationPromise}.
          */
         this.executeRequestPromises = new Map();
         /**
-         * Map of active subscription RequestIds and their corresponding observers.
+         * Map of active {@linkcode ResumeStreamRequest} RequestIds from {@linkcode invokeQuery}, and their
+         * corresponding {@linkcode InvokeOperationPromise}.
+         */
+        this.resumeRequestPromises = new Map();
+        /**
+         * Map of active {@linkcode invokeSubscribe} RequestIds and their corresponding {@linkcode SubscribeObserver}.
          */
         this.subscribeObservers = new Map();
-        /** current close timeout from setTimeout(), if any */
-        this.closeTimeout = null;
-        /** has the close timeout finished? */
-        this.closeTimeoutFinished = false;
+        /**
+         * Map of subscribe RequestIds to deferred unsubscription requests. Used when a client unsubscribes
+         * while a resume request is actively pending.
+         */
+        this.pendingCancellations = new Map();
+        /** current idle timeout, if any */
+        this.idleTimeout = null;
         /** Flag to ensure we wait for the initial auth state once per connection attempt. */
         this.hasWaitedForInitialAuth = false;
+        /** Delay for next reconnection attempt in ms */
+        this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+        /** Timer for reconnection */
+        this.reconnectTimer = null;
+        /** Number of consecutive reconnection attempts */
+        this.reconnectAttempts = 0;
+        /** Callback to remove online event listener */
+        this.removeOnlineEventListener = null;
+        /** Callback to remove visibility change event listener */
+        this.removeVisibilityChangeEventListener = null;
+        /**
+         * Short-circuit a reconnection attempt, if one is pending. Triggered when an online event is
+         * dispatched.
+         */
+        this.onOnlineEventListener = () => {
+            if (this.reconnectTimer) {
+                this.cancelReconnect();
+                void this.attemptReconnect();
+            }
+        };
+        /**
+         * Short-circuit a reconnection attempt, if one is pending. Triggered when a visibility change
+         * event is dispatched.
+         */
+        this.onVisibilityChangeEventListener = () => {
+            const doc = globalThis.document;
+            if (doc && doc.visibilityState === 'visible' && this.reconnectTimer) {
+                this.cancelReconnect();
+                void this.attemptReconnect();
+            }
+        };
         /**
          * Tracks if the next message to be sent is the first message of the stream.
          */
@@ -1716,62 +1795,62 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
          * Used to detect if the token has changed and needs to be resent.
          */
         this.lastSentAuthToken = null;
+        this.registerBrowserEventListeners();
     }
-    /** Is the stream currently waiting to close connection? */
-    get isPendingClose() {
-        return this.pendingClose;
-    }
-    /** True if there are active subscriptions on the stream */
-    get hasActiveSubscriptions() {
-        return this.activeSubscribeRequests.size > 0;
+    /**
+     * Register event listeners for browser-specific events like online/offline and visibility changes.
+     */
+    registerBrowserEventListeners() {
+        if ('addEventListener' in globalThis) {
+            const listener = this.onOnlineEventListener;
+            globalThis.addEventListener('online', listener);
+            this.removeOnlineEventListener = () => globalThis.removeEventListener('online', listener);
+        }
+        const doc = globalThis.document;
+        if (doc && 'addEventListener' in doc) {
+            const listener = this.onVisibilityChangeEventListener;
+            doc.addEventListener('visibilitychange', listener);
+            this.removeVisibilityChangeEventListener = () => doc.removeEventListener('visibilitychange', listener);
+        }
     }
-    /** True if there are active execute or mutation requests on the stream */
-    get hasActiveExecuteRequests() {
-        return (this.activeQueryExecuteRequests.size > 0 ||
-            this.activeMutationExecuteRequests.size > 0);
+    /**
+     * Remove event listeners registered by {@linkcode AbstractDataConnectStreamTransport.registerBrowserEventListeners | registerBrowserEventListeners()}
+     * for browser-specific events like online/offline and visibility changes.
+     */
+    cleanupBrowserEventListeners() {
+        this.removeVisibilityChangeEventListener?.();
+        this.removeVisibilityChangeEventListener = null;
+        this.removeOnlineEventListener?.();
+        this.removeOnlineEventListener = null;
     }
     /**
-     * Generates and returns the next request ID.
+     * Disposes of the transport instance, cleaning up event listeners and timers,
+     * and closing the connection.
      */
-    nextRequestId() {
-        return (this.requestNumber++).toString();
+    async cleanupAndTerminate(code, reason) {
+        this.cleanupBrowserEventListeners();
+        this.cancelReconnect();
+        this.cancelClose();
+        this.rejectAllRequests(code ?? Code.OTHER, reason ?? 'Stream disposed.');
+        await this.closeConnection();
+        this.onCloseCallback?.();
     }
     /**
-     * Tracks a query execution request, storing the request body and creating and storing a promise that
-     * will be resolved when the response is received.
-     * @returns The reject function and the response promise.
-     *
-     * @remarks
-     * This method returns a promise, but is synchronous.
+     * Generates and returns the next Request ID. Starts at {@linkcode FIRST_REQUEST_ID} and increments
+     * for each request sent.
      */
-    trackQueryExecuteRequest(requestId, mapKey, executeBody) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        let resolveFn;
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        let rejectFn;
-        const responsePromise = new Promise((resolve, reject) => {
-            resolveFn = resolve;
-            rejectFn = reject;
-        });
-        const executeRequestPromise = {
-            responsePromise,
-            resolveFn: resolveFn,
-            rejectFn: rejectFn
-        };
-        this.activeQueryExecuteRequests.set(mapKey, executeBody);
-        this.executeRequestPromises.set(requestId, executeRequestPromise);
-        return executeRequestPromise;
+    nextRequestId() {
+        return (this.requestNumber++).toString();
     }
     /**
-     * Tracks a mutation execution request, storing the request body and creating and storing a promise
-     * that will be resolved when the response is received.
-     * @returns The reject function and the response promise.
+     * Tracks an {@linkcode invokeMutation} request, storing the request body and creating and storing a
+     * response promise that will be resolved when the response is received.
+     * @returns The tracked {@linkcode InvokeOperationPromise}.
      *
      * @remarks
      * This method returns a promise, but is synchronous.
      */
-    trackMutationExecuteRequest(requestId, mapKey, executeBody) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    trackInvokeMutationRequest(requestId, mapKey, executeBody) {
         let resolveFn;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let rejectFn;
@@ -1784,42 +1863,43 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
             resolveFn: resolveFn,
             rejectFn: rejectFn
         };
-        const activeRequests = this.activeMutationExecuteRequests.get(mapKey) || [];
+        const activeRequests = this.activeInvokeMutationRequests.get(mapKey) || [];
         activeRequests.push(executeBody);
-        this.activeMutationExecuteRequests.set(mapKey, activeRequests);
+        this.activeInvokeMutationRequests.set(mapKey, activeRequests);
         this.executeRequestPromises.set(requestId, executeRequestPromise);
         return executeRequestPromise;
     }
     /**
-     * Tracks a subscribe request, storing the request body and the notification observer.
+     * Tracks an {@linkcode invokeSubscribe} request, storing the request body and the {@linkcode SubscribeObserver}.
      * @remarks
      * This method is synchronous.
      */
-    trackSubscribeRequest(requestId, mapKey, subscribeBody, observer) {
-        this.activeSubscribeRequests.set(mapKey, subscribeBody);
+    trackInvokeSubscribeRequest(requestId, mapKey, subscribeBody, observer) {
+        this.activeInvokeSubscribeRequests.set(mapKey, subscribeBody);
         this.subscribeObservers.set(requestId, observer);
     }
     /**
      * Cleans up the query execute request tracking data structures, deleting the tracked request and
      * it's associated promise.
      */
-    cleanupQueryExecuteRequest(requestId, mapKey) {
-        this.activeQueryExecuteRequests.delete(mapKey);
+    cleanupInvokeQueryRequest(requestId, mapKey) {
+        this.activeInvokeQueryRequests.delete(mapKey);
         this.executeRequestPromises.delete(requestId);
+        this.resumeRequestPromises.delete(requestId);
     }
     /**
      * Cleans up the mutation execute request tracking data structures, deleting the tracked request and
      * it's associated promise.
      */
-    cleanupMutationExecuteRequest(requestId, mapKey) {
-        const executeRequests = this.activeMutationExecuteRequests.get(mapKey);
+    cleanupInvokeMutationRequest(requestId, mapKey) {
+        const executeRequests = this.activeInvokeMutationRequests.get(mapKey);
         if (executeRequests) {
-            const updatedRequests = executeRequests.filter(req => req.requestId !== requestId);
+            const updatedRequests = executeRequests.filter(request => request.requestId !== requestId);
             if (updatedRequests.length > 0) {
-                this.activeMutationExecuteRequests.set(mapKey, updatedRequests);
+                this.activeInvokeMutationRequests.set(mapKey, updatedRequests);
             }
             else {
-                this.activeMutationExecuteRequests.delete(mapKey);
+                this.activeInvokeMutationRequests.delete(mapKey);
             }
         }
         this.executeRequestPromises.delete(requestId);
@@ -1828,10 +1908,72 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
      * Cleans up the subscribe request tracking data structures, deleting the tracked request and
      * it's associated promise.
      */
-    cleanupSubscribeRequest(requestId, mapKey) {
-        this.activeSubscribeRequests.delete(mapKey);
+    cleanupInvokeSubscribeRequest(requestId, mapKey) {
+        this.activeInvokeSubscribeRequests.delete(mapKey);
         this.subscribeObservers.delete(requestId);
     }
+    /**
+     * Cancel reconnecting.
+     */
+    cancelReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    /**
+     * Starts the backoff timer for reconnection attempts. We use an exponential backoff with randomized
+     * jitter to prevent overwhelming the backend with connection attempts.
+     */
+    startReconnectBackoff() {
+        if (this.reconnectTimer) {
+            return;
+        }
+        if (this.reconnectAttempts++ >= MAX_RECONNECT_ATTEMPTS) {
+            const errorString = 'Stream disconnected and could not reconnect - max stream reconnection attempts reached.';
+            logError(errorString);
+            void this.cleanupAndTerminate(Code.OTHER, errorString);
+            return;
+        }
+        const delay = this.reconnectDelayMs;
+        this.reconnectDelayMs = Math.min(this.reconnectDelayMs * RECONNECT_BACKOFF_FACTOR, MAX_RECONNECT_DELAY_MS);
+        const jitter = Math.random() * MAX_RECONNECT_JITTER_MS;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.attemptReconnect();
+        }, delay + jitter);
+    }
+    async attemptReconnect() {
+        try {
+            await this.ensureConnection();
+            // reset on success
+            this.reconnectDelayMs = INITIAL_RECONNECT_DELAY_MS;
+            this.reconnectAttempts = 0;
+            await this.retriggerActiveRequests();
+        }
+        catch (e) {
+            if (e instanceof util.FirebaseError) {
+                logDebug(`Reconnect attempt #${this.reconnectAttempts} failed with Firebase error: ${e.message}. Retrying...`);
+                this.startReconnectBackoff();
+            }
+            else {
+                logError(`Unexpected error during reconnect attempt #${this.reconnectAttempts}: ${e}`);
+                void this.cleanupAndTerminate(Code.OTHER, `Unexpected error during reconnect attempt #${this.reconnectAttempts}: ${e}`);
+            }
+        }
+    }
+    /**
+     * Retriggers all active requests on the stream connection - first subscribes, then query executions,
+     * and skip mutations. Used after a successful reconnection.
+     */
+    async retriggerActiveRequests() {
+        for (const [_, subscribeBody] of this.activeInvokeSubscribeRequests) {
+            await this.sendRequestMessage(subscribeBody);
+        }
+        for (const [_, requestBody] of this.activeInvokeQueryRequests) {
+            await this.sendRequestMessage(requestBody);
+        }
+    }
     /**
      * Indicates whether we should include the auth token in the next message.
      * Only true if there is an auth token and it is different from the last sent auth token, or this
@@ -1850,66 +1992,91 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
         this.hasWaitedForInitialAuth = false;
     }
     /**
-     * Attempt to close the connection. Will only close if there are no active requests preventing it
-     * from doing so.
+     * Begin closing the connection. Waits for {@linkcode IDLE_CONNECTION_TIMEOUT_MS} without cleaning up
+     * any requests (meaning it will not close after the timeout unless the requests are closed first).
+     * This is a graceful close - it will be called when there are no more active subscriptions, so
+     * there's no need to cleanup.
      */
-    async attemptClose() {
-        if (this.hasActiveSubscriptions || this.hasActiveExecuteRequests) {
+    startIdleCloseTimeout() {
+        if (this.idleTimeout) {
             return;
         }
-        this.cancelClose();
-        await this.closeConnection();
-        this.onGracefulStreamClose?.();
-    }
-    /**
-     * Begin closing the connection. Waits for and cleans up all active requests, and waits for
-     * {@link IDLE_CONNECTION_TIMEOUT_MS}. This is a graceful close - it will be called when there are
-     * no more active subscriptions, so there's no need to cleanup.
-     */
-    prepareToCloseGracefully() {
-        if (this.pendingClose) {
-            return;
-        }
-        this.pendingClose = true;
-        this.closeTimeoutFinished = false;
-        this.closeTimeout = setTimeout(() => {
-            this.closeTimeoutFinished = true;
-            void this.attemptClose();
+        this.idleTimeout = setTimeout(() => {
+            this.idleTimeout = null;
+            // Safety check: Don't close if new requests arrived during the timeout!
+            if (this.hasActiveSubscriptions || this.hasActiveExecuteRequests) {
+                return;
+            }
+            void this.cleanupAndTerminate(Code.OTHER, 'Stream closed due to idleness.');
         }, IDLE_CONNECTION_TIMEOUT_MS);
     }
     /**
      * Cancel closing the connection.
      */
     cancelClose() {
-        if (this.closeTimeout) {
-            clearTimeout(this.closeTimeout);
+        if (this.idleTimeout) {
+            clearTimeout(this.idleTimeout);
+            this.idleTimeout = null;
         }
-        this.pendingClose = false;
-        this.closeTimeoutFinished = false;
     }
     /**
      * Reject all active execute promises and notify all subscribe observers with the given error.
      * Clear active request tracking maps without cancelling or re-invoking any requests.
      */
-    rejectAllActiveRequests(code, reason) {
-        this.activeQueryExecuteRequests.clear();
-        this.activeMutationExecuteRequests.clear();
-        this.activeSubscribeRequests.clear();
+    rejectAllRequests(code, reason) {
+        this.activeInvokeQueryRequests.clear();
+        this.activeInvokeMutationRequests.clear();
+        this.activeInvokeSubscribeRequests.clear();
         const error = new DataConnectError(code, reason);
+        for (const [mapKey, { rejectFn }] of this.queuedInvokeQueryRequests) {
+            this.queuedInvokeQueryRequests.delete(mapKey);
+            rejectFn(error);
+        }
         for (const [requestId, { rejectFn }] of this.executeRequestPromises) {
             this.executeRequestPromises.delete(requestId);
             rejectFn(error);
         }
+        for (const [requestId, { rejectFn }] of this.resumeRequestPromises) {
+            this.resumeRequestPromises.delete(requestId);
+            rejectFn(error);
+        }
         for (const [requestId, observer] of this.subscribeObservers) {
             this.subscribeObservers.delete(requestId);
             observer.onDisconnect(code, reason);
         }
+        this.pendingCancellations.clear();
+        this.cancelReconnect();
+    }
+    /**
+     * Reject all mutation execute promises.
+     * Clear active request tracking maps without cancelling or re-invoking any requests.
+     */
+    rejectAllMutationsOnReconnect() {
+        const error = new DataConnectError(Code.OTHER, 'Mutation aborted due to stream disconnect.');
+        for (const [_, requests] of this.activeInvokeMutationRequests) {
+            for (const request of requests) {
+                const promise = this.executeRequestPromises.get(request.requestId);
+                if (promise) {
+                    promise.rejectFn(error);
+                    this.executeRequestPromises.delete(request.requestId);
+                }
+            }
+        }
+        this.activeInvokeMutationRequests.clear();
     }
     /**
      * Called by concrete implementations when the stream is successfully closed, gracefully or otherwise.
      */
     onStreamClose(code, reason) {
-        this.rejectAllActiveRequests(Code.OTHER, `Stream disconnected with code ${code}: ${reason}`);
+        this.cancelClose();
+        if (!this.hasActiveSubscriptions) {
+            // skip reconnection if there are no active subscriptions
+            void this.cleanupAndTerminate(Code.OTHER, `Stream disconnected while idle with code ${code}: ${reason}`);
+            return;
+        }
+        logDebug(`Stream disconnected with code ${code}: ${reason}. Attempting reconnect...`);
+        this.rejectAllMutationsOnReconnect();
+        this.startReconnectBackoff();
     }
     /**
      * Prepares a stream request message by adding necessary headers and metadata.
@@ -1941,7 +2108,6 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
         this.isFirstStreamMessage = false;
         return preparedRequestBody;
     }
-    // TODO(stephenarosaj): just make this async
     /**
      * Sends a request message to the server via the concrete implementation.
      * Ensures the connection is ready and prepares the message before sending.
@@ -1962,7 +2128,7 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
         });
     }
     /**
-     * Helper to generate a consistent string key for the tracking maps.
+     * Helper to generate a consistent string key for the request tracking maps.
      */
     getMapKey(operationName, variables) {
         const sortedVariables = this.sortObjectKeys(variables);
@@ -1991,28 +2157,114 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
      * preserves the synchronous update of the tracking data structures before the method returns.
      */
     invokeQuery(queryName, variables) {
-        const requestId = this.nextRequestId();
-        const activeRequestKey = { operationName: queryName, variables };
         const mapKey = this.getMapKey(queryName, variables);
-        const executeBody = {
-            requestId,
-            execute: activeRequestKey
-        };
-        let { responsePromise, rejectFn } = this.trackQueryExecuteRequest(requestId, mapKey, executeBody);
+        if (this.activeInvokeQueryRequests.has(mapKey)) {
+            return this.queueInvokeQueryRequest(mapKey);
+        }
+        return this.executeOrResumeQuery(queryName, variables, mapKey);
+    }
+    /**
+     * Queue a new query execute request to be executed after the currently active query execute
+     * request resolves, and track + return a promise associated with the queued request. If there is
+     * already a queued request for this mapKey, return the existing queued request's promise instead.
+     */
+    queueInvokeQueryRequest(mapKey) {
+        const existingQueued = this.queuedInvokeQueryRequests.get(mapKey);
+        if (existingQueued) {
+            // only queue one request per mapKey - return existing queued request promise
+            return existingQueued.responsePromise;
+        }
+        let resolveFn;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let rejectFn;
+        const responsePromise = new Promise((resolve, reject) => {
+            resolveFn = resolve;
+            rejectFn = reject;
+        });
+        this.queuedInvokeQueryRequests.set(mapKey, {
+            responsePromise,
+            resolveFn: resolveFn,
+            rejectFn: rejectFn
+        });
+        return responsePromise;
+    }
+    /**
+     * Executes or resumes a query. Does not check for any active requests which may be overwritten by
+     * this request - this should be handled by the caller.
+     */
+    executeOrResumeQuery(queryName, variables, mapKey, queuedInvokeOperationPromise) {
+        const activeSubscription = this.activeInvokeSubscribeRequests.get(mapKey);
+        let resolveFn;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let rejectFn;
+        let responsePromise;
+        // track the existing queued promise if one exists - otherwise create a new one
+        if (queuedInvokeOperationPromise) {
+            resolveFn = queuedInvokeOperationPromise.resolveFn;
+            rejectFn = queuedInvokeOperationPromise.rejectFn;
+            responsePromise = queuedInvokeOperationPromise.responsePromise;
+        }
+        else {
+            responsePromise = new Promise((resolve, reject) => {
+                resolveFn = resolve;
+                rejectFn = reject;
+            });
+        }
+        let requestId;
+        let requestBody;
+        if (activeSubscription) {
+            // resume!
+            requestId = activeSubscription.requestId;
+            requestBody = { requestId, resume: {} };
+            this.resumeRequestPromises.set(requestId, {
+                responsePromise,
+                resolveFn: resolveFn,
+                rejectFn: rejectFn
+            });
+        }
+        else {
+            // execute!
+            requestId = this.nextRequestId();
+            requestBody = {
+                requestId,
+                execute: { operationName: queryName, variables }
+            };
+            this.executeRequestPromises.set(requestId, {
+                responsePromise,
+                resolveFn: resolveFn,
+                rejectFn: rejectFn
+            });
+        }
+        this.activeInvokeQueryRequests.set(mapKey, requestBody);
         responsePromise = responsePromise.finally(() => {
-            this.cleanupQueryExecuteRequest(requestId, mapKey);
-            if (!this.hasActiveSubscriptions &&
-                !this.hasActiveExecuteRequests &&
-                this.closeTimeoutFinished) {
-                void this.attemptClose();
-            }
+            this.onInvokeQueryRequestFulfilled(queryName, variables, mapKey, requestId);
         });
-        // asynchronous, fire and forget
-        this.sendRequestMessage(executeBody).catch(err => {
+        this.sendRequestMessage(requestBody).catch(err => {
             rejectFn(err);
         });
         return responsePromise;
     }
+    /**
+     * When a query invoke request is fulfilled, clean up and trigger the next queued
+     * request if one exists.
+     */
+    onInvokeQueryRequestFulfilled(queryName, variables, mapKey, requestId) {
+        this.cleanupInvokeQueryRequest(requestId, mapKey);
+        const deferredCancel = this.pendingCancellations.get(requestId);
+        if (deferredCancel) {
+            this.pendingCancellations.delete(requestId);
+            this.cancelSubscription(requestId, mapKey);
+        }
+        const queuedRequestPromise = this.queuedInvokeQueryRequests.get(mapKey);
+        if (!queuedRequestPromise) {
+            if (!this.hasActiveSubscriptions && !this.hasActiveExecuteRequests) {
+                this.startIdleCloseTimeout();
+            }
+            return;
+        }
+        this.queuedInvokeQueryRequests.delete(mapKey);
+        void this.executeOrResumeQuery(queryName, variables, mapKey, queuedRequestPromise);
+    }
     /**
      * @inheritdoc
      * @remarks
@@ -2028,13 +2280,11 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
             requestId,
             execute: activeRequestKey
         };
-        let { responsePromise, rejectFn } = this.trackMutationExecuteRequest(requestId, mapKey, executeBody);
+        let { responsePromise, rejectFn } = this.trackInvokeMutationRequest(requestId, mapKey, executeBody);
         responsePromise = responsePromise.finally(() => {
-            this.cleanupMutationExecuteRequest(requestId, mapKey);
-            if (!this.hasActiveSubscriptions &&
-                !this.hasActiveExecuteRequests &&
-                this.closeTimeoutFinished) {
-                void this.attemptClose();
+            this.cleanupInvokeMutationRequest(requestId, mapKey);
+            if (!this.hasActiveSubscriptions && !this.hasActiveExecuteRequests) {
+                this.startIdleCloseTimeout();
             }
         });
         // asynchronous, fire and forget
@@ -2052,24 +2302,35 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
      * before the method returns.
      */
     invokeSubscribe(observer, queryName, variables) {
-        // if we are waiting to close the stream, cancel closing!
-        this.cancelClose();
-        const requestId = this.nextRequestId();
-        const activeRequestKey = { operationName: queryName, variables };
         const mapKey = this.getMapKey(queryName, variables);
-        const subscribeBody = {
-            requestId,
-            subscribe: activeRequestKey
-        };
-        this.trackSubscribeRequest(requestId, mapKey, subscribeBody, observer);
-        // asynchronous, fire and forget
-        this.sendRequestMessage(subscribeBody).catch(err => {
-            observer.onError(err instanceof Error ? err : new Error(String(err)));
-            this.cleanupSubscribeRequest(requestId, mapKey);
-            if (!this.hasActiveSubscriptions) {
-                this.prepareToCloseGracefully();
+        const existingSubscribe = this.activeInvokeSubscribeRequests.get(mapKey);
+        // if this query is pending cancellation, cancel the cancellation!
+        if (existingSubscribe) {
+            const requestId = existingSubscribe.requestId;
+            if (this.pendingCancellations.has(requestId)) {
+                this.pendingCancellations.delete(requestId);
+                this.subscribeObservers.set(requestId, observer);
             }
-        });
+        }
+        else {
+            const requestId = this.nextRequestId();
+            const activeRequestKey = { operationName: queryName, variables };
+            const subscribeBody = {
+                requestId,
+                subscribe: activeRequestKey
+            };
+            this.trackInvokeSubscribeRequest(requestId, mapKey, subscribeBody, observer);
+            // asynchronous, fire and forget
+            this.sendRequestMessage(subscribeBody).catch(err => {
+                observer.onError(err instanceof Error ? err : new Error(String(err)));
+                this.cleanupInvokeSubscribeRequest(requestId, mapKey);
+                if (!this.hasActiveSubscriptions) {
+                    this.startIdleCloseTimeout();
+                }
+            });
+        }
+        // if we are waiting to close the stream, cancel closing!
+        this.cancelClose();
     }
     /**
      * @inheritdoc
@@ -2080,22 +2341,38 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
      */
     invokeUnsubscribe(queryName, variables) {
         const mapKey = this.getMapKey(queryName, variables);
-        const subscribeRequest = this.activeSubscribeRequests.get(mapKey);
+        const subscribeRequest = this.activeInvokeSubscribeRequests.get(mapKey);
         if (!subscribeRequest) {
             return;
         }
         const requestId = subscribeRequest.requestId;
+        this.subscribeObservers.delete(requestId);
+        const resumePromise = this.resumeRequestPromises.get(requestId);
+        if (resumePromise) {
+            this.pendingCancellations.set(requestId, {
+                operationName: queryName,
+                variables
+            });
+            return;
+        }
+        this.cancelSubscription(requestId, mapKey);
+    }
+    /**
+     * Cancels a subscription, cleans up the request tracking data structures, and checks to see if we
+     * should close the stream due to inactivity.
+     */
+    cancelSubscription(requestId, mapKey) {
+        this.cleanupInvokeSubscribeRequest(requestId, mapKey);
         const cancelBody = {
             requestId,
             cancel: {}
         };
-        this.cleanupSubscribeRequest(requestId, mapKey);
         // asynchronous, fire and forget
         this.sendRequestMessage(cancelBody).catch(err => {
             logError(`Stream Transport failed to send unsubscribe message: ${err}`);
         });
         if (!this.hasActiveSubscriptions) {
-            this.prepareToCloseGracefully();
+            this.startIdleCloseTimeout();
         }
     }
     onAuthTokenChanged(newToken) {
@@ -2114,38 +2391,58 @@ class AbstractDataConnectStreamTransport extends AbstractDataConnectTransport {
             (!oldAuthUid && newAuthUid) || // user logged in
             (oldAuthUid && newAuthUid !== oldAuthUid) // logged in user changed
         ) {
-            this.rejectAllActiveRequests(Code.UNAUTHORIZED, 'Stream disconnected due to auth change.');
-            void this.attemptClose();
+            void this.cleanupAndTerminate(Code.UNAUTHORIZED, 'Stream disconnected due to auth change.');
         }
     }
     /**
      * Handle a response message from the server. Called by the connection-specific implementation after
-     * it's transformed a message from the server into a {@link DataConnectResponse}.
-     * @param requestId the requestId associated with this response.
+     * it's transformed a message from the server into a {@linkcode DataConnectResponse}.
+     * @param requestId the Request ID associated with this response.
      * @param response the response from the server.
      */
     async handleResponse(requestId, response) {
         if (this.executeRequestPromises.has(requestId)) {
-            // don't clean up the tracking maps here, they're handled automatically when the execute promise settles
             const { resolveFn, rejectFn } = this.executeRequestPromises.get(requestId);
-            if (response.errors && response.errors.length) {
-                const failureResponse = {
-                    errors: response.errors,
-                    data: response.data
-                };
-                const stringified = JSON.stringify(response.errors);
-                rejectFn(new DataConnectOperationError('DataConnect error while performing request: ' + stringified, failureResponse));
+            this.handleInvokeOperationResponse(resolveFn, rejectFn, response);
+        }
+        else if (this.subscribeObservers.has(requestId) ||
+            this.resumeRequestPromises.has(requestId)) {
+            const observer = this.subscribeObservers.get(requestId);
+            const resumePromise = this.resumeRequestPromises.get(requestId);
+            if (resumePromise) {
+                this.resumeRequestPromises.delete(requestId);
+                const { resolveFn, rejectFn } = resumePromise;
+                this.handleInvokeOperationResponse(resolveFn, rejectFn, response);
             }
-            else {
-                resolveFn(response);
+            if (observer) {
+                try {
+                    await observer.onData(response);
+                }
+                catch (e) {
+                    logError(`Error in observer callback: ${e}`);
+                }
             }
         }
-        else if (this.subscribeObservers.has(requestId)) {
-            const observer = this.subscribeObservers.get(requestId);
-            await observer.onData(response);
+        else {
+            logError(`Stream response contained unrecognized requestId '${requestId}'`);
+        }
+    }
+    /**
+     * Handles an invoke operation response, resolving or rejecting the promise returned to the user
+     * Does not handle any cleanup for requests - this should be handled by the caller or the promise's
+     * finally() block.
+     */
+    handleInvokeOperationResponse(resolveFn, rejectFn, response) {
+        if (response.errors && response.errors.length) {
+            const failureResponse = {
+                errors: response.errors,
+                data: response.data
+            };
+            const stringified = JSON.stringify(response.errors);
+            rejectFn(new DataConnectOperationError('DataConnect error while performing request: ' + stringified, failureResponse));
         }
         else {
-            throw new DataConnectError(Code.OTHER, `Stream response contained unrecognized requestId '${requestId}'`);
+            resolveFn(response);
         }
     }
 }
@@ -2181,6 +2478,18 @@ const WEBSOCKET_CLOSE_CODE = 1000;
  * @internal
  */
 class WebSocketTransport extends AbstractDataConnectStreamTransport {
+    constructor() {
+        super(...arguments);
+        /** Decodes binary WebSocket responses to strings */
+        this.decoder = undefined;
+        /** The current connection to the server. Undefined if disconnected. */
+        this.connection = undefined;
+        /**
+         * Current connection attempt. If null, we are not currently attemping to connect (not connected,
+         * or already connected). Will be resolved or rejected when the connection is opened or fails to open.
+         */
+        this.connectionAttempt = null;
+    }
     get endpointUrl() {
         return websocketUrlBuilder({
             connector: this._connectorName,
@@ -2206,24 +2515,6 @@ class WebSocketTransport extends AbstractDataConnectStreamTransport {
     get streamIsReady() {
         return this.connection?.readyState === WebSocket.OPEN;
     }
-    constructor(options, apiKey, appId, authProvider, appCheckProvider, transportOptions, _isUsingGen = false, _callerSdkType = CallerSdkTypeEnum.Base) {
-        super(options, apiKey, appId, authProvider, appCheckProvider, transportOptions, _isUsingGen, _callerSdkType);
-        this.apiKey = apiKey;
-        this.appId = appId;
-        this.authProvider = authProvider;
-        this.appCheckProvider = appCheckProvider;
-        this._isUsingGen = _isUsingGen;
-        this._callerSdkType = _callerSdkType;
-        /** Decodes binary WebSocket responses to strings */
-        this.decoder = undefined;
-        /** The current connection to the server. Undefined if disconnected. */
-        this.connection = undefined;
-        /**
-         * Current connection attempt. If null, we are not currently attemping to connect (not connected,
-         * or already connected). Will be resolved or rejected when the connection is opened or fails to open.
-         */
-        this.connectionAttempt = null;
-    }
     ensureConnection() {
         try {
             if (this.streamIsReady) {
@@ -2443,7 +2734,7 @@ class DataConnectTransportManager {
             if (this.isUsingEmulator && this.transportOptions) {
                 this.streamTransport.useEmulator(this.transportOptions.host, this.transportOptions.port, this.transportOptions.sslEnabled);
             }
-            this.streamTransport.onGracefulStreamClose = () => {
+            this.streamTransport.onCloseCallback = () => {
                 this.streamTransport = undefined;
             };
         }