BREAKING(path/unstable): move unstable overload of extname to unstable-extname

_tools/check_docs.ts

@@ -71,7 +71,9 @@ const ENTRY_POINTS = [
   "../net/mod.ts",
   "../net/unstable_get_network_address.ts",
   "../path/mod.ts",
+  "../path/unstable_basename.ts",
   "../path/unstable_dirname.ts",
+  "../path/unstable_extname.ts",
   "../path/posix/mod.ts",
   "../path/windows/mod.ts",
   "../random/mod.ts",

path/deno.json

@@ -40,13 +40,15 @@
     "./posix/to-namespaced-path": "./posix/to_namespaced_path.ts",
     "./posix/unstable-basename": "./posix/unstable_basename.ts",
     "./posix/unstable-dirname": "./posix/unstable_dirname.ts",
+    "./posix/unstable-extname": "./posix/unstable_extname.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-basename": "./unstable_basename.ts",
     "./unstable-dirname": "./unstable_dirname.ts",
+    "./unstable-extname": "./unstable_extname.ts",
     "./windows": "./windows/mod.ts",
     "./windows/basename": "./windows/basename.ts",
     "./windows/common": "./windows/common.ts",
@@ -68,6 +70,7 @@
     "./windows/to-file-url": "./windows/to_file_url.ts",
     "./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-dirname": "./windows/unstable_dirname.ts",
+    "./windows/unstable-extname": "./windows/unstable_extname.ts"
   }
 }

path/extname.ts

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

path/extname_test.ts

@@ -4,6 +4,8 @@
 import { assertEquals } from "@std/assert";
 import * as posix from "./posix/mod.ts";
 import * as windows from "./windows/mod.ts";
+import { extname as posixUnstableExtname } from "./posix/unstable_extname.ts";
+import { extname as windowsUnstableExtname } from "./windows/unstable_extname.ts";
 
 const slashRE = /\//g;
 
@@ -70,11 +72,11 @@ Deno.test("posix.extname()", function () {
   assertEquals(posix.extname("file.\\\\"), ".\\\\");
 
   assertEquals(
-    posix.extname(new URL("file:///home/user/Documents/image.png")),
+    posixUnstableExtname(new URL("file:///home/user/Documents/image.png")),
     ".png",
   );
   assertEquals(
-    posix.extname(new URL("file:///home/user/Documents")),
+    posixUnstableExtname(new URL("file:///home/user/Documents")),
     "",
   );
 });
@@ -98,11 +100,11 @@ Deno.test("windows.extname()", function () {
   assertEquals(windows.extname("file.\\\\"), ".");
 
   assertEquals(
-    windows.extname(new URL("file:///C:/home/user/Documents/image.png")),
+    windowsUnstableExtname(new URL("file:///C:/home/user/Documents/image.png")),
     ".png",
   );
   assertEquals(
-    windows.extname(new URL("file:///C:/home/user/Documents")),
+    windowsUnstableExtname(new URL("file:///C:/home/user/Documents")),
     "",
   );
 });

path/posix/extname.ts

@@ -4,7 +4,6 @@
 import { CHAR_DOT } from "../_common/constants.ts";
 import { assertPath } from "../_common/assert_path.ts";
 import { isPosixPathSeparator } from "./_util.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Return the extension of the `path` with leading period.
@@ -19,40 +18,13 @@ import { fromFileUrl } from "./from_file_url.ts";
  * assertEquals(extname("/home/user/Documents/image.png"), ".png");
  * ```
  *
- * @param path The path to get the extension from.
- * @returns The extension (ex. for `file.ts` returns `.ts`).
- */
-export function extname(path: string): string;
-/**
- * Return the extension of the `path` with leading period.
- *
- * Note: Hashes and query parameters are ignore when constructing a URL.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- *
- * ```ts
- * import { extname } from "@std/path/posix/extname";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(extname("/home/user/Documents/file.ts"), ".ts");
- * assertEquals(extname("/home/user/Documents/"), "");
- * assertEquals(extname("/home/user/Documents/image.png"), ".png");
- * assertEquals(extname(new URL("file:///home/user/Documents/file.ts")), ".ts");
- * assertEquals(extname(new URL("file:///home/user/Documents/file.ts?a=b")), ".ts");
- * assertEquals(extname(new URL("file:///home/user/Documents/file.ts#header")), ".ts");
- * ```
+ * Note: If you are working with file URLs,
+ * use the new version of `extname` from `@std/path/posix/unstable-extname`.
  *
  * @param path The path to get the extension from.
  * @returns The extension (ex. for `file.ts` returns `.ts`).
  */
-export function extname(path: string | URL): string;
-export function extname(path: string | URL): string {
-  if (path instanceof URL) {
-    path = fromFileUrl(path);
-  }
-
+export function extname(path: string): string {
   assertPath(path);
 
   let startDot = -1;

path/posix/unstable_extname.ts

@@ -0,0 +1,36 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { extname as stableExtname } from "./extname.ts";
+import { fromFileUrl } from "./from_file_url.ts";
+
+/**
+ * Return the extension of the `path` with leading period.
+ *
+ * Note: Hashes and query parameters are ignore when constructing a URL.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ *
+ * ```ts
+ * import { extname } from "@std/path/posix/unstable-extname";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(extname("/home/user/Documents/file.ts"), ".ts");
+ * assertEquals(extname("/home/user/Documents/"), "");
+ * assertEquals(extname("/home/user/Documents/image.png"), ".png");
+ * assertEquals(extname(new URL("file:///home/user/Documents/file.ts")), ".ts");
+ * assertEquals(extname(new URL("file:///home/user/Documents/file.ts?a=b")), ".ts");
+ * assertEquals(extname(new URL("file:///home/user/Documents/file.ts#header")), ".ts");
+ * ```
+ *
+ * @param path The path to get the extension from.
+ * @returns The extension (ex. for `file.ts` returns `.ts`).
+ */
+export function extname(path: string | URL): string {
+  if (path instanceof URL) {
+    path = fromFileUrl(path);
+  }
+  return stableExtname(path);
+}

path/unstable_extname.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 { extname as posixUnstableExtname } from "./posix/unstable_extname.ts";
+import { extname as windowsUnstableExtname } from "./windows/unstable_extname.ts";
+
+/**
+ * Return the extension of the path with leading period (".").
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { extname } from "@std/path/unstable-extname";
+ * import { assertEquals } from "@std/assert";
+ *
+ * if (Deno.build.os === "windows") {
+ *   assertEquals(extname("C:\\home\\user\\Documents\\image.png"), ".png");
+ *   assertEquals(extname(new URL("file:///C:/home/user/Documents/image.png")), ".png");
+ * } else {
+ *   assertEquals(extname("/home/user/Documents/image.png"), ".png");
+ *   assertEquals(extname(new URL("file:///home/user/Documents/image.png")), ".png");
+ * }
+ * ```
+ *
+ * @param path Path with extension.
+ * @returns The file extension. E.g. returns `.ts` for `file.ts`.
+ */
+export function extname(path: string | URL): string {
+  return isWindows ? windowsUnstableExtname(path) : posixUnstableExtname(path);
+}

path/windows/extname.ts

@@ -4,7 +4,6 @@
 import { CHAR_COLON, CHAR_DOT } from "../_common/constants.ts";
 import { assertPath } from "../_common/assert_path.ts";
 import { isPathSeparator, isWindowsDeviceRoot } from "./_util.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Return the extension of the `path` with leading period.
@@ -18,32 +17,13 @@ import { fromFileUrl } from "./from_file_url.ts";
  * assertEquals(ext, ".ts");
  * ```
  *
- * @param path The path to get the extension from.
- * @returns The extension of the `path`.
- */
-export function extname(path: string): string;
-/**
- * Return the extension of the `path` with leading period.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { extname } from "@std/path/windows/extname";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(extname("file.ts"), ".ts");
- * assertEquals(extname(new URL("file:///C:/foo/bar/baz.ext")), ".ext");
- * ```
+ * Note: If you are working with file URLs,
+ * use the new version of `extname` from `@std/path/windows/unstable-extname`.
  *
  * @param path The path to get the extension from.
  * @returns The extension of the `path`.
  */
-export function extname(path: string | URL): string;
-export function extname(path: string | URL): string {
-  if (path instanceof URL) {
-    path = fromFileUrl(path);
-  }
+export function extname(path: string): string {
   assertPath(path);
 
   let start = 0;

path/windows/unstable_extname.ts

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