Please document fs.WriteStream.path

[rogierschouten]

WriteStreams have a .path property with the path of the file they write to. Please document this property so that I can reliably use it without fear of it being an unsupported feature. This will also enable me to put it into node.d.ts and push that to DefinitelyTyped.

[bnoordhuis]

I don't know, it has a bunch of undocumented properties; the reason they're not underscore-prefixed is mostly an accident of history.

[claudiorodriguez]

Among these, only bytesWritten is documented, the rest are not:

this.path = path;
this.fd = options.fd === undefined ? null : options.fd;
this.flags = options.flags === undefined ? 'w' : options.flags;
this.mode = options.mode === undefined ? 0o666 : options.mode;
this.start = options.start;
this.pos = undefined;
this.bytesWritten = 0;

At this point it would be a serious breaking change to prefix them all with underscores, of course, but exposing them would require some more clarification IMHO. From what I'm seeing, the first implementation of these was by @felixge
cc @nodejs/fs ?

[rogierschouten]

The reason I use the path property is that I get a WriteStream from an NPM module that makes temp files with random names. I need to get that random name and WriteStream#path is the only way to do it. I don't see why these couldn't be made public, apparently people are relying on this.

[claudiorodriguez]

Well, it -has- been there since Mar 2010 at least.

[mscdex]

@rogierschouten Seems like that module could just return the name it used?

[felixge]

To provide some historical context. I implemented WriteStream over 5 years ago. At this time node core didn't have much coding conventions and objects often exposed "private" properties without any indication (see 1, 2). IIRC Ryan disliked the '_' prefix convention back then, possibly out of resentment for Python.

As far as the path property is concerned, I don't recall if I intended it to be private or not, but at this point I'd just document it as an official property. Having a mechanism for getting the path seems very useful, and I can only imagine how much code in the wild already depends on the existence of the path property as-is.

[aredridel]

I've written code that depends on this for sure.

[jasnell]

Landed