BREAKING(path/unstable): move unstable overload of normalize to unstable-normalize (#5965)

_tools/check_docs.ts

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

path/deno.json

@@ -42,6 +42,7 @@
     "./posix/unstable-dirname": "./posix/unstable_dirname.ts",
     "./posix/unstable-extname": "./posix/unstable_extname.ts",
     "./posix/unstable-join": "./posix/unstable_join.ts",
+    "./posix/unstable-normalize": "./posix/unstable_normalize.ts",
     "./relative": "./relative.ts",
     "./resolve": "./resolve.ts",
     "./to-file-url": "./to_file_url.ts",
@@ -51,6 +52,7 @@
     "./unstable-dirname": "./unstable_dirname.ts",
     "./unstable-extname": "./unstable_extname.ts",
     "./unstable-join": "./unstable_join.ts",
+    "./unstable-normalize": "./unstable_normalize.ts",
     "./windows": "./windows/mod.ts",
     "./windows/basename": "./windows/basename.ts",
     "./windows/common": "./windows/common.ts",
@@ -74,6 +76,7 @@
     "./windows/unstable-basename": "./windows/unstable_basename.ts",
     "./windows/unstable-dirname": "./windows/unstable_dirname.ts",
     "./windows/unstable-extname": "./windows/unstable_extname.ts",
-    "./windows/unstable-join": "./windows/unstable_join.ts"
+    "./windows/unstable-join": "./windows/unstable_join.ts",
+    "./windows/unstable-normalize": "./windows/unstable_normalize.ts"
   }
 }

path/normalize.ts

@@ -23,37 +23,12 @@ import { normalize as windowsNormalize } from "./windows/normalize.ts";
  * }
  * ```
  *
+ * Note: If you are working with file URLs,
+ * use the new version of `normalize` from `@std/path/unstable-normalize`.
+ *
  * @param path Path to be normalized
  * @returns The normalized path.
  */
-export function normalize(path: string): string;
+export function normalize(path: string): string {
-/**
- * Normalize the path, resolving `'..'` and `'.'` segments.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * Note: Resolving these segments does not necessarily mean that all will be
- * eliminated. A `'..'` at the top-level will be preserved, and an empty path is
- * canonically `'.'`.
- *
- * @example Usage
- * ```ts
- * import { normalize } from "@std/path/normalize";
- * import { assertEquals } from "@std/assert";
- *
- * if (Deno.build.os === "windows") {
- *   assertEquals(normalize("C:\\foo\\bar\\..\\baz\\quux"), "C:\\foo\\baz\\quux");
- *   assertEquals(normalize(new URL("file:///C:/foo/bar/../baz/quux")), "C:\\foo\\baz\\quux");
- * } else {
- *   assertEquals(normalize("/foo/bar/../baz/quux"), "/foo/baz/quux");
- *   assertEquals(normalize(new URL("file:///foo/bar/../baz/quux")), "/foo/baz/quux");
- * }
- * ```
- *
- * @param path Path to be normalized. Path can be a string or a file URL object.
- * @returns The normalized path.
- */
-export function normalize(path: string | URL): string;
-export function normalize(path: string | URL): string {
   return isWindows ? windowsNormalize(path) : posixNormalize(path);
 }

path/normalize_test.ts

@@ -2,6 +2,8 @@
 import { assertEquals } from "@std/assert";
 import * as windows from "./windows/mod.ts";
 import * as posix from "./posix/mod.ts";
+import { normalize as windowsUnstableNormalize } from "./windows/unstable_normalize.ts";
+import { normalize as posixUnstableNormalize } from "./posix/unstable_normalize.ts";
 
 Deno.test(`normalize() returns "." if input is empty`, function () {
   assertEquals(posix.normalize(""), ".");
@@ -14,7 +16,7 @@ Deno.test("posix.normalize() normalizes posix specific paths", () => {
     "/foo/bar/baz/asdf",
   );
   assertEquals(
-    posix.normalize(new URL("file:///foo/bar//baz/asdf/quux/..")),
+    posixUnstableNormalize(new URL("file:///foo/bar//baz/asdf/quux/..")),
     "/foo/bar/baz/asdf/",
   );
 });
@@ -25,7 +27,7 @@ Deno.test("windows.normalize() normalizes windows specific paths", () => {
     "\\\\server\\share\\dir\\file.ext",
   );
   assertEquals(
-    windows.normalize(new URL("file:///C:/foo/bar/../baz/quux")),
+    windowsUnstableNormalize(new URL("file:///C:/foo/bar/../baz/quux")),
     "C:\\foo\\baz\\quux",
   );
 });

path/posix/normalize.ts

@@ -4,7 +4,6 @@
 import { assertArg } from "../_common/normalize.ts";
 import { normalizeString } from "../_common/normalize_string.ts";
 import { isPosixPathSeparator } from "./_util.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Normalize the `path`, resolving `'..'` and `'.'` segments.
@@ -20,32 +19,13 @@ import { fromFileUrl } from "./from_file_url.ts";
  * assertEquals(path, "/foo/bar/baz/asdf");
  * ```
  *
