Fix client.flush() blocking process exit with unref'd timers and early exit

Co-authored-by: Lms24 <8420481+Lms24@users.noreply.github.com>

Author: Copilot

packages/core/src/client.ts

@@ -1148,11 +1148,23 @@ export abstract class Client<O extends ClientOptions = ClientOptions> {
    * `false` otherwise
    */
   protected async _isClientDoneProcessing(timeout?: number): Promise<boolean> {
+    // Early exit if there's nothing to process
+    if (!this._numProcessing) {
+      return true;
+    }
+
     let ticked = 0;
 
     // if no timeout is provided, we wait "forever" until everything is processed
     while (!timeout || ticked < timeout) {
-      await new Promise(resolve => setTimeout(resolve, 1));
+      await new Promise(resolve => {
+        const timer = setTimeout(resolve, 1);
+        // Use unref() in Node.js to allow the process to exit naturally
+        // In browsers, setTimeout returns a number, so we check for that
+        if (typeof timer !== 'number' && timer.unref) {
+          timer.unref();
+        }
+      });
 
       if (!this._numProcessing) {
         return true;

packages/core/src/utils/promisebuffer.ts

@@ -77,7 +77,17 @@ export function makePromiseBuffer<T>(limit: number = 100): PromiseBuffer<T> {
       return drainPromise;
     }
 
-    const promises = [drainPromise, new Promise<boolean>(resolve => setTimeout(() => resolve(false), timeout))];
+    const promises = [
+      drainPromise,
+      new Promise<boolean>(resolve => {
+        const timer = setTimeout(() => resolve(false), timeout);
+        // Use unref() in Node.js to allow the process to exit naturally
+        // In browsers, setTimeout returns a number, so we check for that
+        if (typeof timer !== 'number' && timer.unref) {
+          timer.unref();
+        }
+      }),
+    ];
 
     // Promise.race will resolve to the first promise that resolves or rejects
     // So if the drainPromise resolves, the timeout promise will be ignored

packages/core/test/lib/client.test.ts

@@ -2205,6 +2205,50 @@ describe('Client', () => {
         }),
       ]);
     });
+
+    test('flush returns immediately when nothing is processing', async () => {
+      vi.useRealTimers();
+      expect.assertions(2);
+
+      const options = getDefaultTestClientOptions({ dsn: PUBLIC_DSN });
+      const client = new TestClient(options);
+
+      const startTime = Date.now();
+      const result = await client.flush(1000);
+      const elapsed = Date.now() - startTime;
+
+      // Should return true immediately without waiting
+      expect(result).toBe(true);
+      // Should take less than 100ms (much less than the 1000ms timeout)
+      expect(elapsed).toBeLessThan(100);
+    });
+
+    test('flush with early exit when processing completes', async () => {
+      vi.useRealTimers();
+      expect.assertions(3);
+
+      const { makeTransport, getSendCalled, getSentCount, delay } = makeFakeTransport(50);
+
+      const client = new TestClient(
+        getDefaultTestClientOptions({
+          dsn: PUBLIC_DSN,
+          enableSend: true,
+          transport: makeTransport,
+        }),
+      );
+
+      client.captureMessage('test');
+      expect(getSendCalled()).toEqual(1);
+
+      const startTime = Date.now();
+      // Use a large timeout but processing should complete early
+      await client.flush(5000);
+      const elapsed = Date.now() - startTime;
+
+      expect(getSentCount()).toEqual(1);
+      // Should complete in ~50ms (the transport delay), not wait for the full 5000ms timeout
+      expect(elapsed).toBeLessThan(500);
+    });
   });
 
   describe('sendEvent', () => {

packages/core/test/lib/utils/promisebuffer.test.ts

@@ -252,4 +252,17 @@ describe('PromiseBuffer', () => {
       expect(e).toEqual(new Error('whoops'));
     }
   });
+
+  test('drain returns immediately when buffer is empty', async () => {
+    const buffer = makePromiseBuffer();
+    expect(buffer.$.length).toEqual(0);
+
+    const startTime = Date.now();
+    const result = await buffer.drain(5000);
+    const elapsed = Date.now() - startTime;
+
+    expect(result).toBe(true);
+    // Should return immediately, not wait for timeout
+    expect(elapsed).toBeLessThan(100);
+  });
 });

packages/node-core/test/sdk/client.test.ts

@@ -386,4 +386,34 @@ describe('NodeClient', () => {
       expect(processOffSpy).toHaveBeenNthCalledWith(1, 'beforeExit', expect.any(Function));
     });
   });
+
+  describe('flush', () => {
+    it('flush returns immediately when nothing is processing', async () => {
+      const options = getDefaultNodeClientOptions();
+      const client = new NodeClient(options);
+
+      const startTime = Date.now();
+      const result = await client.flush(1000);
+      const elapsed = Date.now() - startTime;
+
+      // Should return true immediately without waiting
+      expect(result).toBe(true);
+      // Should take less than 100ms (much less than the 1000ms timeout)
+      expect(elapsed).toBeLessThan(100);
+    });
+
+    it('flush does not block process exit when using unref timers', async () => {
+      // This test verifies that timers are properly unref'd in Node.js
+      // We create a client with no processing and a long timeout
+      const options = getDefaultNodeClientOptions();
+      const client = new NodeClient(options);
+
+      // Flush with a long timeout - if timers are not unref'd, this would block
+      const flushPromise = client.flush(5000);
+
+      // The flush should complete immediately since there's nothing to process
+      const result = await flushPromise;
+      expect(result).toBe(true);
+    });
+  });
 });