fs.realpath vs fs.realpath.native differences not documented

[didiercolens]

Affected URL(s)

https://nodejs.org/api/fs.html#fsrealpathpath-options-callback

Description of the problem

There is a difference in the errors thrown by fs.realpath and fs.realpath.native, when the path does not exist, fs.realpath throws an error with the path property set to the realpath stopping at the first subpath that does not exist, while the fs.realpath.native throws an error with the path property set to the value of the path argument.

Example:

> fs.realpath('does/not/exist', console.log)
undefined
> [Error: ENOENT: no such file or directory, lstat '/private/tmp/does'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'lstat',
  path: '/private/tmp/does' <==== real path until it does not exist
}
> fs.realpath.native('does/not/exist', console.log)
undefined
> [Error: ENOENT: no such file or directory, realpath 'does/not/exist'] {
  errno: -2,
  code: 'ENOENT',
  syscall: 'realpath',
  path: 'does/not/exist' <==== always same value as path argument
}

If this is intentional it should be documented.

This is particularly annoying because fsPromises.realpath runs fs.realpath.native and therefore a coder that would switch from fs.realpath to fsPromises.realpath would expect consistent behaviour and even if the documentation states the fsPrommises uses .native, it does not show the different behaviour highlighted above.

[juanarbol]

Hey, this is really good. Do you think you can send a PR documenting this? BTW, thanks again for the report

[didiercolens]

@juanarbol thank you, I need some guidance because errors are documented in https://github.com/nodejs/node/blob/main/doc/api/errors.md#class-systemerror and this behaviour is specific to 2 fs methods. Should I add a comment in fs.realpath describing the error.path property in case of ENOENT error?

[juanarbol]

I would extend the scope and put some references to the necessary errors.