feat(fs): introduce canonicalize option to WalkOptions

[powdream]

Introduces a new option canonicalize to WalkOptions.

Currently, when followSymlinks is enabled, walk() function emits the canonical paths of the symlinks, which is transformed with Deno.realPath(). However, if the false is given for canonicalize option, the symlinks would be kept without canonicalizing.

To keep the existing behavior of walk API, canonicalize defaults to true.

Example

root
  + a
     - 1
     - 2
  + b
    - a -> ../a

As-is

walk(b, { followSymlinks: true })

=> ["../a", "../a/1", "../a/2"]

To-be

walk(b, { followSymlinks: true })

=> ["../a", "../a/1", "../a/1"]

walk(b, { followSymlinks: true, canonicalize: false })

=> ["a", "a/1", "a/2"]

[timreichen]

I think useRealPath as a name does not clearly express the functionality.
Maybe it should be renamed to something like resolveSymlinksToRealPaths or resolveSymlinks.

[powdream]

I think useRealPath as a name does not clearly express the functionality. Maybe it should be renamed to something like resolveSymlinksToRealPaths or resolveSymlinks.

Thanks for the suggestion.
I'd like to vote for resolveSymlinksToRealPaths even if it is longer than resolveSymlinks, since resolveSymlinks sounds a bit confused because of followSymlinks.
Then, can I go with resolveSymlinksToRealPaths?

[timreichen]

Another one that comes into mind is resolveSymlinkPaths. realPath kinda suggests symlink paths not to be real. I think we should make a collection of possible names and do a poll on what would work best.

[powdream]

Then, let me list up possible candidates here:

1. useRealPath: Not clear
2. resolveSymlinksToRealPaths
3. resolveSymlinks: Sounds similar to followSymlinks
4. resolveSymlinkPaths
5. resolvePaths
6. replaceSymlinksWithRealPaths
7. resolveSymlinksToCanonicalPaths
8. canonicalize

[jollytoad]

resolveToCanonicalPaths?
or just canonical or canonicalize?

A canonical path is the general term used when a path has been normalized and all symlinks folllowed

[powdream]

I have no idea whether we can call the result of Deno.realPath() a canonical path. What do you think?

[jollytoad]

It's a canonical path...
Deno.realPath would most probably be based on the underlying posix fn... realpath which states:

return the canonicalized absolute pathname

GNU even provides an alternative... canonicalize_file_name, as the posix realpath has a design flaw.

I agree with @timreichen that realpath is a bad name, but it's just an unfortunate history carried over from posix, many other languages and operating systems (including Windows) use the term canonical. Tbh, I'm surprised that Deno carried this legacy over and didn't seek to use a more accurate term like canonicalPath.

I think the choice should be down to either base the name on the correct term canonical, or on the name of the underlying fn call, ie. realPath ... throwing the terms follow or symlinks don't really help.

Just my humble opinion.

[powdream]

@jollytoad
Thanks for your opinion for this topic. It sounds reasonable. I wasn't aware of whether there is historical reason for the name. If we can use the term "canonical" path in this case, "resolveSymlinksToCanonicalPath" sounds very fair enough.

[jollytoad]

tbh, i'd suggest canonicalize is probably enough, all other words are redundant.

[powdream]

I'd like to vote for the word normalize instead of canonicalize for consistency with other path-related APIs.
In path module, normalize function already exists but not canonicalize.

How does the following look to other guys?

walk(b, { followSymlinks: true, normalizeSymlinks: false })

[jollytoad]

normalize means a different thing, it's to resolve '..' and '.' segments in the path, where-as canonicalize also does this AND resolves symlinks until the path references a concrete file. Deno has unfortunately used the questionable term realPath (based on the historical usage in the posix API) rather than the correct term canonicalPath. If it's a question of consistency with the existing API, which is perfectly valid, then the most sensible option is to use realPath.

normalize is not the right term here, the correct term is canonicalize, but a reasonable name could also be based on realPath as it's the underlying API used (but that is difficult to turn into a verb). Anyway, that's enough bike-shedding from me.

[powdream]

I'm persuaded. Then, let me address it.

[kt3k]

Sorry for the delay in review.

LGTM. Thanks for your contribution!