Help Land Promises in Core

[chrisdickinson]

Ref nodejs#5020.

OK folks, this is a big PR, it will take time and effort to land. If you want to help land it, here are some excellent places to pitch in. If you notice something missing — raise your hand here by saying ":hand: signature cluster.disconnect" or ":hand: docs net.connectAsync", then PR this repo's promises branch with your changes. You will be credited in the resulting commit. If an item looks good to you, respond to this issue with, for example, "LGTM docs dns.lookupService". I'll be moderating this issue pretty strictly to keep it to just the tasks folks have volunteered for and their results — any other comments will be deleted. This issue isn't for code review — it's just for checking docs and promise resolution results.

One thing before you contribute: I can't promise (har, har) that these changes will make it in — but I'll do everything I can to make sure your effort is well-spent. Contributing to this issue is a positive sign that you want to see this land in Node, and is way more effective than a 👍 on the PR.

Thanks for your help, everyone!

Steps:

1. Clone this repository.
2. Check out the promises branch — git checkout -b promises --track origin/promises.
3. Run ./configure; make -j8.
4. Check the docs, use the API, make sure things seem OK!
5. If a promise resolution value needs changing, note it on this issue. If docs need changing, make a PR to this repository fixing the docs.

Misc. Tasks

• Benchmark: keep an updated benchmarking gist comparing tip of promises branch to tip of master.

Make sure these functions resolve and reject as expected:

• child_process.ChildProcess#send
• cluster.disconnect
• dgram.Socket#bind
• dgram.Socket#close
• dgram.Socket#send
• dgram.Socket#sendto
• dns.lookupService
• dns.lookup
• dns.resolve
• fs.access
• fs.appendFile
• fs.chmod
• fs.chown
• fs.close
• fs.exists
• fs.fchmod
• fs.fchown
• fs.fdatasync
• fs.fstat
• fs.fsync
• fs.ftruncate
• fs.futimes
• fs.lchmod
• fs.lchown
• fs.link
• fs.lstat
• fs.mkdir
• fs.open
• fs.readFile
• fs.readdir
• fs.readlink
• fs.realpath
• fs.rename
• fs.rmdir
• fs.stat
• fs.symlink
• fs.unlink
• fs.utimes
• fs.writeFile
• net.Socket#setTimeout
• readline.Interface#question
• repl.REPLServer#complete
• zlib.deflateRaw
• zlib.deflate
• zlib.gunzip
• zlib.gzip
• zlib.inflateRaw
• zlib.inflate
• zlib.unzip
• net.connectAsync
• tls.connectAsync
• crypto.randomBytesAsync
• crypto.pbkdf2Async
• crypto.pseudoRandomBytesAsync
• crypto.rngAsync
• crypto.prngAsync
• http.getAsync
• https.getAsync
• http.requestAsync
• https.requestAsync
• child_process.execAsync
• child_process.execFileAsync

Make sure that the docs have been updated:

• child_process.ChildProcess#send
• cluster.disconnect
• dgram.Socket#bind
• dgram.Socket#close
• dgram.Socket#send
• dgram.Socket#sendto
• dns.lookupService
• dns.lookup
• dns.resolve
• fs.access
• fs.appendFile
• fs.chmod
• fs.chown
• fs.close
• fs.exists
• fs.fchmod
• fs.fchown
• fs.fdatasync
• fs.fstat
• fs.fsync
• fs.ftruncate
• fs.futimes
• fs.lchmod
• fs.lchown
• fs.link
• fs.lstat
• fs.mkdir
• fs.open
• fs.readFile
• fs.readdir
• fs.readlink
• fs.realpath
• fs.rename
• fs.rmdir
• fs.stat
• fs.symlink
• fs.unlink
• fs.utimes
• fs.writeFile
• net.Socket#setTimeout
• readline.Interface#question
• repl.REPLServer#complete
• zlib.deflateRaw
• zlib.deflate
• zlib.gunzip
• zlib.gzip
• zlib.inflateRaw
• zlib.inflate
• zlib.unzip
• net.connectAsync
• tls.connectAsync
• crypto.randomBytesAsync
• crypto.pbkdf2Async
• crypto.pseudoRandomBytesAsync
• crypto.rngAsync
• crypto.prngAsync
• http.getAsync
• https.getAsync
• http.requestAsync
• https.requestAsync
• child_process.execAsync
• child_process.execFileAsync

[mgwalker]

(Using the current *Async naming for these. Will knock out more tomorrow when I'm not starting so late!)

LGTM signature dns.lookupService
LGTM signature dns.lookup
LGTM signature dns.resolve

LGTM signature fs.access
LGTM signature fs.appendFile
LGTM signature fs.chmod
LGTM signature fs.chown

[mgwalker]

LGTM signature fs.close
LGTM signature fs.exists
LGTM signature fs.fchmod
LGTM signature fs.fchown
LGTM signature fs.fdatasync
LGTM signature fs.fstat
LGTM signature fs.fsync
LGTM signature fs.ftruncate
LGTM signature fs.futimes
LGTM signature fs.lchmod
LGTM signature fs.lchown
LGTM signature fs.link
LGTM signature fs.lstat
LGTM signature fs.mkdir
LGTM signature fs.open
LGTM signature fs.readFile
LGTM signature fs.readdir
LGTM signature fs.readlink
LGTM signature fs.realpath
LGTM signature fs.rename
LGTM signature fs.rmdir
LGTM signature fs.stat
LGTM signature fs.symlink
LGTM signature fs.unlink
LGTM signature fs.utimes
LGTM signature fs.writeFile

[misterdjules]

May I suggest adding "Research potential fixes for nodejs#5084" in "Misc. Tasks"?

[benjamingr]

I recommend writing a short tool that compares the resolves/rejects with bluebird's promisifyAll that works for every proper nodeback API and has years of production experience in huge projects.