fs.readdir recursive: is `parentPath` supposed to be the same as `path`?

[jonschlinkert]

Affected URL(s)

No response

Description of the problem

I'm curious what the purpose of parentPath is on Dirent objects when using fs.readdir or fs.readdirSync when both withFileTypes and recursive are set to true.

The reason for this issue is that I haven't found a situation where parentPath differs from path, it's always the same value. My hunch is that it's not supposed to be and there is probably a bug.

FWIW, I think it would be more useful to include the relative path versus parentPath, since parentPath is just the path.dirname(path) of each path, isn't it? If not, perhaps parentPath isn't the best name? Maybe it should be base or root or something?

[LiviaMedeiros]

This is correct, dirent.path and dirent.parentPath have the same value.

The only difference is that dirent.path is doc-deprecated with DEP0178. Users should use .parentPath in new projects and migrate from .path in old ones.
It's likely to become runtime-deprecated in the upcoming major release.

parentPath property has value of parent directory of its dirent, relative¹ to the current working directory.
E.g. for /a/b/c/d/e/f/g file, if our current working directory is /a/b and we do readdir('../b/c/d', ...) dirent for that file will look like { name: 'g', parentPath: '../b/c/d/e/f'}.

Historically, path property had path to the file itself and it got changed, which is why it's in process of being renamed to less ambiguous parentPath.

IMHO in direct comparison parentPath is preferable over relativePath, because likewise we can get relativePath value with just path.join(dirent.parentPath, dirent.name) as well as absolutePath with path.resolve(dirent.parentPath, dirent.name). However, internally readdir() deals with parentPath and by providing it directly we can skip doing path.join() for every dirent internally and path.dirname() in userspace.

Thus said, the issue of .path property with same value is planned to be fixed. :)
If you have suggestions on adding more useful properties (e.g. absolutePath) that are worth the performance cost of doing it internally, or maybe methods (e.g. dirent.resolve()), feel free to share the usecases.

Footnotes

1. in case if we passed absolute path to readdir, parentPath will also be absolute ↩

[aduh95]

Closing as answered, let us know if you have more questions.

[jonschlinkert]

I guess my only feedback is that it’s confusing that a new word is being coined for dirname. I had no idea what parentPath was supposed to mean, and I’ve published dozens of path libraries over the years. Why not just use dirname, for consistency with path.dirname()? Or dir, for consistency with path.parse() (which should have used dirname IMHO)?It’s ok, I’m not really asking you to justify your decisions or debate me, etc. I’m just throwing these things out for consideration, since I know I won’t be the only one thinking these things… tbh these are the types of inconsistencies that make people want to pull their hair out with Node. Sent from my iPhoneOn Mar 13, 2024, at 5:31 PM, Antoine du Hamel ***@***.***> wrote: Closing as answered, let us know if you have more questions. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you authored the thread.Message ID: ***@***.***>

[GabenGar]

Is it node-specific? Pretty sure the underlying issues with naming is inconsistent naming between OSes in the first place. I use folder in place of directory because that's how windows file explorer calls them. The entirety of fs module and its unix lingo was pretty painful to learn about because of it. And parentPath isn't technically a wrong term either, because it refers to the syntactic part of the path string (which may or may not be a directory when being opened), not the file system definition of directory.

[avivkeller]

Reopening with question label, as it seems this has become a question about the naming

[mitchellsimoens]

The way I see it is that parentPath and path are not always aliases in that they have the same values. Example:

const files = await readdir(path, { withFileTypes: true });

files here will have an array of DirEnt. this example, I would have a DirEnt with parentPath of the parent directory of the file whereas path is the full path of the file. This is the issue of calling them aliases, this is simply not always true.

To get the same path value, you need to do:

for (const file of files) {
  const filePath = path.join(file.parentPath, file.name);
}

Not optimal but if there are different OS reasons or whatever, not the end of the world either. However, the documentation does not lead you down this path either.