doc: improve fs.utimes

[refack]

AFAICT the internal conversion helper toUnixTimestamp has always been able to convert Dates - https://github.com/nodejs/node/commit/1d5ff15
Currently precision is platform dependant, but that could be fixed.

@nodejs/platform-aix - Should the AIX >= 7.1 note be added to utimes as well? #14154 (comment)

/cc @bnoordhuis @nodejs/fs

Checklist

• mdlint passes
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc,fs

[refack]

/cc @nodejs/documentation

[vsemozhetbyt]

Still "an Error"?

[benjamingr]

What happens if Invalid Date is passed?

Also, if we can pass a string that gets coerced to numbers, then I'm not sure we should put string in the docs.

[refack]

1. Still an Error in master - https://github.com/nodejs/node/blob/master/lib/fs.js#L1196
2. Even a Date is converted (or coerced) to number so the sentence still stands true (Number(new Date("foo")) === NaN), just missing an explicit mention.

[vsemozhetbyt]

@refack Sorry, I meant a nit, still "an", not "a")

[refack]

@benjamingr the string note was alway there. As for the arg type I think it's better to explicitly state string but this is JS1.0 semantics so we need to ask ourselves WWDCD?
_{What Would Douglas Crockford Do}

[refack]

@refack Sorry, I meant a nit, still "an", not "a")

Ack. But I'm not pushing a fix yet, so the string conversation will stay open.

[gireeshpunathil]

Should the AIX >= 7.1 note be added to utimes as well?

No:

bash-4.3$ uname -a
AIX 1 6 00F460A94C00
bash-4.3$ touch g.txt
bash-4.3$ cat utimes.js 

var fs = require('fs')
fs.utimes(process.argv[2], 1, 2, () => {
  const stat = fs.statSync(process.argv[2])
  console.log(`file modified at ${stat.mtime} and accessed at ${stat.atime}`)
})

bash-4.3$ ./node utimes.js g.txt
file modified at Thu Jan 01 1970 00:00:02 GMT+0000 (EST) and accessed at Thu Jan 01 1970 00:00:01 GMT+0000 (EST)

[refack]

Should the AIX >= 7.1 note be added to utimes as well?

No:

That's surprising since intuitively I'd assume utimes(path) := futimes(open(path)), but if no one complains 🤷‍♂️

[gireeshpunathil]

basically fs.utimes is implemented by uv__fs_utimes and fs.futimes by uv__fs_futime and underneath mapping to system calls of the same name in most of the unixens, but platform specificity applies. AIX cases are here and here.

[BridgeAR]

Where do we stand here?

[BridgeAR]

@refack as far as I see it there is little to do to get this ready to land, right?

I would otherwise close the PR sometime soon.

[BridgeAR]

Landed in 64e97b2