writeFileSync data as Object throws type error despite docs listing Object as a supported type

[JakobJingleheimer]

• Version: 14.17.0 & 16.4.0
• Platform: local 20.5.0 Darwin Kernel Version 20.5.0: Sat May 8 05:10:31 PDT 2021; root:xnu-7195.121.3~9/RELEASE_ARM64_T8101 arm64
• Subsystem: FS / Docs

What steps will reproduce the bug?

import { writeFileSync } from 'fs';

writeFileSync('test.log', { foo: 'bar' });

How often does it reproduce? Is there a required condition?

100% (no special conditions)

What is the expected behavior?

The type(s) for data listed in the docs to work.

What do you see instead?

TypeError [ERR_INVALID_ARG_TYPE]: The "data" argument must be of type string or an
instance of Buffer, TypedArray, or DataView. Received an instance of Object
    at writeFileSync (node:fs:2136:5)

Additional information

fs docs for 14.x and 16.x both include <Object> as a type for writeFileSync's data argument:

data <string> | <Buffer> | <TypedArray> | <DataView> | <Object>

[mscdex]

The object has to have a toString() function on the object itself and not one inherited via prototype.

Unfortunately it seems the documentation did not get updated properly for every API that was touched by these changes (#34993).

[chloebrett]

I think the current documentation is sufficient. The docs for writeFileSync (link) specifies:

For detailed information, see the documentation of the asynchronous version of this API: [`fs.writeFile()`][].

And for writeFile (link):

If `data` is a normal object, it must have an own `toString` function property.

If we added this line to every function with similar parameters to writeFile, then we'd need to add all the other notes as well:

When `file` is a filename, asynchronously writes data to the file, replacing the
file if it already exists. `data` can be a string or a buffer.

When `file` is a file descriptor, the behavior is similar to calling
`fs.write()` directly (which is recommended). See the notes below on using
a file descriptor.

The `encoding` option is ignored if `data` is a buffer.
If `data` is a normal object, it must have an own `toString` function property.

Makes more sense to me to have the specifics detailed under writeFile and direct people to them for all the related functions, which is what we currently do.

[JakobJingleheimer]

Ah yes. I think the asterisk as @mscdex described should be added. Otherwise it feels like Gryzzl's T&Cs.

The object needing to have an own toString() method is a pretty big gotcha as it is.

[chloebrett]

@JakobJingleheimer definitely agree it could be clearer - where would this be added though?

[JakobJingleheimer]

I think the various (writeFile, writeFileSync, etc) type defs should all have the asterisk, and it would be fine for the related caveat to be detailed in the one place.

I can put together a PR for that if acceptable 🙂

[chloebrett]

Sure thing. (I'm not an official contributor/maintainer btw, just someone who stumbled across this issue)

While you're at it might be worth doing the same for writeSync as well, as it's the same story

[JakobJingleheimer]

Sure! I was thinking to add the asterisk for all related to this (which already link back to the 1 detailed explanation).

Incoming