Clean up platform specific APIs of `path` module

[kt3k]

We currently expose platform specific APIs like the below:

import { posix, win32 } from "https://deno.land/std@0.200.0/path/mod.ts";

or

import * as win32 from "https://deno.land/std@0.200.0/path/win32.ts";
import * as posix from "https://deno.land/std@0.200.0/path/posix.ts";

I think this has 2 problems:

• There's no way to import single implementation of platform specific API
• 'posix' and 'win32' keywords don't match the way we usually specify the platform name (i.e. it doesn't match to Deno.build.os)

One way to solve this is to implement #687

part of #3489

[lino-levan]

'posix' and 'win32' keywords don't match the way we usually specify the platform name

I'm in favor of renaming win32.ts->windows.ts. It's unclear to me what posix.ts could be renamed to while keeping it's semantic meaning.

One way to solve this is to implement #687

As I've mentioned before, I'm not quite sure how to go about implementing this. There are some APIs (resolve and friends) which don't fit well into adding an optional argument. Breaking changes would almost certainly be required.

[kt3k]

There are some APIs (resolve and friends) which don't fit well into adding an optional argument.

Something like the below seems working. Does this help designing it?:

type OS = "windows" | "linux" | "darwin" | "freebsd";

function resolve(...args: string[]): string;
function resolve(...args: [...string[], { os: OS }]): string;
function resolve(...args: any[]): string {
    //
    return "...";
}

resolve("a", "b");
resolve("a", "b", { os: "windows" });

[lino-levan]

Ah, fair enough, I never really got the hang of overloading typescript functions 😅. Seems like a reasonable and non-breaking change. I'll pick this up later today.

[jollytoad]

I made a suggestion for this here... https://github.com/denoland/deno_std/discussions/3553

Adding an os option is overkill and unnecessary.

Also there is no need for more than the two platforms... posix and windows

[kt3k]

#3553 might be fine too. I'm curious what people think about these options.

[lino-levan]

Either way makes sense to me. The complexity is about the same either way.

[kt3k]

I now feel #3553 is better as it allows more granular imports. With os-argument proposal, platform-specific single operation is not importable. Also dynamic nature of os-argument doesn't look useful to me (I can't think of the case where dynamic os argument is absolutely necessary).

Also Os-argument proposal has tricky typing with join and resolve methods (See this for example). On the other hand, #3553 doesn't require any typing change and looks straightforward.

I'll work on implementing #3553

[jollytoad]

@kt3k I had a bash at this, let me push and share the branch so far, it's not well tested, but after doing this I have concerns.

[jollytoad]

I'd not pushed this sooner as I had some concerns after doing it...

1. My main motivation for this split was so you could just remap the path modules to a specific OS using an import map.

For example:

"imports": {
   "https://deno.land/std@0.xxx.0/path/": "https://deno.land/std@0.xxx.0/path/posix/"
}

I feel that remapping onto a subpath may be problematic, but I've not had chance to test this idea yet, maybe it'll be fine, I'm not sure yet!

Maybe if the sub-path is a problem, using a sibling structure would be better, eg: ".../path/": ".../path_posix/"?

2. Despite feeling this is technically a better way to approach this problem, the overall outcome makes me feel somewhat uncomfortable, I can't quite put my finger on it. (It's probably just the shear scale of the PR)

3. glob doesn't fit neatly into the pattern as it already had an OS switch option ... but i've attempted to refactor this too. TBH, glob feels a little out of place to me being in path, it's a lot more complex than other fns, and provides multiple fns from it's module, feels like it should probably live in a top-level module of its own.

[jollytoad]

Ah, I remember, my main concern about remapping... if you remap /path/ to /path/posix/ for example, then anything that uses /path/posix/ directly may get mapped to /path/posix/posix/, which isn't ideal.

How would you feel about top level /path_posix & /path_windows & an internal dir for common modules (/_internal/path or /_path_common for example?)

I'd suggest this could be a reasonable common pattern for std lib and even encourage other modules to adopt where a feature can have multiple implementations and support runtime and import map switching, eg: /<feature> (switches at runtime), /<feature>_<variant> (use by the runtime switch modules, or can be mapped to) ... consumers should generally use the /<feature> so that it can get switched globally by an import map.

[jollytoad]

I've raised an alternative PR #3650 to explore this option ^

[kt3k]

@jollytoad

I feel that remapping onto a subpath may be problematic

If there are overlapping import map keys, the most specific one has the effect (according to this WICG/import-maps#113 )

I think the below should work.

"imports": {
   "https://deno.land/std@0.xxx.0/path/posix/": "https://deno.land/std@0.xxx.0/path/posix/"
   "https://deno.land/std@0.xxx.0/path/windows/": "https://deno.land/std@0.xxx.0/path/windows/"
   "https://deno.land/std@0.xxx.0/path/": "https://deno.land/std@0.xxx.0/path/posix/"
}