Merge pull request #5751 from cloudflare/dlapid/nodejs_global_timers

Enable nodejs style global timers with a compat flag.

Author: danlapid

src/node/internal/internal_timers.ts

@@ -26,6 +26,28 @@
 import { validateFunction } from 'node-internal:validators';
 import { default as timersUtil } from 'node-internal:timers';
 
+// Capture original global timer functions at module load time, before they might be
+// overridden by the enable_nodejs_global_timers compat flag. This avoids circular
+// dependency issues when our setTimeout/setInterval return Timeout objects.
+// Cast to number-returning functions since we know we're capturing the original
+// implementations before any override.
+const originalSetTimeout = globalThis.setTimeout.bind(globalThis) as (
+  callback: (...args: unknown[]) => unknown,
+  ms?: number,
+  ...args: unknown[]
+) => number;
+const originalSetInterval = globalThis.setInterval.bind(globalThis) as (
+  callback: (...args: unknown[]) => unknown,
+  ms?: number,
+  ...args: unknown[]
+) => number;
+const originalClearTimeout = globalThis.clearTimeout.bind(globalThis) as (
+  id?: number
+) => void;
+const originalClearInterval = globalThis.clearInterval.bind(globalThis) as (
+  id?: number
+) => void;
+
 let clearTimeoutImpl: (obj: Timeout) => void;
 
 export class Timeout {
@@ -54,18 +76,17 @@ export class Timeout {
   }
 
   #constructTimer(): number {
-    // @ts-expect-error TS2322 Due to difference between Node.js and globals
     this.#timer = this.#isRepeat
-      ? globalThis.setInterval(this.#callback, this.#after, ...this.#args)
-      : globalThis.setTimeout(this.#callback, this.#after, ...this.#args);
+      ? originalSetInterval(this.#callback, this.#after, ...this.#args)
+      : originalSetTimeout(this.#callback, this.#after, ...this.#args);
     return this.#timer;
   }
 
   #clearTimeout(): void {
     if (this.#isRepeat) {
-      globalThis.clearInterval(this.#timer);
+      originalClearInterval(this.#timer);
     } else {
-      globalThis.clearTimeout(this.#timer);
+      originalClearTimeout(this.#timer);
     }
   }
 
@@ -133,7 +154,7 @@ export function clearTimeout(
   if (timer instanceof Timeout) {
     clearTimeoutImpl(timer);
   } else if (typeof timer === 'number') {
-    globalThis.clearTimeout(timer);
+    originalClearTimeout(timer);
   }
 }
 
@@ -162,7 +183,7 @@ export function clearInterval(
   if (timer instanceof Timeout) {
     clearTimeoutImpl(timer);
   } else if (typeof timer === 'number') {
-    globalThis.clearInterval(timer);
+    originalClearInterval(timer);
   }
 }
 
@@ -182,7 +203,7 @@ export function unenroll(timer: unknown): void {
   if (timer instanceof Timeout) {
     clearTimeoutImpl(timer);
   } else if (typeof timer === 'number') {
-    globalThis.clearTimeout(timer);
+    originalClearTimeout(timer);
   }
 }
 

src/node/internal/internal_timers_global_override.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2017-2025 Cloudflare, Inc.
+// Licensed under the Apache 2.0 license found in the LICENSE file or at:
+//     https://opensource.org/licenses/Apache-2.0
+
+// This module overrides globalThis timer functions with Node.js-compatible versions
+// when loaded. It is loaded by worker.c++ when enable_nodejs_global_timers compat
+// flag is enabled.
+//
+// After loading:
+// - globalThis.setTimeout and globalThis.setInterval return Timeout objects
+//   with methods like refresh(), ref(), unref(), and hasRef() instead of numeric IDs
+// - globalThis.setImmediate and globalThis.clearImmediate are available
+
+import {
+  setTimeout,
+  setInterval,
+  clearTimeout,
+  clearInterval,
+  setImmediate,
+  clearImmediate,
+} from 'node-internal:internal_timers';
+
+globalThis.setTimeout = setTimeout as unknown as typeof globalThis.setTimeout;
+globalThis.setInterval =
+  setInterval as unknown as typeof globalThis.setInterval;
+globalThis.clearTimeout =
+  clearTimeout as unknown as typeof globalThis.clearTimeout;
+globalThis.clearInterval =
+  clearInterval as unknown as typeof globalThis.clearInterval;
+globalThis.setImmediate = setImmediate;
+globalThis.clearImmediate = clearImmediate;

src/workerd/api/node/tests/BUILD.bazel

@@ -365,6 +365,12 @@ wd_test(
     data = ["timers-nodejs-test.js"],
 )
 
+wd_test(
+    src = "timers-global-override-test.wd-test",
+    args = ["--experimental"],
+    data = ["timers-global-override-test.js"],
+)
+
 wd_test(
     src = "async_hooks-nodejs-test.wd-test",
     args = ["--experimental"],