fs/promises API inconsitency (.close not there)

[ChALkeR]

Currently, fs/promises provides a nearly identical API to fs, minus callbacks → promises change (obvious) and the fd → filenandle change (mostly invisible in most usecases).

The following parts of fs API are not present on fs/promises:

• *Sync methods (obvious)
• non-functions (ok)
• exists — kinda ok, since it was deprecated and never worked in a promisified variant. access is there.
• *Stream — well, kinda ok, not a promise.
• *watch* — also ok, it doesn't behave like promises.
• close — why?

All the other methods, except close, that are present on filehandle objects and in callback-based fs API are also present directly as methods of fs/promises API, accepting a filehandle. I assume that was done to ease the migration and provide 1:1 mapping between those where sensible, e.g. for people who were previously using promisified fs versions.

I don't see how close is different from other filehandle APIs, so in my opinion either of there two should happen:

• All the methods of fs/promises that accept a filehandle should be dropped in favor of the same methods on filehandle objects.
  This will avoid overcomplicating things, will declutter the docs and will save time future users figuring out the «canonical» way to do something.
• fs/promises should have as much of direct fs API duplicates as reasonable — basically, what we have now + .close should be added.
  This will ease migration for people who are already using the current fs API with (or without) promisify.

/cc @jasnell @Trott @BridgeAR

[ChALkeR]

The patch for adding close is trivial, I suppose:

async function close(handle) {
  validateFileHandle(handle);
  return handle.close();
}

Was it omitted for some actual reason?

[devsnek]

@ChALkeR I believe the design is such that it automatically closes when the handle is gc'd so manually closing it is kinda useless

[ChALkeR]

@devsnek It's there on the filehandle though: https://nodejs.org/api/fs.html#fs_filehandle_close

Also, manual closing is not useless, as close-on-gc could be delayed.

[jasnell]

closing manually is still the preferred choice, even when using FileHandle.prototype.close()... in fact, a warning will be emitted if the handle is closed on gc.

[jasnell]

@ChALkeR ... the reason there's no require('fs/promises').close is because it's already on FileHandle ... it would be redundant and largely unnecessary.

[ChALkeR]

@jasnell What's the difference with write, for example? That reasoning for not including close is equally applicable for not including write and sync (and others).

[ChALkeR]

@jasnell Ah, I suppose that I see what you are talking about — but those are mere implementation details mostly hidden from the users, It shouldn't infuence the API needlessly.

fs/promises exports sync in two variants: fsync(filehandle) FileHandle#sync(), write in two variants: write(filehandle, ... and FileHandle#write(..., the same for pretty much every method dealing with filehandles. But not close. What makes close special from the API PoV?

IMO, we should either export close(handle) method or not export fsync(handle)/write(handle,…/etc.

[jasnell]

Ah, right, yeah the variants on FileHandle were added after. I forgot about those. Ugh, yeah, if we're going to have those we might as well have close also

[Trott]

Oooh, this will simplify #20439, so yes please! :-D

[ChALkeR]

@jasnell @Trott As fs/promises is experimental, we could also remove methods that accept handles in favor of FileHande# variants. Both approaches (keeping 2 and switching to a single variant) have upsides and downsides. What do you think?

[Trott]

What do you think?

@ChALkeR No opinion from me other than whichever way we go, maximizing consistency in the API would be helpful (to me, at least).

@nodejs/fs

[Trott]

(OK, I guess I do slightly prefer having only one correct way to do something. But that would kind of argue against introducing fs.promises in core in the first place. In fact, it would probably argue against using JavaScript at all. So, again, I'll defer to others.)

[ChALkeR]

After thinking about this, my personal opinion is that, if the API would be kept as it is now (separate from fs), we should remove duplicate methods that accept filehandle as the fist argument. That should simplify things for the new users. If we merge it with fs — not sure, but probably the same.