diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 589a8adeb..bc816adad 100644 --- a/_tools/check_docs.ts +++ b/_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", diff --git a/path/deno.json b/path/deno.json index 7e53b4b77..ef7238293 100644 --- a/path/deno.json +++ b/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" } } diff --git a/path/normalize.ts b/path/normalize.ts index c069a16dc..d4fb0d827 100644 --- a/path/normalize.ts +++ b/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; -/** - * 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 { +export function normalize(path: string): string { return isWindows ? windowsNormalize(path) : posixNormalize(path); } diff --git a/path/normalize_test.ts b/path/normalize_test.ts index 0107b2877..2b43b0719 100644 --- a/path/normalize_test.ts +++ b/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", ); }); diff --git a/path/posix/normalize.ts b/path/posix/normalize.ts index c27d5e663..2258feb48 100644 --- a/path/posix/normalize.ts +++ b/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; -/** - * 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; +export function normalize(path: string): string { assertArg(path); const isAbsolute = isPosixPathSeparator(path.charCodeAt(0)); diff --git a/path/posix/unstable_normalize.ts b/path/posix/unstable_normalize.ts new file mode 100644 index 000000000..c3c84dd7b --- /dev/null +++ b/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); +} diff --git a/path/unstable_normalize.ts b/path/unstable_normalize.ts new file mode 100644 index 000000000..6c5ad227e --- /dev/null +++ b/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); +} diff --git a/path/windows/normalize.ts b/path/windows/normalize.ts index 29bdd0c83..0c9f244af 100644 --- a/path/windows/normalize.ts +++ b/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; -/** - * 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; +export function normalize(path: string): string { assertArg(path); const len = path.length; diff --git a/path/windows/unstable_normalize.ts b/path/windows/unstable_normalize.ts new file mode 100644 index 000000000..0ffd4e748 --- /dev/null +++ b/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); +}