More detailed `fs` documentation

[jamestalmage]

The fs docs provide a great overview of the API, but information on their low-level operations is pretty sparse.

For example, I can't tell how two competing fs.writeFileSync calls from different processes will interact. Will an error be thrown by whichever process loses the race for the lock? Will the second process just wait for the lock and then overwrite the previous contents?

For reference, here are two issues would have benefited from these sorts of details:

• Caching istanbuljs/nyc#101 (comment)
• Issues with cross-process concurrency sindresorhus/configstore#20 (comment)

[bnoordhuis]

Your specific example about fs.writeFileSync() is something we would probably accept pull requests for but your general request ("more detailed fs documentation") is, well, too general to be actionable.

The fs docs provide a great overview of the API, but information on their low-level operations is pretty sparse.

In many cases they're light wrappers around their POSIX counterparts. This is hinted at if not outright mentioned in quite a few places in doc/api/fs.markdown.

For example, I can't tell how two competing fs.writeFileSync calls from different processes will interact. Will an error be thrown by whichever process loses the race for the lock? Will the second process just wait for the lock and then overwrite the previous contents?

There is no lock beyond the intrinsic synchronization that the operating system provides for concurrent requests, which isn't much. File locks are surprisingly broken.

[Fishrock123]

This is related to #4375 i.e. more detailed description of what man(N) actually means and possibly links to a general posix doc.

[sindresorhus]

intrinsic synchronization that the operating system provides for concurrent requests, which isn't much

What kind of synchronization is that? It's still unclear what will happen if two processes try to fs.writeFileSync to the same file at once? Would be useful if the docs answered that or at least linked to something that does.

File locks are surprisingly broken.

Computers in general are.

[jamestalmage]

In many cases they're light wrappers around their POSIX counterparts. This is hinted at if not outright mentioned in quite a few places in doc/api/fs.markdown.

Yes, and I spent some time googling before posting ("posix", "posix file system api", etc.). That led me to unhelpful resources that explained little more than the acronym, or incredibly dense resources that were fairly overwhelming and I certainly could not find a "counterpart" for writeFileSync.

Honestly, the most helpful thing I have done so far is read the source, but that has hardly given me a definitive answer.

possibly links to a general posix doc

That would be a start, but I think it needs more. Obviously, it is a difficult to strike a balance between approachability and thoroughness on a topic like this, so maybe a link to an external resource is the best we can do. I would prefer it be one that was written for Node users, as much of the POSIX documentation I have found so far is pretty hard to grok.

[jasnell]

btw, this is something that I'm working on. expect a PR with significant modifications soon

[bnoordhuis]

The documentation has seen (and continues to see) significant improvements since this issue was filed so I'll go ahead and close it out. Pull requests are of course still welcome.