@addaleax ... because I know you'll ask.. this intentionally does not do the util.promisify() customization yet for a couple reasons. 1) because there are folks who use that in production today, I'd like to make sure this implementation is solid before switching... and 2) there's a discrepancy between methods like fs.fstat() and fs.promises.fstat() in that the former takes the numeric file descriptor and the latter takes the new FileHandle object.

My intent would be to land this as an experimental feature

Just fyi.. benchmark comparison for bench-stat vs bench-stat-promises (running in a vm on a laptop...)

$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 20,714.827782562465
fs/bench-stat-promise.js statType="lstat" n=200000: 15,589.439105836866
fs/bench-stat-promise.js statType="stat" n=200000: 22,186.395158011303

$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 13,882.790153144382
fs/bench-stat-promise.js statType="lstat" n=200000: 15,744.878475049993
fs/bench-stat-promise.js statType="stat" n=200000: 17,180.365568781977

$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 20,064.173934086277
fs/bench-stat-promise.js statType="lstat" n=200000: 16,715.911703541507
fs/bench-stat-promise.js statType="stat" n=200000: 17,014.91350175299

$ ./node benchmark/fs/bench-stat.js
fs/bench-stat.js statType="fstat" n=200000: 19,148.535379755922
fs/bench-stat.js statType="lstat" n=200000: 17,326.004694161828
fs/bench-stat.js statType="stat" n=200000: 18,626.09603864018

$ ./node benchmark/fs/bench-stat.js
fs/bench-stat.js statType="fstat" n=200000: 14,399.220751034958
fs/bench-stat.js statType="lstat" n=200000: 14,749.28092887841
fs/bench-stat.js statType="stat" n=200000: 21,620.088712923043

$ ./node benchmark/fs/bench-stat.js
fs/bench-stat.js statType="fstat" n=200000: 19,873.273062278913
fs/bench-stat.js statType="lstat" n=200000: 23,040.86746115833
fs/bench-stat.js statType="stat" n=200000: 27,742.886612762228

1. This is going to be a talkative PR, so please, feel free to delete any of my comments if they are not appropriate or will not be hidden after addressing (or even if they will be hidden).

2. Is the omission of the fs.write(fd, string[, position[, encoding]], callback) variant intended?

3. If I get it right, the promises API doc part is not as full as the callback API part (some examples and notes are omitted). Is it worth to mention this in the intro part? Like "for more info see callback API counterparts"?

@vsemozhetbyt ... as always I love your reviews of my doc commits. Thank you for being so thorough. Yes, the omission of the fs.write(fd, string, position, encoding, callback) variant is intentional.

I plan to go back and add better examples either in an iteration of this PR or a future one.

Thanks for this. This is great.

Can we have a shorter namespace though? Something like fs.p (or fs.prom if fs.p is too terse)? It'd be painful if I have to type fs.promises all the time.

@jasnell You may also need to update the appropriate counterparts according to that PR (I've found those missing types reviewing this PR :) ).

@jasnell Your benchmark run seems to suggest that the promise performance is already quite good compared to the callback version. Although that is of course a micro-benchmark. Do you have a representative (macro-)benchmark?

cc @psmarshall

Yep and rightfully so given that they mostly use exactly the same internal mechanisms. The differences are quite minimal thankfully. Where they are different is in the creation of the additional promise and the additional overhead of the promise hook, both of which are fairly minimal.

I do not yet have a macro benchmark in place. It'll likely take bit to get that.

One thing I did notice is that there are about twice as many GC runs in the promises microbenchmark, which is not at all surprising but is certainly worth noting.

@jasnell Did you see #17739 (comment) from @gsathya? That might be worth investigating.

I don't know if we should discuss this here but I have a concern with the interaction of fs.promises and ESM (related to #18131).
We are committed to making ESM a first class feature in Node, but with the current way things are going, it will be difficult to provide the Promise APIs in an ESM-friendly way (no way to directly import a specific promisified method).
It seems the only way would be to have the Promise API in another module. Examples: require('fs.promise'), require('fs/promise')

@bmeurer ... Yeah, I'm working that way but wanted to get all of the js functions impl'd to make sure we would be able to completely eliminate creating the FSReqPromise object in js. I've got a way forward on that now that should work nicely, tho I'll have to test that it does not negatively impact the perf of the callback approach first.

@targos ... definitely a valid concern, will have to think about that a bit more. FWIW, we would have precisely the same issue with path.win32and path.posix, and likely several other bits of core API, so I'm not sure if solving it just for fs.promises is the right thing or if we should come with a more general solution.

@bmeurer ... updated to eliminate the creation of FSReqPromise in JS land, Definitely makes a difference.

james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 21,609.73968730913
fs/bench-stat-promise.js statType="lstat" n=200000: 13,606.886508071122
fs/bench-stat-promise.js statType="stat" n=200000: 20,361.793179169545
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 19,382.167235983314
fs/bench-stat-promise.js statType="lstat" n=200000: 14,694.606891503132
fs/bench-stat-promise.js statType="stat" n=200000: 13,698.616828686227
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 28,453.65135200578
fs/bench-stat-promise.js statType="lstat" n=200000: 13,697.273150949744
fs/bench-stat-promise.js statType="stat" n=200000: 18,633.918977446763
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 16,870.88056950238
fs/bench-stat-promise.js statType="lstat" n=200000: 13,472.76114383914
fs/bench-stat-promise.js statType="stat" n=200000: 26,460.504276421147
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat.js
fs/bench-stat.js statType="fstat" n=200000: 36,322.48835345608
fs/bench-stat.js statType="lstat" n=200000: 15,002.883243224593
fs/bench-stat.js statType="stat" n=200000: 22,319.499506552078
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat.js
fs/bench-stat.js statType="fstat" n=200000: 32,136.6980781016
fs/bench-stat.js statType="lstat" n=200000: 14,883.592505458588
fs/bench-stat.js statType="stat" n=200000: 25,631.456606611602
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat.js
fs/bench-stat.js statType="fstat" n=200000: 31,111.359958434878
fs/bench-stat.js statType="lstat" n=200000: 22,671.7262379716
fs/bench-stat.js statType="stat" n=200000: 17,104.025292210692
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 30,095.77601510028
fs/bench-stat-promise.js statType="lstat" n=200000: 24,965.011103171837
fs/bench-stat-promise.js statType="stat" n=200000: 27,054.78894406488
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 30,281.66760510009
fs/bench-stat-promise.js statType="lstat" n=200000: 23,380.61184604834
fs/bench-stat-promise.js statType="stat" n=200000: 27,438.146664427066
james@ubuntu:~/node/node$ ./node benchmark/fs/bench-stat-promise.js
fs/bench-stat-promise.js statType="fstat" n=200000: 26,104.278785435945
fs/bench-stat-promise.js statType="lstat" n=200000: 20,969.553527682114
fs/bench-stat-promise.js statType="stat" n=200000: 13,553.763324970801

@jasnell Cool! 👍 Kudos to @gsathya for the finding!

@targos makes a great point in #18297 (comment).

I'd be a definite +1 on require('fs/promise') / require('fs-promise') / require('fs.promise') require('fsp') or similar to ensure ES module compatibility. ES module parity should be a primary consideration for all API changes at this point.

@jasnell if we were implementing path.posix today the same suggestion would apply, but given it's a stable API it probably doesn't make sense to change now - import { posix } from 'path' seems less costly as it's a much rarer API use case anyway than import { readFile } from 'fs-promise'.

Landed in df34029, 7154bc0, 85b37db and 329fc78. woot!