@ayonli/jsext/types/path/util.d.ts

A JavaScript extension package for building strong and modern applications.

export declare function isNotQuery(str: string): boolean;
export declare function isVolume(path: string, strict?: boolean): boolean;
/**
 * Checks if the given `path` is a Windows specific path.
 * @experimental
 *
 * @example
 * ```ts
 * import { isWindowsPath } from "@ayonli/jsext/path";
 *
 * console.assert(isWindowsPath("C:\\Windows\\System32"));
 * console.assert(isWindowsPath("c:\\Windows\\System32")); // case-insensitive on volume
 * console.assert(isWindowsPath("D:/Program Files")); // forward slash is also valid
 * console.assert(isWindowsPath("E:")); // volume without path is also valid
 * ```
 */
export declare function isWindowsPath(path: string): boolean;
/**
 * Checks if the given `path` is a Posix specific path.
 * @experimental
 *
 * @example
 * ```ts
 * import { isPosixPath } from "@ayonli/jsext/path";
 *
 * console.assert(isPosixPath("/usr/bin"));
 * ```
 */
export declare function isPosixPath(path: string): boolean;
/**
 * Checks if the given `path` is a file system path.
 * @experimental
 *
 * @example
 * ```ts
 * import { isFsPath } from "@ayonli/jsext/path";
 *
 * console.assert(isFsPath("/usr/bin"));
 * console.assert(isFsPath("C:\\Windows\\System32"));
 * console.assert(isFsPath("./foo/bar"));
 * console.assert(isFsPath("../foo/bar"));
 * ```
 */
export declare function isFsPath(path: string): boolean;
/**
 * Checks if the given string is a URL, whether standard or non-standard.
 * @experimental
 *
 * @example
 * ```ts
 * import { isUrl } from "@ayonli/jsext/path";
 *
 * console.assert(isUrl("http://example.com"));
 * console.assert(isUrl("https://example.com?foo=bar#baz"));
 * console.assert(isUrl("ftp://example.com")); // ftp url
 * console.assert(isUrl("file:///C:/Windows/System32")); // file url
 * console.assert(isUrl("file://localhost/C:/Windows/System32")); // file url with hostname
 * console.assert(isUrl("file:///usr/bin"));
 * ```
 */
export declare function isUrl(str: string): boolean;
/**
 * Checks if the given string is a file URL, whether with or without `//`.
 * @experimental
 *
 * @example
 * ```ts
 * import { isFileUrl } from "@ayonli/jsext/path";
 *
 * console.assert(isFileUrl("file:///C:/Windows/System32"));
 * console.assert(isFileUrl("file://localhost/C:/Windows/System32"));
 * console.assert(isFileUrl("file:///usr/bin"));
 * console.assert(isFileUrl("file:/usr/bin"));
 * console.assert(isFileUrl("file:///usr/bin?foo=bar"));
 * ```
 */
export declare function isFileUrl(str: string): boolean;
export declare function isFileProtocol(path: string): boolean;
/**
 * Checks if the given `path` is an absolute path.
 * @experimental
 *
 * @example
 * ```ts
 * import { isAbsolute } from "@ayonli/jsext/path";
 *
 * console.assert(isAbsolute("/usr/bin"));
 * console.assert(isAbsolute("C:\\Windows\\System32"));
 * console.assert(isAbsolute("http://example.com"));
 * console.assert(isAbsolute("file:///C:/Windows/System32"));
 * console.assert(isAbsolute("file://localhost/C:/Windows/System32?foo=bar#baz"));
 * ```
 */
export declare function isAbsolute(path: string): boolean;
/**
 * Splits the `path` into well-formed segments.
 * @experimental
 *
 * @example
 * ```ts
 * import { split } from "@ayonli/jsext/path";
 *
 * console.log(split("/usr/bin")); // ["/", "usr", "bin"]
 * console.log(split("C:\\Windows\\System32")); // ["C:\\", "Windows", "System32"]
 * console.log(split("file:///user/bin")); // ["file:///", "usr", "bin"]
 *
 * console.log(split("http://example.com/foo/bar?foo=bar#baz"));
 * // ["http://example.com", "foo", "bar", "?foo=bar", "#baz"]
 * ```
 */
export declare function split(path: string): string[];
/**
 * Options for path comparison functions, such as {@link contains},
 * {@link startsWith}, {@link endsWith} and {@link equals}.
 */
