feat(path): single file exports

[lino-levan]

Related #687.

Future PRs:

• BREAKING: Add "os" argument
• BREAKING: Rename some methods to make them more intuitive (by @nayeemrmn on discord)
  • basename() -> fileName()
  • dirname() -> parent()
  • extname() -> extension()

[kt3k]

Move to single export file structure looks good to me, and it's probably less controversial to other points if it doesn't have breaking changes. Can we only do the move to single-file export without API design changes in this PR?

Add "os" argument
Make some breaking changes to APIs to allow for more options in the future

These points seem needing more discussion, also these 2 changes don't seem necessarily in the same PR. Maybe try them later PRs?

[lino-levan]

I guess you're right, but I just wanted to bundle breaking changes together. I'm not sure what the best way to move forward with single-file exports is. Should we expose posixX() and windowsX() to the user? Does that naming make any sense?

[kt3k]

I think we can also update mod.ts to use new implementations and that should make the rendering of this page better.

Should we expose posixX() and windowsX() to the user?

I don't think so. The names sound strange to me.

I don't think we should deprecate win32.ts and posix.ts in this PR. I think that should be discussed together with Add "os" argument issue

[kt3k]

Also can you add the license headers // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license. to the new files?

[lino-levan]

Alright, un-deprecating posix.ts and win32.ts (and not updating their implementations) in this PR. I'll change mod.ts to re-export the single-file exports.

[lino-levan]

I guess this module will have quite the turbulent future. This should no longer be a breaking change (even if I personally think it should be). We now have duplicated implementations between posix.ts + win32.ts and the single-file exports. If we add an OS argument (or export the internal functions), we should be able to consolidate them.

[lino-levan]

Updated the original comment for future os argument PR. This should be reviewable now.

[iuioiua]

Sidenote: each function in this sub-module should have JSDocs. I guess this can be done in a follow-up PR.

[lino-levan]

With #3515, is there any value in keeping posix.ts and win32.ts? To clarify, not suggesting to remove it in this PR. I think this PR accomplishes the goal in the title just fine.

[kt3k]

It looks like in most test cases, the APIs are called via path.posix or path.win32. So with this change, new implementations are note tested in CI.

Can you also replace the APIs under path.posix and path.win32 with the new ones?

I think each platform specific function (like windowsBasename) should work independently, and we should re-export it as platform specific version.

[lino-levan]

I would need to export windowsX and posixX to do this. Are we committed to doing that?

[lino-levan]

Alternatively, which is what I initially pushed for, we could implement an os argument, and keep those implementations internal while still being able to test them. Additionally, we would be able to "re-export" the new implementations in posix.ts and win32.ts.

I don't think we should make our API surface larger over this, especially with the naming as it is.

[kt3k]

I don't think we should make our API surface larger over this, especially with the naming as it is.

I agree.

How about moving platform specific implementations of, for example, basename (windowsBasename and posixBasename) to _basename.ts? We can use them from basename.ts, posix.ts, and win32.ts, but they are still private from the users

[lino-levan]

That seems reasonable. I'll go ahead with that.

[lino-levan]

I was skeptical at first, but I'm now convinced that this was the way to do it. Thanks for the suggestion @kt3k! This should now really be ready for review.

[iuioiua]

Few nits. Otherwise, LGTM! Nice.

[kt3k]

LGTM. Nice work! @lino-levan

I'd tag this change as feat as newly available paths can be considered as new features.