+ * Note: If you are working with file URLs,
+ * use the new version of `normalize` from `@std/path/posix/unstable-normalize`.
+ *
  * @param path The path to normalize.
  * @returns The normalized path.
  */
-export function normalize(path: string): string;
+export function normalize(path: string): string {
-/**
- * Normalize the `path`, resolving `'..'` and `'.'` segments.
- * Note that resolving these segments does not necessarily mean that all will be eliminated.
- * A `'..'` at the top-level will be preserved, and an empty path is canonically `'.'`.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { normalize } from "@std/path/posix/normalize";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(normalize("/foo/bar//baz/asdf/quux/.."), "/foo/bar/baz/asdf");
- * assertEquals(normalize(new URL("file:///foo/bar//baz/asdf/quux/..")), "/foo/bar/baz/asdf/");
- * ```
- *
- * @param path The path to normalize. Path can be a string or a file URL object.
- * @returns The normalized path.
- */
-export function normalize(path: string | URL): string;
-export function normalize(path: string | URL): string {
-  path = path instanceof URL ? fromFileUrl(path) : path;
   assertArg(path);
 
   const isAbsolute = isPosixPathSeparator(path.charCodeAt(0));

path/posix/unstable_normalize.ts

@@ -0,0 +1,29 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { normalize as stableNormalize } from "./normalize.ts";
+import { fromFileUrl } from "./from_file_url.ts";
+
+/**
+ * Normalize the `path`, resolving `'..'` and `'.'` segments.
+ * Note that resolving these segments does not necessarily mean that all will be eliminated.
+ * A `'..'` at the top-level will be preserved, and an empty path is canonically `'.'`.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { normalize } from "@std/path/posix/unstable-normalize";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(normalize("/foo/bar//baz/asdf/quux/.."), "/foo/bar/baz/asdf");
+ * assertEquals(normalize(new URL("file:///foo/bar//baz/asdf/quux/..")), "/foo/bar/baz/asdf/");
+ * ```
+ *
+ * @param path The path to normalize. Path can be a string or a file URL object.
+ * @returns The normalized path.
+ */
+export function normalize(path: string | URL): string {
+  path = path instanceof URL ? fromFileUrl(path) : path;
+  return stableNormalize(path);
+}

path/unstable_normalize.ts

@@ -0,0 +1,38 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { isWindows } from "./_os.ts";
+import { normalize as posixUnstableNormalize } from "./posix/unstable_normalize.ts";
+import { normalize as windowsUnstableNormalize } from "./windows/unstable_normalize.ts";
+/**
+ * Normalize the path, resolving `'..'` and `'.'` segments.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * Note: Resolving these segments does not necessarily mean that all will be
+ * eliminated. A `'..'` at the top-level will be preserved, and an empty path is
+ * canonically `'.'`.
+ *
+ * @example Usage
+ * ```ts
+ * import { normalize } from "@std/path/unstable-normalize";
+ * import { assertEquals } from "@std/assert";
+ *
+ * if (Deno.build.os === "windows") {
+ *   assertEquals(normalize("C:\\foo\\bar\\..\\baz\\quux"), "C:\\foo\\baz\\quux");
+ *   assertEquals(normalize(new URL("file:///C:/foo/bar/../baz/quux")), "C:\\foo\\baz\\quux");
+ * } else {
+ *   assertEquals(normalize("/foo/bar/../baz/quux"), "/foo/baz/quux");
+ *   assertEquals(normalize(new URL("file:///foo/bar/../baz/quux")), "/foo/baz/quux");
+ * }
+ * ```
+ *
+ * @param path Path to be normalized. Path can be a string or a file URL object.
+ * @returns The normalized path.
+ */
+
+export function normalize(path: string | URL): string {
+  return isWindows
+    ? windowsUnstableNormalize(path)
+    : posixUnstableNormalize(path);
+}

path/windows/normalize.ts

@@ -5,7 +5,6 @@ import { assertArg } from "../_common/normalize.ts";
 import { CHAR_COLON } from "../_common/constants.ts";
 import { normalizeString } from "../_common/normalize_string.ts";
 import { isPathSeparator, isWindowsDeviceRoot } from "./_util.ts";
-import { fromFileUrl } from "./from_file_url.ts";
 
 /**
  * Normalize the `path`, resolving `'..'` and `'.'` segments.
@@ -21,32 +20,13 @@ import { fromFileUrl } from "./from_file_url.ts";
  * assertEquals(normalized, "C:\\bar");
  * ```
  *
+ * Note: If you are working with file URLs,
+ * use the new version of `normalize` from `@std/path/windows/unstable-normalize`.
+ *
  * @param path The path to normalize
  * @returns The normalized path
  */
-export function normalize(path: string): string;
+export function normalize(path: string): string {
-/**
- * Normalize the `path`, resolving `'..'` and `'.'` segments.
- * Note that resolving these segments does not necessarily mean that all will be eliminated.
- * A `'..'` at the top-level will be preserved, and an empty path is canonically `'.'`.
- *
- * @experimental **UNSTABLE**: New API, yet to be vetted.
- *
- * @example Usage
- * ```ts
- * import { normalize } from "@std/path/windows/normalize";
- * import { assertEquals } from "@std/assert";
- *
- * assertEquals(normalize("C:\\foo\\..\\bar"), "C:\\bar");
- * assertEquals(normalize(new URL("file:///C:/foo/../bar")), "C:\\bar");
- * ```
- *
- * @param path The path to normalize. Path can be a string or a file URL object.
- * @returns The normalized path
- */
-export function normalize(path: string | URL): string;
-export function normalize(path: string | URL): string {
-  path = path instanceof URL ? fromFileUrl(path) : path;
   assertArg(path);
 
   const len = path.length;

path/windows/unstable_normalize.ts

@@ -0,0 +1,29 @@
+// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
+// This module is browser compatible.
+
+import { normalize as stableNormalize } from "./normalize.ts";
+import { fromFileUrl } from "./from_file_url.ts";
+
+/**
+ * Normalize the `path`, resolving `'..'` and `'.'` segments.
+ * Note that resolving these segments does not necessarily mean that all will be eliminated.
+ * A `'..'` at the top-level will be preserved, and an empty path is canonically `'.'`.
+ *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
+ * @example Usage
+ * ```ts
+ * import { normalize } from "@std/path/windows/unstable-normalize";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(normalize("C:\\foo\\..\\bar"), "C:\\bar");
+ * assertEquals(normalize(new URL("file:///C:/foo/../bar")), "C:\\bar");
+ * ```
+ *
+ * @param path The path to normalize. Path can be a string or a file URL object.
+ * @returns The normalized path
+ */
+export function normalize(path: string | URL): string {
+  path = path instanceof URL ? fromFileUrl(path) : path;
+  return stableNormalize(path);
+}