export interface PathCompareOptions {
    caseInsensitive?: boolean;
    ignoreFileProtocol?: boolean;
}
/**
 * Checks if the `path` contains the given `sub` path.
 *
 * This function doesn't check the path string directly, instead, it checks the
 * path segments.

 * This function is ignorant about the path separator, the query string and the
 * hash string (if present). And is case-insensitive on Windows volume symbol
 * by default.
 *
 * @experimental
 *
 * @example
 * ```ts
 * import { contains } from "@ayonli/jsext/path";
 *
 * console.assert(contains("/usr/bin", "/usr"));
 * console.assert(contains("C:\\Windows\\System32", "Windows\\System32"));
 * console.assert(contains("http://example.com/foo/bar", "foo"));
 * console.assert(contains("file:///C:/Windows/System32", "C:/Windows/System32"));
 *
 * // To be noted, the origin portion of a URL is considered as a whole segment.
 * console.assert(!contains("http://example.com/foo/bar", "example.com"));
 * console.assert(contains("http://example.com/foo/b", "http://example.com"));
 * ```
 */
export declare function contains(path: string, sub: string, options?: PathCompareOptions): boolean;
/**
 * Checks if the `path` starts with the given `sub` path.
 *
 * This function doesn't check the path string directly, instead, it checks the
 * path segments.
 *
 * This function is ignorant about the path separator, the query string and the
 * hash string (if present). And is case-insensitive on Windows volume symbol
 * by default.
 * @experimental
 *
 * @example
 * ```ts
 * import { startsWith } from "@ayonli/jsext/path";
 *
 * console.assert(startsWith("/usr/bin", "/usr"));
 * console.assert(startsWith("C:\\Windows\\System32", "c:/Windows"));
 * console.assert(startsWith("http://example.com/foo/bar", "http://example.com"));
 * console.assert(startsWith("file:///C:/Windows/System32", "file:///c:/Windows"));
 *
 * // To be noted, the origin portion of a URL is considered as a whole segment.
 * console.assert(!startsWith("http://example.com/foo/bar", "example.com"));
 * console.assert(startsWith("http://example.com/foo/b", "http://example.com"));
 *
 * // ignore file protocol
 * console.assert(startsWith("file:///C:/Windows/System32", "C:/Windows/System32", {
 *     ignoreFileProtocol: true,
 * }));
 * ```
 */
export declare function startsWith(path: string, sub: string, options?: PathCompareOptions): boolean;
/**
 * Checks if the `path` ends with the given `sub` path.
 *
 * This function doesn't check the path string directly, instead, it checks the
 * path segments.
 *
 * This function is ignorant about the path separator, the query string and the
 * hash string (if present). And is case-insensitive on Windows volume symbol
 * by default.
 * @experimental
 *
 * @example
 * ```ts
 * import { endsWith } from "@ayonli/jsext/path";
 *
 * console.assert(endsWith("/usr/bin", "bin"));
 * console.assert(endsWith("C:\\Windows\\System32", "System32"));
 * console.assert(endsWith("http://example.com/foo/bar", "bar"));
 * console.assert(endsWith("file:///C:/Windows/System32", "System32"));
 *
 * // To be noted, an absolute sub path has its own root.
 * console.assert(!endsWith("/usr/bin", "/bin"));
 * ```
 */
export declare function endsWith(path: string, sub: string, options?: PathCompareOptions): boolean;
/**
 * Checks if the `path1` and `path2` describe the same path.
 *
 * This function doesn't check the path string directly, instead, it checks the
 * path segments.
 *
 * This function is ignorant about the path separator, the query string and the
 * hash string (if present). And is case-insensitive on Windows volume symbol
 * by default.
 * @experimental
 *
 * @example
 * ```ts
 * import { equals } from "@ayonli/jsext/path";
 *
 * console.assert(equals("/usr/bin", "/usr/bin"));
 * console.assert(equals("C:\\Windows\\System32", "c:/Windows/System32"));
 * console.assert(equals("http://example.com/foo/bar?foo=bar", "http://example.com/foo/bar"));
 * console.assert(equals("file://localhost/C:/Windows/System32", "file:///c:/Windows/System32"));
 *
 * // ignore file protocol
 * console.assert(equals("file:///C:/Windows/System32", "C:\\Windows\\System32", {
 *     ignoreFileProtocol: true,
 * }));
 * ```
 */
export declare function equals(path1: string, path2: string, options?: PathCompareOptions): boolean;