timers.js

/**
 * @file     timers.js
 * @author   Tom Tang <xmader@distributive.network>
 * @date     May 2023
 */
const internalBinding = require('internal-binding');

const { 
  enqueueWithDelay,
  cancelByTimeoutId
} = internalBinding('timers');

/**
 * Implement the `setTimeout` global function
 * @see https://developer.mozilla.org/en-US/docs/Web/API/setTimeout and
 * @see https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#dom-settimeout
 * @param {Function | string} handler
 * @param {number} delayMs timeout milliseconds, use value of 0 if this is omitted
 * @param {any[]} args additional arguments to be passed to the `handler`
 * @return {number} timeoutId
 */
function setTimeout(handler, delayMs = 0, ...args) 
{
  // Ensure the first parameter is a function
  // We support passing a `code` string to `setTimeout` as the callback function
  if (typeof handler !== 'function')
    handler = new Function(handler);

  // `setTimeout` allows passing additional arguments to the callback, as spec-ed
  // FIXME (Tom Tang): the spec doesn't allow additional arguments to be passed if the original `handler` is not a function
  const thisArg = globalThis; // HTML spec requires `thisArg` to be the global object
  // Wrap the job function into a bound function with the given additional arguments
  //    https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind
  /** @type {Function} */
  const boundHandler = handler.bind(thisArg, ...args);

  // Get the delay time in seconds
  //  JS `setTimeout` takes milliseconds, but Python takes seconds
  delayMs = Number(delayMs) || 0; // ensure the `delayMs` is a `number`, explicitly do type coercion
  if (delayMs < 0)
    delayMs = 0; // as spec-ed
  const delaySeconds = delayMs / 1000; // convert ms to s

  return enqueueWithDelay(boundHandler, delaySeconds);
}

/**
 * Implement the `clearTimeout` global function
 * @see https://developer.mozilla.org/en-US/docs/Web/API/clearTimeout and
 * @see https://html.spec.whatwg.org/multipage/timers-and-user-prompts.html#dom-cleartimeout
 * @param {number} timeoutId
 * @return {void}
 */
function clearTimeout(timeoutId) 
{
  return cancelByTimeoutId(timeoutId);
}

if (!globalThis.setTimeout)
  globalThis.setTimeout = setTimeout;
if (!globalThis.clearTimeout)
  globalThis.clearTimeout = clearTimeout;

exports.setTimeout = setTimeout;
exports.clearTimeout = clearTimeout;