timers: allow passing delay to timer.refresh()

doc/api/deprecations.md

@@ -3242,7 +3242,7 @@ Convert them to primitive strings.
 [`setTimeout()`]: timers.md#settimeoutcallback-delay-args
 [`socket.bufferSize`]: net.md#socketbuffersize
 [`timeout.ref()`]: timers.md#timeoutref
-[`timeout.refresh()`]: timers.md#timeoutrefresh
+[`timeout.refresh()`]: timers.md#timeoutrefreshdelay-resetinterval
 [`timeout.unref()`]: timers.md#timeoutunref
 [`tls.CryptoStream`]: tls.md#class-tlscryptostream
 [`tls.SecureContext`]: tls.md#tlscreatesecurecontextoptions

doc/api/timers.md

@@ -111,18 +111,26 @@ When called, requests that the Node.js event loop _not_ exit so long as the
 By default, all `Timeout` objects are "ref'ed", making it normally unnecessary
 to call `timeout.ref()` unless `timeout.unref()` had been called previously.
 
-### `timeout.refresh()`
+### `timeout.refresh([delay[, resetInterval]])`
 
 <!-- YAML
 added: v10.2.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/40434
+    description: Added `delay` and `resetInterval` parameters.
 -->
 
+* `delay` {number} The number of milliseconds to wait before calling the
+  original callback.
+* `resetInterval` {boolean} For an interval timer, should the interval be set to
+  `delay`? **Default:** `false`.
 * Returns: {Timeout} a reference to `timeout`
 
 Sets the timer's start time to the current time, and reschedules the timer to
-call its callback at the previously specified duration adjusted to the current
-time. This is useful for refreshing a timer without allocating a new
-JavaScript object.
+call its callback at the previously specified duration or the duration specified
+by `delay` adjusted to the current time. This is useful for refreshing a timer
+without allocating a new JavaScript object.
 
 Using this on a timer that has already called its callback will reactivate the
 timer.

lib/internal/timers.js

@@ -158,20 +158,26 @@ function initAsyncResource(resource, type) {
   if (initHooksExist())
     emitInit(asyncId, type, triggerAsyncId, resource);
 }
+
+function calcAfter(after) {
+  after *= 1; // Coalesce to number or NaN
+  if (!(after >= 1 && after <= TIMEOUT_MAX)) {
+    if (after > TIMEOUT_MAX) {
+      process.emitWarning(`${after} does not fit into` +
+                          ' a 32-bit signed integer.' +
+                          '\nTimeout duration was set to 1.',
+                          'TimeoutOverflowWarning');
+    }
+    after = 1; // Schedule on next tick, follows browser behavior
+  }
+  return after;
+}
+
 class Timeout {
   // Timer constructor function.
   // The entire prototype is defined in lib/timers.js
   constructor(callback, after, args, isRepeat, isRefed) {
-    after *= 1; // Coalesce to number or NaN
-    if (!(after >= 1 && after <= TIMEOUT_MAX)) {
-      if (after > TIMEOUT_MAX) {
-        process.emitWarning(`${after} does not fit into` +
-                            ' a 32-bit signed integer.' +
-                            '\nTimeout duration was set to 1.',
-                            'TimeoutOverflowWarning');
-      }
-      after = 1; // Schedule on next tick, follows browser behavior
-    }
+    after = calcAfter(after);
 
     this._idleTimeout = after;
     this._idlePrev = this;
@@ -204,7 +210,14 @@ class Timeout {
     });
   }
 
-  refresh() {
+  refresh(after, resetInterval) {
+    if (after !== undefined) {
+      after = calcAfter(after);
+      this._idleTimeout = after;
+      if (this._repeat !== null && resetInterval)
+        this._repeat = after;
+    }
+
     if (this[kRefed])
       active(this);
     else

test/sequential/test-timers-refresh-args.js

@@ -0,0 +1,31 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+
+const LONGER_DELAY = 1000;
+const SHORTER_DELAY = 100;
+let last;
+let t = setTimeout(() => {
+  if (last !== undefined) {
+    assert(Date.now() - last < LONGER_DELAY);
+
+    last = undefined;
+    let count = 0;
+    t = setInterval(() => {
+      if (last !== undefined)
+        assert(Date.now() - last < LONGER_DELAY);
+      last = Date.now();
+      switch (count++) {
+        case 0:
+          t.refresh(SHORTER_DELAY, true);
+          break;
+        case 3:
+          clearInterval(t);
+          break;
+      }
+    }, LONGER_DELAY);
+    return;
+  }
+  last = Date.now();
+  t.refresh(SHORTER_DELAY);
+}, LONGER_DELAY);