fs: promises have undocumented write(string,…) method

[ChALkeR]

• Version: 10.0.0, master
• Subsystem: fs

Non-promises API has two variants documented: Buffer, string.

Promises API has only Buffer variants documented: method, class method.

This code works, but it's undocumented behavior:

const fs = require('fs/promises');
const fd = await fs.open('temp.txt', 'w+');
fd.write('test\n');

[ChALkeR]

Not sure if this is a documentation issue. Should we keep that API in such form?

[BridgeAR]

Without looking into it further: as far as I know the promises API should be identical to the non-promise one besides returning promises. So it sounds like a documentation issue.

[vsemozhetbyt]

Refs: #18297 (comment) and next comment:

Yes, the omission of the fs.write(fd, string, position, encoding, callback) variant is intentional.

so cc @jasnell

[ChALkeR]

It's undocumented, but present and partially broken — see #20407.

[ChALkeR]

Note that according to coverage report, that variant is called once, which means that there is a test that depends on it being present.

[jasnell]

Doc omission. The variant should be doc'd.

[jasnell]

It was a to-do that I never went back to. Although if I recall correctly there may need to be some reconcilation still with the non-promise version

[jasnell]

@BridgeAR ... To be certain the promise certain is not identical. There are intended differences... Such as the use of the FileHandle object rather than numeric fd.

[BridgeAR]

That does not sound intuitive to me at all. I would have expected it is fine to switch to promises 1-to-1. Can you outline the specific differences / where there a lot of these?

[ChALkeR]

@BridgeAR The ones I noticed:

1. callbacks → promises
2. fd → filehandle
3. constants not there (fs.constants, fs.*_OK),
4. classes not there (fs.Stats, fs.WriteStream, etc.),
5. some methods are not there, see fs/promises API inconsitency (.close not there) #20548 — close, *Stream, *watch*, *Sync, exists. fs: drop duplicate API in promises mode #20559 should remove even more.
6. return values is different

Example:

> await (await fsp.open('test.txt', 'w')).write('test')
{ bytesWritten: 4, buffer: 'test' }
> fs.writeSync(fs.openSync('test.txt', 'w'), 'test')
4