docs: fixing comments

Author: joker23

packages/sdk/node-client/__tests__/NodeClientFDv2.test.ts

@@ -296,24 +296,17 @@ it('duplicate-mode setConnectionMode awaits an in-flight transition to the same
     localStoragePath: tmpRoot,
   });
 
-  // Make the offline transition's flush() defer to a later microtask so the
-  // offline -> streaming queue is still draining when the duplicate streaming
-  // call is issued. This exposes the early-return race deterministically.
+  // Keeps the queue draining when p3 is issued, making the race deterministic.
   const flushSpy = jest
     .spyOn(LDClientImpl.prototype, 'flush')
     .mockImplementation(() => Promise.resolve({ result: true }));
 
-  // Sequence: initial mode is 'streaming'. Go offline, then streaming, then
-  // streaming again (the duplicate). The third call's _connectionMode is already
-  // 'streaming' (set synchronously by the second call), so the idempotency guard
-  // fires. Without the await fix, p3 resolves before the second call's queued
-  // task has delegated 'streaming' to the data manager.
+  // p3 hits the idempotency guard because p2 sets _connectionMode synchronously,
+  // before p2's queued task runs. Without the await, p3 resolves too early.
   const p1 = client.setConnectionMode('offline');
   const p2 = client.setConnectionMode('streaming');
   const p3 = client.setConnectionMode('streaming');
 
-  // Awaiting only the duplicate call must guarantee the queued streaming
-  // transition has completed (mockSetConnectionMode called with 'streaming').
   await p3;
   expect(mockSetConnectionMode).toHaveBeenCalledWith('streaming');
 
@@ -365,15 +358,16 @@ it('restores connection mode when an FDv2 offline transition task throws', async
     logger,
     localStoragePath: tmpRoot,
   });
-  // Force the queued offline transition task to throw by making flush() reject.
+  // flush() is the first async step, so a reject here means setConnectionMode
+  // on the data manager is never reached.
   const flushSpy = jest
     .spyOn(LDClientImpl.prototype, 'flush')
     .mockRejectedValueOnce(new Error('flush failed'));
 
   await expect(client.setConnectionMode('offline')).rejects.toThrow('flush failed');
 
-  // The synchronously-set 'offline' must be rolled back to the prior mode so
-  // isOffline() does not lie while the data manager is still streaming.
+  // The synchronously-set 'offline' is rolled back: the data manager is still
+  // streaming, so isOffline() reflects actual state.
   expect(client.getConnectionMode()).toBe('streaming');
   expect(client.isOffline()).toBe(false);
   // The data manager was never told to go offline.

packages/sdk/node-client/src/NodeClient.ts

@@ -190,26 +190,20 @@ export class NodeClient extends LDClientImpl {
         return;
       }
       if (mode === this._connectionMode) {
-        // The requested mode matches the optimistically-set _connectionMode, so
-        // no new transition is queued. But _connectionMode is set synchronously
-        // before the queued task runs, so an earlier call's transition to this
-        // same mode may still be in flight. Await the queue tail (without
-        // appending to it) so the caller's promise resolves only after that
-        // transition has actually completed. If nothing is in flight,
-        // _fdv2ConnectionModeQueue is already resolved, so this is a no-op.
+        // Await without appending: an earlier call may still be transitioning to
+        // this same mode, and we must not resolve until it has finished.
         await this._fdv2ConnectionModeQueue;
         return;
       }
-      // FDv2 data manager: serialize transitions so concurrent calls cannot
-      // reorder flush/setEventSendingEnabled around the offline await.
-      // Capture the prior mode so a failed transition can be rolled back -
+      // Without serialization, concurrent calls can interleave flush() and
+      // setEventSendingEnabled() across an offline await, corrupting order.
+      // Capture the prior mode so a failed transition can be rolled back:
       // otherwise isOffline()/getConnectionMode() would report a state the
       // data manager never actually entered.
       const previousMode = this._connectionMode;
       this._connectionMode = mode;
       const task = this._fdv2ConnectionModeQueue.then(async () => {
-        // Re-check after any preceding tasks have run — close() may have fired
-        // while this task was queued, matching the FDv1 NodeDataManager guard.
+        // Re-check: close() may have been called while this task was queued.
         if (this._closed) {
           return;
         }
@@ -223,10 +217,9 @@ export class NodeClient extends LDClientImpl {
             this.setEventSendingEnabled(true, false);
           }
         } catch (e) {
-          // The transition did not complete; restore the requested-mode marker
-          // so isOffline()/getConnectionMode() stay consistent with the data
-          // manager. Only roll back if no later queued task has already moved
-          // us on from this transition's target mode.
+          // Only roll back if no later queued task has already moved past this
+          // mode; otherwise isOffline()/getConnectionMode() would drift from
+          // the state the data manager actually reached.
           if (this._connectionMode === mode) {
             this._connectionMode = previousMode;
           }