BREAKING(path/unstable): move unstable overload of dirname to unstable-dirname (#5954)

_tools/check_docs.ts

@@ -68,6 +68,7 @@ const ENTRY_POINTS = [
   "../net/mod.ts",
   "../net/unstable_get_network_address.ts",
   "../path/mod.ts",
+  "../path/unstable_dirname.ts",
   "../path/posix/mod.ts",
   "../path/windows/mod.ts",
   "../random/mod.ts",

path/deno.json

@@ -38,11 +38,13 @@
     "./posix/resolve": "./posix/resolve.ts",
     "./posix/to-file-url": "./posix/to_file_url.ts",
     "./posix/to-namespaced-path": "./posix/to_namespaced_path.ts",
+    "./posix/unstable-dirname": "./posix/unstable_dirname.ts",
     "./relative": "./relative.ts",
     "./resolve": "./resolve.ts",
     "./to-file-url": "./to_file_url.ts",
     "./to-namespaced-path": "./to_namespaced_path.ts",
     "./types": "./types.ts",
+    "./unstable-dirname": "./unstable_dirname.ts",
     "./windows": "./windows/mod.ts",
     "./windows/basename": "./windows/basename.ts",
     "./windows/common": "./windows/common.ts",
@@ -62,6 +64,7 @@
     "./windows/relative": "./windows/relative.ts",
     "./windows/resolve": "./windows/resolve.ts",
     "./windows/to-file-url": "./windows/to_file_url.ts",
-    "./windows/to-namespaced-path": "./windows/to_namespaced_path.ts"
+    "./windows/to-namespaced-path": "./windows/to_namespaced_path.ts",
+    "./windows/unstable-dirname": "./windows/unstable_dirname.ts"
   }
 }

path/dirname.ts

@@ -20,33 +20,12 @@ import { dirname as windowsDirname } from "./windows/dirname.ts";
  * }
  * ```
  *
- * @param path Path to extract the directory from.
+ * Note: If you are working with file URLs,
- * @returns The directory path.
+ * use the new version of `dirname` from `@std/path/unstable-dirname`.
- */
-export function dirname(path: string): string;
-/**
- * Return the directory path of a file URL.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { dirname } from "@std/path/dirname";
- * import { assertEquals } from "@std/assert";
- *
- * if (Deno.build.os === "windows") {
- *   assertEquals(dirname("C:\\home\\user\\Documents\\image.png"), "C:\\home\\user\\Documents");
- *   assertEquals(dirname(new URL("file:///C:/home/user/Documents/image.png")), "C:\\home\\user\\Documents");
- * } else {
- *   assertEquals(dirname("/home/user/Documents/image.png"), "/home/user/Documents");
- *   assertEquals(dirname(new URL("file:///home/user/Documents/image.png")), "/home/user/Documents");
- * }
- * ```
  *
  * @param path Path to extract the directory from.
  * @returns The directory path.
  */
