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

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

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

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.

@jasnell

Refs: #18297 (comment) and next comment:

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

so cc @jasnell

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

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

Doc omission. The variant should be doc'd.

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

@BridgeAR

@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.

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?

@BridgeAR

@BridgeAR The ones I noticed:

callbacks → promises
fd → filehandle
constants not there (fs.constants, fs.*_OK),
classes not there (fs.Stats, fs.WriteStream, etc.),
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.
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

@ChALkeR

@ChALkeR thanks for pointing these things out.

@ChALkeR

@ChALkeR @jasnell Hey folks, I just submitted a docs PR for this issue. I hope it helps in some way. I've raised some questions in there. Cheers!

doc: add filehandle.write(string[, position[, encoding]])

Navigation Menu

Repository navigation

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

6 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Activity

ChALkeR commented on Apr 29, 2018

BridgeAR commented on Apr 29, 2018

vsemozhetbyt commented on Apr 29, 2018

ChALkeR commented on Apr 29, 2018

ChALkeR commented on Apr 30, 2018

jasnell commented on Apr 30, 2018

jasnell commented on Apr 30, 2018

jasnell commented on Apr 30, 2018

BridgeAR commented on Apr 30, 2018

ChALkeR commented on May 8, 2018

BridgeAR commented on May 8, 2018

6 remaining items

darahayes commented on Oct 2, 2018

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions