@tslite/parser 1.10.0 → 1.12.0

package/dist/path.d.ts

@@ -0,0 +1,312 @@
+import { Comparison } from "./_namespaces/ts.js";
+import type { GetCanonicalFileName, Path } from "./_namespaces/ts.js";
+/**
+ * Internally, we represent paths as strings with '/' as the directory separator.
+ * When we make system calls (eg: LanguageServiceHost.getDirectory()),
+ * we expect the host to correctly handle paths in our specified format.
+ */
+export declare const directorySeparator = "/";
+/**
+ * Determines whether a charCode corresponds to `/` or `\`.
+ */
+export declare function isAnyDirectorySeparator(charCode: number): boolean;
+/**
+ * Determines whether a path is an absolute disk path (e.g. starts with `/`, or a dos path
+ * like `c:`, `c:\` or `c:/`).
+ */
+export declare function isRootedDiskPath(path: string): boolean;
+/**
+ * Determines whether a path starts with an absolute path component (i.e. `/`, `c:/`, `file://`, etc.).
+ *
+ * ```ts
+ * // POSIX
+ * pathIsAbsolute("/path/to/file.ext") === true
+ * // DOS
+ * pathIsAbsolute("c:/path/to/file.ext") === true
+ * // URL
+ * pathIsAbsolute("file:///path/to/file.ext") === true
+ * // Non-absolute
+ * pathIsAbsolute("path/to/file.ext") === false
+ * pathIsAbsolute("./path/to/file.ext") === false
+ * ```
+ */
+export declare function pathIsAbsolute(path: string): boolean;
+/**
+ * Determines whether a path starts with a relative path component (i.e. `.` or `..`).
+ */
+export declare function pathIsRelative(path: string): boolean;
+export declare function fileExtensionIs(path: string, extension: string): boolean;
+/**
+ * Determines whether a path has a trailing separator (`/` or `\\`).
+ */
+export declare function hasTrailingDirectorySeparator(path: string): boolean;
+/**
+ * Returns length of the root part of a path or URL (i.e. length of "/", "x:/", "//server/share/, file:///user/files").
+ *
+ * For example:
+ * ```ts
+ * getRootLength("a") === 0                   // ""
+ * getRootLength("/") === 1                   // "/"
+ * getRootLength("c:") === 2                  // "c:"
+ * getRootLength("c:d") === 0                 // ""
+ * getRootLength("c:/") === 3                 // "c:/"
+ * getRootLength("c:\\") === 3                // "c:\\"
+ * getRootLength("//server") === 7            // "//server"
+ * getRootLength("//server/share") === 8      // "//server/"
+ * getRootLength("\\\\server") === 7          // "\\\\server"
+ * getRootLength("\\\\server\\share") === 8   // "\\\\server\\"
+ * getRootLength("file:///path") === 8        // "file:///"
+ * getRootLength("file:///c:") === 10         // "file:///c:"
+ * getRootLength("file:///c:d") === 8         // "file:///"
+ * getRootLength("file:///c:/path") === 11    // "file:///c:/"
+ * getRootLength("file://server") === 13      // "file://server"
+ * getRootLength("file://server/path") === 14 // "file://server/"
+ * getRootLength("http://server") === 13      // "http://server"
+ * getRootLength("http://server/path") === 14 // "http://server/"
+ * ```
+ */
+export declare function getRootLength(path: string): number;
+/**
+ * Returns the path except for its basename. Semantics align with NodeJS's `path.dirname`
+ * except that we support URLs as well.
+ *
+ * ```ts
+ * // POSIX
+ * getDirectoryPath("/path/to/file.ext") === "/path/to"
+ * getDirectoryPath("/path/to/") === "/path"
+ * getDirectoryPath("/") === "/"
+ * // DOS
+ * getDirectoryPath("c:/path/to/file.ext") === "c:/path/to"
+ * getDirectoryPath("c:/path/to/") === "c:/path"
+ * getDirectoryPath("c:/") === "c:/"
+ * getDirectoryPath("c:") === "c:"
+ * // URL
+ * getDirectoryPath("http://typescriptlang.org/path/to/file.ext") === "http://typescriptlang.org/path/to"
+ * getDirectoryPath("http://typescriptlang.org/path/to") === "http://typescriptlang.org/path"
+ * getDirectoryPath("http://typescriptlang.org/") === "http://typescriptlang.org/"
+ * getDirectoryPath("http://typescriptlang.org") === "http://typescriptlang.org"
+ * ```
+ */
+export declare function getDirectoryPath(path: Path): Path;
+/**
+ * Returns the path except for its basename. Semantics align with NodeJS's `path.dirname`
+ * except that we support URLs as well.
+ *
+ * ```ts
+ * // POSIX
+ * getDirectoryPath("/path/to/file.ext") === "/path/to"
+ * getDirectoryPath("/path/to/") === "/path"
+ * getDirectoryPath("/") === "/"
+ * // DOS
+ * getDirectoryPath("c:/path/to/file.ext") === "c:/path/to"
+ * getDirectoryPath("c:/path/to/") === "c:/path"
+ * getDirectoryPath("c:/") === "c:/"
+ * getDirectoryPath("c:") === "c:"
+ * // URL
+ * getDirectoryPath("http://typescriptlang.org/path/to/file.ext") === "http://typescriptlang.org/path/to"
+ * getDirectoryPath("http://typescriptlang.org/path/to") === "http://typescriptlang.org/path"
+ * getDirectoryPath("http://typescriptlang.org/") === "http://typescriptlang.org/"
+ * getDirectoryPath("http://typescriptlang.org") === "http://typescriptlang.org"
+ * getDirectoryPath("file://server/path/to/file.ext") === "file://server/path/to"
+ * getDirectoryPath("file://server/path/to") === "file://server/path"
+ * getDirectoryPath("file://server/") === "file://server/"
+ * getDirectoryPath("file://server") === "file://server"
+ * getDirectoryPath("file:///path/to/file.ext") === "file:///path/to"
+ * getDirectoryPath("file:///path/to") === "file:///path"
+ * getDirectoryPath("file:///") === "file:///"
+ * getDirectoryPath("file://") === "file://"
+ * ```
+ */
+export declare function getDirectoryPath(path: string): string;
+/**
+ * Returns the path except for its containing directory name.
+ * Semantics align with NodeJS's `path.basename` except that we support URL's as well.
+ *
+ * ```ts
+ * // POSIX
+ * getBaseFileName("/path/to/file.ext") === "file.ext"
+ * getBaseFileName("/path/to/") === "to"
+ * getBaseFileName("/") === ""
+ * // DOS
+ * getBaseFileName("c:/path/to/file.ext") === "file.ext"
+ * getBaseFileName("c:/path/to/") === "to"
+ * getBaseFileName("c:/") === ""
+ * getBaseFileName("c:") === ""
+ * // URL
+ * getBaseFileName("http://typescriptlang.org/path/to/file.ext") === "file.ext"
+ * getBaseFileName("http://typescriptlang.org/path/to/") === "to"
+ * getBaseFileName("http://typescriptlang.org/") === ""
+ * getBaseFileName("http://typescriptlang.org") === ""
+ * getBaseFileName("file://server/path/to/file.ext") === "file.ext"
+ * getBaseFileName("file://server/path/to/") === "to"
+ * getBaseFileName("file://server/") === ""
+ * getBaseFileName("file://server") === ""
+ * getBaseFileName("file:///path/to/file.ext") === "file.ext"
+ * getBaseFileName("file:///path/to/") === "to"
+ * getBaseFileName("file:///") === ""
+ * getBaseFileName("file://") === ""
+ * ```
+ */
+export declare function getBaseFileName(path: string): string;
+/**
+ * Gets the portion of a path following the last (non-terminal) separator (`/`).
+ * Semantics align with NodeJS's `path.basename` except that we support URL's as well.
+ * If the base name has any one of the provided extensions, it is removed.
+ *
+ * ```ts
+ * getBaseFileName("/path/to/file.ext", ".ext", true) === "file"
+ * getBaseFileName("/path/to/file.js", ".ext", true) === "file.js"
+ * getBaseFileName("/path/to/file.js", [".ext", ".js"], true) === "file"
+ * getBaseFileName("/path/to/file.ext", ".EXT", false) === "file.ext"
+ * ```
+ */
+export declare function getBaseFileName(path: string, extensions: string | readonly string[], ignoreCase: boolean): string;
+/**
+ * Gets the file extension for a path.
+ *
+ * ```ts
+ * getAnyExtensionFromPath("/path/to/file.ext") === ".ext"
+ * getAnyExtensionFromPath("/path/to/file.ext/") === ".ext"
+ * getAnyExtensionFromPath("/path/to/file") === ""
+ * getAnyExtensionFromPath("/path/to.ext/file") === ""
+ * ```
+ */
+export declare function getAnyExtensionFromPath(path: string): string;
+/**
+ * Gets the file extension for a path, provided it is one of the provided extensions.
+ *
+ * ```ts
+ * getAnyExtensionFromPath("/path/to/file.ext", ".ext", true) === ".ext"
+ * getAnyExtensionFromPath("/path/to/file.js", ".ext", true) === ""
+ * getAnyExtensionFromPath("/path/to/file.js", [".ext", ".js"], true) === ".js"
+ * getAnyExtensionFromPath("/path/to/file.ext", ".EXT", false) === ""
+ */
+export declare function getAnyExtensionFromPath(path: string, extensions: string | readonly string[], ignoreCase: boolean): string;
+/**
+ * Parse a path into an array containing a root component (at index 0) and zero or more path
+ * components (at indices > 0). The result is not normalized.
+ * If the path is relative, the root component is `""`.
+ * If the path is absolute, the root component includes the first path separator (`/`).
+ *
+ * ```ts
+ * // POSIX
+ * getPathComponents("/path/to/file.ext") === ["/", "path", "to", "file.ext"]
+ * getPathComponents("/path/to/") === ["/", "path", "to"]
+ * getPathComponents("/") === ["/"]
+ * // DOS
+ * getPathComponents("c:/path/to/file.ext") === ["c:/", "path", "to", "file.ext"]
+ * getPathComponents("c:/path/to/") === ["c:/", "path", "to"]
+ * getPathComponents("c:/") === ["c:/"]
+ * getPathComponents("c:") === ["c:"]
+ * // URL
+ * getPathComponents("http://typescriptlang.org/path/to/file.ext") === ["http://typescriptlang.org/", "path", "to", "file.ext"]
+ * getPathComponents("http://typescriptlang.org/path/to/") === ["http://typescriptlang.org/", "path", "to"]
+ * getPathComponents("http://typescriptlang.org/") === ["http://typescriptlang.org/"]
+ * getPathComponents("http://typescriptlang.org") === ["http://typescriptlang.org"]
+ * getPathComponents("file://server/path/to/file.ext") === ["file://server/", "path", "to", "file.ext"]
+ * getPathComponents("file://server/path/to/") === ["file://server/", "path", "to"]
+ * getPathComponents("file://server/") === ["file://server/"]
+ * getPathComponents("file://server") === ["file://server"]
+ * getPathComponents("file:///path/to/file.ext") === ["file:///", "path", "to", "file.ext"]
+ * getPathComponents("file:///path/to/") === ["file:///", "path", "to"]
+ * getPathComponents("file:///") === ["file:///"]
+ * getPathComponents("file://") === ["file://"]
+ */
+export declare function getPathComponents(path: string, currentDirectory?: string): string[];
+/**
+ * Formats a parsed path consisting of a root component (at index 0) and zero or more path
+ * segments (at indices > 0).
+ *
+ * ```ts
+ * getPathFromPathComponents(["/", "path", "to", "file.ext"]) === "/path/to/file.ext"
+ * ```
+ */
+export declare function getPathFromPathComponents(pathComponents: readonly string[]): string;
+/**
+ * Normalize path separators, converting `\` into `/`.
+ */
+export declare function normalizeSlashes(path: string): string;
+/**
+ * Reduce an array of path components to a more simplified path by navigating any
+ * `"."` or `".."` entries in the path.
+ */
+export declare function reducePathComponents(components: readonly string[]): string[];
+/**
+ * Combines paths. If a path is absolute, it replaces any previous path. Relative paths are not simplified.
+ *
+ * ```ts
+ * // Non-rooted
+ * combinePaths("path", "to", "file.ext") === "path/to/file.ext"
+ * combinePaths("path", "dir", "..", "to", "file.ext") === "path/dir/../to/file.ext"
+ * // POSIX
+ * combinePaths("/path", "to", "file.ext") === "/path/to/file.ext"
+ * combinePaths("/path", "/to", "file.ext") === "/to/file.ext"
+ * // DOS
+ * combinePaths("c:/path", "to", "file.ext") === "c:/path/to/file.ext"
+ * combinePaths("c:/path", "c:/to", "file.ext") === "c:/to/file.ext"
+ * // URL
+ * combinePaths("file:///path", "to", "file.ext") === "file:///path/to/file.ext"
+ * combinePaths("file:///path", "file:///to", "file.ext") === "file:///to/file.ext"
+ * ```
+ */
+export declare function combinePaths(path: string, ...paths: (string | undefined)[]): string;
+/**
+ * Parse a path into an array containing a root component (at index 0) and zero or more path
+ * components (at indices > 0). The result is normalized.
+ * If the path is relative, the root component is `""`.
+ * If the path is absolute, the root component includes the first path separator (`/`).
+ *
+ * ```ts
+ * getNormalizedPathComponents("to/dir/../file.ext", "/path/") === ["/", "path", "to", "file.ext"]
+ * ```
+ */
+export declare function getNormalizedPathComponents(path: string, currentDirectory: string | undefined): string[];
+export declare function getNormalizedAbsolutePath(fileName: string, currentDirectory: string | undefined): string;
+export declare function normalizePath(path: string): string;
+export declare function toPath(fileName: string, basePath: string | undefined, getCanonicalFileName: (path: string) => string): Path;
+/**
+ * Removes a trailing directory separator from a path, if it does not already have one.
+ *
+ * ```ts
+ * removeTrailingDirectorySeparator("/path/to/file.ext") === "/path/to/file.ext"
+ * removeTrailingDirectorySeparator("/path/to/file.ext/") === "/path/to/file.ext"
+ * ```
+ */
+export declare function removeTrailingDirectorySeparator(path: Path): Path;
+export declare function removeTrailingDirectorySeparator(path: string): string;
+/**
+ * Adds a trailing directory separator to a path, if it does not already have one.
+ *
+ * ```ts
+ * ensureTrailingDirectorySeparator("/path/to/file.ext") === "/path/to/file.ext/"
+ * ensureTrailingDirectorySeparator("/path/to/file.ext/") === "/path/to/file.ext/"
+ * ```
+ */
+export declare function ensureTrailingDirectorySeparator(path: Path): Path;
+export declare function ensureTrailingDirectorySeparator(path: string): string;
+/**
+ * Ensures a path is either absolute (prefixed with `/` or `c:`) or dot-relative (prefixed
+ * with `./` or `../`) so as not to be confused with an unprefixed module name.
+ *
+ * ```ts
+ * ensurePathIsNonModuleName("/path/to/file.ext") === "/path/to/file.ext"
+ * ensurePathIsNonModuleName("./path/to/file.ext") === "./path/to/file.ext"
+ * ensurePathIsNonModuleName("../path/to/file.ext") === "../path/to/file.ext"
+ * ensurePathIsNonModuleName("path/to/file.ext") === "./path/to/file.ext"
+ * ```
+ */
+export declare function ensurePathIsNonModuleName(path: string): string;
+/**
+ * Compare two paths using the provided case sensitivity.
+ */
+export declare function comparePaths(a: string, b: string, ignoreCase?: boolean): Comparison;
+export declare function comparePaths(a: string, b: string, currentDirectory: string, ignoreCase?: boolean): Comparison;
+export declare function getPathComponentsRelativeTo(from: string, to: string, stringEqualityComparer: (a: string, b: string) => boolean, getCanonicalFileName: GetCanonicalFileName): string[];
+/**
+ * Gets a relative path that can be used to traverse between `from` and `to`.
+ */
+export declare function getRelativePathFromDirectory(from: string, to: string, ignoreCase: boolean): string;
+/**
+ * Gets a relative path that can be used to traverse between `from` and `to`.
+ */
+export declare function getRelativePathFromDirectory(fromDirectory: string, to: string, getCanonicalFileName: GetCanonicalFileName): string;