-export function dirname(path: string | URL): string;
+export function dirname(path: string): string {
-export function dirname(path: string | URL): string {
   return isWindows ? windowsDirname(path) : posixDirname(path);
 }

path/dirname_test.ts

@@ -5,6 +5,8 @@ import { assertEquals, assertThrows } from "@std/assert";
 import { dirname } from "./dirname.ts";
 import * as posix from "./posix/mod.ts";
 import * as windows from "./windows/mod.ts";
+import { dirname as windowsUnstableDirname } from "./windows/unstable_dirname.ts";
+import { dirname as posixUnstableDirname } from "./posix/unstable_dirname.ts";
 
 // Test suite from "GNU core utilities"
 // https://github.com/coreutils/coreutils/blob/master/tests/misc/dirname.pl
@@ -89,13 +91,13 @@ Deno.test("posix.dirname()", function () {
 
 Deno.test("posix.dirname() works with file URLs", () => {
   assertEquals(
-    posix.dirname(new URL("file:///home/user/Documents/image.png")),
+    posixUnstableDirname(new URL("file:///home/user/Documents/image.png")),
     "/home/user/Documents",
   );
 
   // throws with non-file URLs
   assertThrows(
-    () => posix.dirname(new URL("https://deno.land/")),
+    () => posixUnstableDirname(new URL("https://deno.land/")),
     TypeError,
     'URL must be a file URL: received "https:"',
   );
@@ -118,13 +120,13 @@ Deno.test("windows.dirname()", function () {
 
 Deno.test("windows.dirname() works with file URLs", () => {
   assertEquals(
-    windows.dirname(new URL("file:///C:/home/user/Documents/image.png")),
+    windowsUnstableDirname(new URL("file:///C:/home/user/Documents/image.png")),
     "C:\\home\\user\\Documents",
   );
 
   // throws with non-file URLs
   assertThrows(
-    () => windows.dirname(new URL("https://deno.land/")),
+    () => windowsUnstableDirname(new URL("https://deno.land/")),
     TypeError,
     'URL must be a file URL: received "https:"',
   );

path/posix/dirname.ts

@@ -4,7 +4,6 @@
 import { assertArg } from "../_common/dirname.ts";
 import { stripTrailingSeparators } from "../_common/strip_trailing_separators.ts";
 import { isPosixPathSeparator } from "./_util.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Return the directory path of a `path`.
@@ -18,33 +17,13 @@ import { fromFileUrl } from "./from_file_url.ts";
  * assertEquals(dirname("/home/user/Documents/image.png"), "/home/user/Documents");
  * ```
  *
+ * Note: If you are working with file URLs,
+ * use the new version of `dirname` from `@std/path/posix/unstable-dirname`.
+ *
  * @param path The path to get the directory from.
  * @returns The directory path.
  */
-export function dirname(path: string): string;
+export function dirname(path: string): string {
-/**
- * Return the directory path of a file URL.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { dirname } from "@std/path/posix/dirname";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(dirname("/home/user/Documents/"), "/home/user");
- * assertEquals(dirname("/home/user/Documents/image.png"), "/home/user/Documents");
- * assertEquals(dirname(new URL("file:///home/user/Documents/image.png")), "/home/user/Documents");
- * ```
- *
- * @param path The file url to get the directory from.
- * @returns The directory path.
- */
-export function dirname(path: string | URL): string;
-export function dirname(path: string | URL): string {
-  if (path instanceof URL) {
-    path = fromFileUrl(path);
-  }
   assertArg(path);
 
   let end = -1;

path/posix/unstable_dirname.ts

@@ -0,0 +1,30 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { dirname as stableDirname } from "./dirname.ts";
+import { fromFileUrl } from "./from_file_url.ts";
+
+/**
+ * Return the directory path of a file URL.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { dirname } from "@std/path/posix/unstable-dirname";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(dirname("/home/user/Documents/"), "/home/user");
+ * assertEquals(dirname("/home/user/Documents/image.png"), "/home/user/Documents");
+ * assertEquals(dirname(new URL("file:///home/user/Documents/image.png")), "/home/user/Documents");
+ * ```
+ *
+ * @param path The file url to get the directory from.
+ * @returns The directory path.
+ */
+export function dirname(path: string | URL): string {
+  if (path instanceof URL) {
+    path = fromFileUrl(path);
+  }
+  return stableDirname(path);
+}

path/unstable_dirname.ts

@@ -0,0 +1,32 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { isWindows } from "./_os.ts";
+import { dirname as posixUnstableDirname } from "./posix/unstable_dirname.ts";
+import { dirname as windowsUnstableDirname } from "./windows/unstable_dirname.ts";
+
+/**
+ * Return the directory path of a file URL.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { dirname } from "@std/path/unstable-dirname";
+ * import { assertEquals } from "@std/assert";
+ *
+ * if (Deno.build.os === "windows") {
+ *   assertEquals(dirname("C:\\home\\user\\Documents\\image.png"), "C:\\home\\user\\Documents");
+ *   assertEquals(dirname(new URL("file:///C:/home/user/Documents/image.png")), "C:\\home\\user\\Documents");
+ * } else {
+ *   assertEquals(dirname("/home/user/Documents/image.png"), "/home/user/Documents");
+ *   assertEquals(dirname(new URL("file:///home/user/Documents/image.png")), "/home/user/Documents");
+ * }
+ * ```
+ *
+ * @param path Path to extract the directory from.
+ * @returns The directory path.
+ */
+export function dirname(path: string | URL): string {
+  return isWindows ? windowsUnstableDirname(path) : posixUnstableDirname(path);
+}

path/windows/dirname.ts

@@ -9,7 +9,6 @@ import {
   isPosixPathSeparator,
   isWindowsDeviceRoot,
 } from "./_util.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Return the directory path of a `path`.
@@ -23,32 +22,13 @@ import { fromFileUrl } from "./from_file_url.ts";
  * assertEquals(dir, "C:\\foo\\bar");
  * ```
  *
- * @param path The path to get the directory from.
+ * Note: If you are working with file URLs,
- * @returns The directory path.
+ * use the new version of `dirname` from `@std/path/windows/unstable-dirname`.
- */
-export function dirname(path: string): string;
-/**
- * Return the directory path of a file URL.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { dirname } from "@std/path/windows/dirname";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(dirname("C:\\foo\\bar\\baz.ext"), "C:\\foo\\bar");
- * assertEquals(dirname(new URL("file:///C:/foo/bar/baz.ext")), "C:\\foo\\bar");
- * ```
  *
  * @param path The path to get the directory from.
  * @returns The directory path.
  */
-export function dirname(path: string | URL): string;
+export function dirname(path: string): string {
-export function dirname(path: string | URL): string {
-  if (path instanceof URL) {
-    path = fromFileUrl(path);
-  }
   assertArg(path);
 
   const len = path.length;

path/windows/unstable_dirname.ts

@@ -0,0 +1,29 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { dirname as stableDirname } from "./dirname.ts";
+import { fromFileUrl } from "./from_file_url.ts";
+
+/**
+ * Return the directory path of a file URL.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { dirname } from "@std/path/windows/unstable-dirname";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(dirname("C:\\foo\\bar\\baz.ext"), "C:\\foo\\bar");
+ * assertEquals(dirname(new URL("file:///C:/foo/bar/baz.ext")), "C:\\foo\\bar");
+ * ```
+ *
+ * @param path The path to get the directory from.
+ * @returns The directory path.
+ */
+export function dirname(path: string | URL): string {
+  if (path instanceof URL) {
+    path = fromFileUrl(path);
+  }
+  return stableDirname(path);
+}