BREAKING(path/unstable): move unstable overload of join to unstable-join (#5964)

_tools/check_docs.ts

@@ -77,6 +77,7 @@ const ENTRY_POINTS = [
   "../path/unstable_basename.ts",
   "../path/unstable_dirname.ts",
   "../path/unstable_extname.ts",
+  "../path/unstable_join.ts",
   "../path/posix/mod.ts",
   "../path/windows/mod.ts",
   "../random/mod.ts",

path/deno.json

@@ -41,6 +41,7 @@
     "./posix/unstable-basename": "./posix/unstable_basename.ts",
     "./posix/unstable-dirname": "./posix/unstable_dirname.ts",
     "./posix/unstable-extname": "./posix/unstable_extname.ts",
+    "./posix/unstable-join": "./posix/unstable_join.ts",
     "./relative": "./relative.ts",
     "./resolve": "./resolve.ts",
     "./to-file-url": "./to_file_url.ts",
@@ -49,6 +50,7 @@
     "./unstable-basename": "./unstable_basename.ts",
     "./unstable-dirname": "./unstable_dirname.ts",
     "./unstable-extname": "./unstable_extname.ts",
+    "./unstable-join": "./unstable_join.ts",
     "./windows": "./windows/mod.ts",
     "./windows/basename": "./windows/basename.ts",
     "./windows/common": "./windows/common.ts",
@@ -71,6 +73,7 @@
     "./windows/to-namespaced-path": "./windows/to_namespaced_path.ts",
     "./windows/unstable-basename": "./windows/unstable_basename.ts",
     "./windows/unstable-dirname": "./windows/unstable_dirname.ts",
-    "./windows/unstable-extname": "./windows/unstable_extname.ts"
+    "./windows/unstable-extname": "./windows/unstable_extname.ts",
+    "./windows/unstable-join": "./windows/unstable_join.ts"
   }
 }

path/join.ts

@@ -23,26 +23,6 @@ import { join as windowsJoin } from "./windows/join.ts";
  * @param paths Paths to be joined and normalized.
  * @returns The joined and normalized path.
  */
-export function join(...paths: string[]): string;
-/**
- * Join all given a sequence of `paths`, then normalizes the resulting path.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { join } from "@std/path/posix/join";
- * import { assertEquals } from "@std/assert";
- *
- * const path = join(new URL("file:///foo"), "bar", "baz/asdf", "quux", "..");
- * assertEquals(path, "/foo/bar/baz/asdf");
- * ```
- *
- * @param path The path to join. This can be string or file URL.
- * @param paths The paths to join.
- * @returns The joined path.
- */
-export function join(path?: URL | string, ...paths: string[]): string;
-export function join(path?: URL | string, ...paths: string[]): string {
-  return isWindows ? windowsJoin(path, ...paths) : posixJoin(path, ...paths);
+export function join(...paths: string[]): string {
+  return isWindows ? windowsJoin(...paths) : posixJoin(...paths);
 }

path/join_test.ts

@@ -3,10 +3,13 @@ import { assertEquals } from "@std/assert";
 import * as posix from "./posix/mod.ts";
 import * as windows from "./windows/mod.ts";
 import { join } from "./join.ts";
+import { join as posixUnstableJoin } from "./posix/unstable_join.ts";
+import { join as windowsUnstableJoin } from "./windows/unstable_join.ts";
 
 const backslashRE = /\\/g;
 
-type TestCase = [string[] | [URL, ...string[]], string];
+type TestCase = [string[], string];
+type UrlTestCase = [[URL, ...string[]], string];
 
 const joinTests: TestCase[] =
   // arguments                     result
@@ -58,16 +61,18 @@ const joinTests: TestCase[] =
     [["/", "", "/foo"], "/foo"],
     [["", "/", "foo"], "/foo"],
     [["", "/", "/foo"], "/foo"],
-
-    // URLs
-    [[new URL("file:///"), "x/b", "..", "/b/c.js"], "/x/b/c.js"],
-    [[new URL("file:///foo"), "../../../bar"], "/bar"],
-    [
-      [new URL("file:///foo"), "bar", "baz/asdf", "quux", ".."],
-      "/foo/bar/baz/asdf",
-    ],
   ];
 
