timers: introduce timers/promises

[jasnell]

Move the promisified timers implementations into a new experimental
sub-module to avoid the need to promisify. The promisified versions
now return the timers/promises versions.

Also adds ref option to the promisified versions

const {
  setTimeout,
  setImmediate
} = require('timers/promises');

setTimeout(10, null, { ref: false })
  .then(console.log);

setImmediate(null, { ref: false })
  .then(console.log);

// The promisify versions of the original timers return the same functions...
const timers = require('timers');
const { promisify } = require('util');
const assert = require('assert');

assert.strictEqual(promisify(timers.setTimeout), setTimeout);
assert.strictEqual(promisify(timers.setImmediate), setImmediate);

Needs the additional fixes implemented in #33949 ... this one is blocked on that one landing.

Signed-off-by: James M Snell [email protected]

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[jasnell]

/cc @mcollina @devsnek @benjamingr @lundibundi

[lundibundi]

LGTM, finally I'll be able to write one less util.promisify 😄 🚀

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/32034/

[jasnell]

Landed in a8904e8

[vjeux]

I saw this pull request from nodejs 16 announcement. It's probably too late but I'm a bit concerned by the naming. setTimeout API in the browser has a different signature than setTimeout here. This feels very confusing to me to have two functions with the same name but a different way to call them. Have you considered using a different name?