* `original` {Function}

Takes a function following the common Node.js callback style, i.e. taking a

`(err, value) => ...` callback as the last argument, and returns a version

that returns promises.

For example:

const util = require('util');

const fs = require('fs');

const stat = util.promisify(fs.stat);

stat('.').then((stats) => {

// Do something with `stats`

}).catch((error) => {

// Handle the error.

});

Or, equivalently using `async function`s:

const util = require('util');

const fs = require('fs');

const stat = util.promisify(fs.stat);

async function callStat() {

const stats = await stat('.');

console.log(`This directory is owned by ${stats.uid}`);

}

If there is an `original[util.promisify.custom]` property present, `promisify`

will return its value, see [Custom promisified functions][].

`promisify()` assumes that `original` is a function taking a callback as its

final argument in all cases, and the returned function will result in undefined

behaviour if it does not.

Using the `util.promisify.custom` symbol one can override the return value of

[`util.promisify()`][]:

const util = require('util');

function doSomething(foo, callback) {

// ...

}

doSomething[util.promisify.custom] = function(foo) {

return getPromiseSomehow();

};

const promisified = util.promisify(doSomething);

console.log(promisified === doSomething[util.promisify.custom]);

// prints 'true'

This can be useful for cases where the original function does not follow the

standard format of taking an error-first callback as the last argument.

* {symbol}

A Symbol that can be used to declare custom promisified variants of functions,

see [Custom promisified functions][].

[`util.promisify()`]: #util_util_promisify_original

[Custom promisified functions]: #util_custom_promisified_functions

const { createPromise, promiseResolve, promiseReject } = binding;

const kCustomPromisifiedSymbol = Symbol('util.promisify.custom');

const kCustomPromisifyArgsSymbol = Symbol('customPromisifyArgs');

function promisify(orig) {

if (typeof orig !== 'function') {

const errors = require('internal/errors');

throw new errors.TypeError('ERR_INVALID_ARG_TYPE', 'original', 'function');

}

if (orig[kCustomPromisifiedSymbol]) {

const fn = orig[kCustomPromisifiedSymbol];

if (typeof fn !== 'function') {

throw new TypeError('The [util.promisify.custom] property must be ' +

'a function');

}

Object.defineProperty(fn, kCustomPromisifiedSymbol, {

value: fn, enumerable: false, writable: false, configurable: true

});

return fn;

}

// Names to create an object from in case the callback receives multiple

// arguments, e.g. ['stdout', 'stderr'] for child_process.exec.

const argumentNames = orig[kCustomPromisifyArgsSymbol];

function fn(...args) {

const promise = createPromise();

try {

orig.call(this, ...args, (err, ...values) => {

if (err) {

promiseReject(promise, err);

} else if (argumentNames !== undefined && values.length > 1) {

const obj = {};

for (var i = 0; i < argumentNames.length; i++)

obj[argumentNames[i]] = values[i];

promiseResolve(promise, obj);

} else {

promiseResolve(promise, values[0]);

}

});

} catch (err) {

promiseReject(promise, err);

}

return promise;

}

Object.setPrototypeOf(fn, Object.getPrototypeOf(orig));

Object.defineProperty(fn, kCustomPromisifiedSymbol, {

value: fn, enumerable: false, writable: false, configurable: true

});

return Object.defineProperties(fn, Object.getOwnPropertyDescriptors(orig));

promisify.custom = kCustomPromisifiedSymbol;

exports.promisify = promisify;

exports.customPromisifyArgs = kCustomPromisifyArgsSymbol;

exports.promisify = internalUtil.promisify;

V(isAsyncFunction, IsAsyncFunction) \

const common = require('../common');

const assert = require('assert');

const fs = require('fs');

const vm = require('vm');

const { promisify } = require('util');

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);

}));