+const joinUrlTests: UrlTestCase[] = [
+  // URLs
+  [[new URL("file:///"), "x/b", "..", "/b/c.js"], "/x/b/c.js"],
+  [[new URL("file:///foo"), "../../../bar"], "/bar"],
+  [
+    [new URL("file:///foo"), "bar", "baz/asdf", "quux", ".."],
+    "/foo/bar/baz/asdf",
+  ],
+];
+
 // Windows-specific join tests
 const windowsJoinTests: TestCase[] = [
   // arguments                     result
@@ -116,6 +121,8 @@ const windowsJoinTests: TestCase[] = [
   [["c:.", "file"], "c:file"],
   [["c:", "/"], "c:\\"],
   [["c:", "file"], "c:\\file"],
+];
+const windowsJoinUrlTests: UrlTestCase[] = [
   // URLs
   [[new URL("file:///c:")], "c:\\"],
   [[new URL("file:///c:"), "file"], "c:\\file"],
@@ -130,6 +137,14 @@ Deno.test("posix.join()", function () {
   });
 });
 
+Deno.test("posix.(unstable-)join()", function () {
+  joinUrlTests.forEach(function (p) {
+    const _p = p[0];
+    const actual = posixUnstableJoin.apply(null, _p);
+    assertEquals(actual, p[1]);
+  });
+});
+
 Deno.test("windows.join()", function () {
   joinTests.forEach(function (p) {
     const _p = p[0];
@@ -143,6 +158,22 @@ Deno.test("windows.join()", function () {
   });
 });
 
+Deno.test("windows.(unstable-)join()", function () {
+  joinUrlTests.forEach(function (p) {
+    const _p = p[0];
+    const actual = windowsUnstableJoin.apply(null, _p).replace(
+      backslashRE,
+      "/",
+    );
+    assertEquals(actual, p[1]);
+  });
+  windowsJoinUrlTests.forEach(function (p) {
+    const _p = p[0];
+    const actual = windowsUnstableJoin.apply(null, _p);
+    assertEquals(actual, p[1]);
+  });
+});
+
 Deno.test(`join() returns "." if input is empty`, function () {
   assertEquals(join(""), ".");
   assertEquals(join("", ""), ".");

path/posix/join.ts

@@ -3,7 +3,6 @@
 
 import { assertPath } from "../_common/assert_path.ts";
 import { normalize } from "./normalize.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Join all given a sequence of `paths`,then normalizes the resulting path.
@@ -20,30 +19,8 @@ import { fromFileUrl } from "./from_file_url.ts";
  * @param paths The paths to join.
  * @returns The joined path.
  */
-export function join(...paths: string[]): string;
-/**
- * Join all given a sequence of `paths`, then normalizes the resulting path.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { join } from "@std/path/posix/join";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(join("/foo", "bar", "baz/asdf", "quux", ".."), "/foo/bar/baz/asdf");
- * assertEquals(join(new URL("file:///foo"), "bar", "baz/asdf", "quux", ".."), "/foo/bar/baz/asdf");
- * ```
- *
- * @param path The path to join. This can be string or file URL.
- * @param paths The paths to join.
- * @returns The joined path.
- */
-export function join(path?: URL | string, ...paths: string[]): string;
-export function join(path?: URL | string, ...paths: string[]): string {
-  if (path === undefined) return ".";
-  path = path instanceof URL ? fromFileUrl(path) : path;
-  paths = path ? [path, ...paths] : paths;
+export function join(...paths: string[]): string {
+  if (paths.length === 0) return ".";
   paths.forEach((path) => assertPath(path));
   const joined = paths.filter((path) => path.length > 0).join("/");
   return joined === "" ? "." : normalize(joined);

path/posix/unstable_join.ts

@@ -0,0 +1,30 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { join as stableJoin } from "./join.ts";
+import { fromFileUrl } from "./from_file_url.ts";
+
+/**
+ * Join all given a sequence of `paths`, then normalizes the resulting path.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { join } from "@std/path/posix/unstable-join";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(join("/foo", "bar", "baz/asdf", "quux", ".."), "/foo/bar/baz/asdf");
+ * assertEquals(join(new URL("file:///foo"), "bar", "baz/asdf", "quux", ".."), "/foo/bar/baz/asdf");
+ * ```
+ *
+ * @param path The path to join. This can be string or file URL.
+ * @param paths The paths to join.
+ * @returns The joined path.
+ */
+export function join(path?: URL | string, ...paths: string[]): string {
+  if (path === undefined) return ".";
+  path = path instanceof URL ? fromFileUrl(path) : path;
+  paths = path ? [path, ...paths] : paths;
+  return stableJoin(...paths);
+}

path/unstable_join.ts

@@ -0,0 +1,35 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { isWindows } from "./_os.ts";
+import { join as posixUnstableJoin } from "./posix/unstable_join.ts";
+import { join as windowsUnstableJoin } from "./windows/unstable_join.ts";
+
+/**
+ * Join all given a sequence of `paths`, then normalizes the resulting path.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { join } from "@std/path/unstable-join";
+ * import { assertEquals } from "@std/assert";
+ *
+ * if (Deno.build.os === "windows") {
+ *   const path = join(new URL("file:///C:/foo"), "bar", "baz/asdf", "quux", "..");
+ *   assertEquals(path, "C:\\foo\\bar\\baz\\asdf");
+ * } else {
+ *   const path = join(new URL("file:///foo"), "bar", "baz/asdf", "quux", "..");
+ *   assertEquals(path, "/foo/bar/baz/asdf");
+ * }
+ * ```
+ *
+ * @param path The path to join. This can be string or file URL.
+ * @param paths The paths to join.
+ * @returns The joined path.
+ */
+export function join(path?: URL | string, ...paths: string[]): string {
+  return isWindows
+    ? windowsUnstableJoin(path, ...paths)
+    : posixUnstableJoin(path, ...paths);
+}

path/windows/join.ts

@@ -4,7 +4,6 @@
 import { assertPath } from "../_common/assert_path.ts";
 import { isPathSeparator } from "./_util.ts";
 import { normalize } from "./normalize.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Join all given a sequence of `paths`,then normalizes the resulting path.
@@ -21,29 +20,7 @@ import { fromFileUrl } from "./from_file_url.ts";
  * @param paths The paths to join.
  * @returns The joined path.
  */
-export function join(...paths: string[]): string;
-/**
- * Join all given a sequence of `paths`, then normalizes the resulting path.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { join } from "@std/path/windows/join";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(join("C:\\foo", "bar", "baz\\.."), "C:\\foo\\bar");
- * assertEquals(join(new URL("file:///C:/foo"), "bar", "baz\\.."), "C:\\foo\\bar");
- * ```
- *
- * @param path The path to join. This can be string or file URL.
- * @param paths The paths to join.
- * @returns The joined path.
- */
-export function join(path?: URL | string, ...paths: string[]): string;
-export function join(path?: URL | string, ...paths: string[]): string {
-  path = path instanceof URL ? fromFileUrl(path) : path;
-  paths = path ? [path, ...paths] : paths;
+export function join(...paths: string[]): string {
   paths.forEach((path) => assertPath(path));
   paths = paths.filter((path) => path.length > 0);
   if (paths.length === 0) return ".";

path/windows/unstable_join.ts

@@ -0,0 +1,29 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { join as stableJoin } from "./join.ts";
+import { fromFileUrl } from "./from_file_url.ts";
+
+/**
+ * Join all given a sequence of `paths`, then normalizes the resulting path.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { join } from "@std/path/windows/unstable-join";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(join("C:\\foo", "bar", "baz\\.."), "C:\\foo\\bar");
+ * assertEquals(join(new URL("file:///C:/foo"), "bar", "baz\\.."), "C:\\foo\\bar");
+ * ```
+ *
+ * @param path The path to join. This can be string or file URL.
+ * @param paths The paths to join.
+ * @returns The joined path.
+ */
+export function join(path?: URL | string, ...paths: string[]): string {
+  path = path instanceof URL ? fromFileUrl(path) : path;
+  paths = path ? [path, ...paths] : paths;
+  return stableJoin(...paths);
+}