Help Land Promises in Core

[chrisdickinson]

Ref https://github.com/nodejs/node/pull/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 :+1: 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 https://github.com/nodejs/node/issues/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.