util: add util.promisify()

Add `util.promisify(function)` for creating promisified functions.
Includes documentation and tests.

Fixes: https://github.com/nodejs/CTC/issues/12
PR-URL: https://github.com/nodejs/node/pull/12442
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: William Kapke <william.kapke@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Teddy Katz <teddy.katz@gmail.com>

1 files changed, 76 insertions, 0 deletions

diff --git a/test/parallel/test-util-promisify.js b/test/parallel/test-util-promisify.js
new file mode 100644
index 0000000000..23b3d40037
--- /dev/null
+++ b/test/parallel/test-util-promisify.js
@@ -0,0 +1,76 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const vm = require('vm');
+const { promisify } = require('util');
+
+common.crashOnUnhandledRejection();
+
+const stat = promisify(fs.stat);
+
+{
+  const promise = stat(__filename);
+  assert(promise instanceof Promise);
+  promise.then(common.mustCall((value) => {
+    assert.deepStrictEqual(value, fs.statSync(__filename));
+  }));
+}
+
+{
+  const promise = stat('/dontexist');
+  promise.catch(common.mustCall((error) => {
+    assert(error.message.includes('ENOENT: no such file or directory, stat'));
+  }));
+}
+
+{
+  function fn() {}
+  function promisifedFn() {}
+  fn[promisify.custom] = promisifedFn;
+  assert.strictEqual(promisify(fn), promisifedFn);
+  assert.strictEqual(promisify(promisify(fn)), promisifedFn);
+}
+
+{
+  function fn() {}
+  fn[promisify.custom] = 42;
+  assert.throws(
+      () => promisify(fn),
+      (err) => err instanceof TypeError &&
+                err.message === 'The [util.promisify.custom] property must ' +
+                                'be a function');
+}
+
+{
+  const fn = vm.runInNewContext('(function() {})');
+  assert.notStrictEqual(Object.getPrototypeOf(promisify(fn)),
+                        Function.prototype);
+}
+
+{
+  function fn(callback) {
+    callback(null, 'foo', 'bar');
+  }
+  promisify(fn)().then(common.mustCall((value) => {
+    assert.deepStrictEqual(value, 'foo');
+  }));
+}
+
+{
+  function fn(callback) {
+    callback(null);
+  }
+  promisify(fn)().then(common.mustCall((value) => {
+    assert.strictEqual(value, undefined);
+  }));
+}
+
+{
+  function fn(callback) {
+    callback();
+  }
+  promisify(fn)().then(common.mustCall((value) => {
+    assert.strictEqual(value, undefined);
+  }));
+}