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

A JavaScript extension package for building strong and modern applications.

/**
 * Platform-independent utility functions for dealing with file system paths and
 * URLs.
 *
 * The functions in this module are designed to be generic and work in any
 * runtime, whether server-side or browsers. They can be used for both system
 * paths and URLs.
 * @module
 */
import { contains, endsWith, equals, isAbsolute, isFileUrl, isFsPath, isPosixPath, isUrl, isWindowsPath, split, startsWith, type PathCompareOptions } from "./path/util.ts";
export type { PathCompareOptions };
export { isWindowsPath, isPosixPath, isFsPath, isUrl, isFileUrl, isAbsolute, contains, endsWith, startsWith, equals, split, };
/**
 * Platform-specific path segment separator. The value is `\` in Windows
 * server-side environments, and `/` elsewhere.
 */
export declare const sep: "/" | "\\";
/**
 * Returns the current working directory.
 *
 * **NOTE:** In the browser, this function returns the current origin and pathname.
 *
 * This function may fail in unsupported environments or being rejected by the
 * permission system of the runtime.
 */
export declare function cwd(): string;
/**
 * Concatenates all given `segments` into a well-formed path.
 * @experimental
 *
 * @example
 * ```ts
 * import { join } from "@ayonli/jsext/path";
 *
 * console.log(join("foo", "bar")); // "foo/bar" or "foo\\bar" on Windows
 * console.log(join("/", "foo", "bar")); // "/foo/bar"
 * console.log(join("C:\\", "foo", "bar")); // "C:\\foo\\bar"
 * console.log(join("file:///foo", "bar", "..")) // "file:///foo"
 *
 * console.log(join("http://example.com", "foo", "bar", "?query"));
 * // "http://example.com/foo/bar?query"
 * ```
 */
export declare function join(...segments: string[]): string;
/**
 * This function is similar to Node.js implementation, but does not preserve
 * trailing slashes.
 *
 * Since Node.js implementation is not well-designed and this function is
 * identical as calling `join(path)`, so it is deprecated.
 * @experimental
 *
 * @deprecated use {@link join} or {@link sanitize} instead.
 */
export declare function normalize(path: string): string;
/**
 * Similar to {@link normalize}, but also remove the search string and hash
 * string if present.
 * @experimental
 *
 * @example
 * ```ts
 * import { sanitize } from "@ayonli/jsext/path";
 *
 * console.log(sanitize("foo/bar?query")); // "foo/bar"
 * console.log(sanitize("foo/bar#hash")); // "foo/bar"
 * console.log(sanitize("foo/bar/..?query#hash")); // "foo"
 * console.log(sanitize("foo/./bar/..?query#hash")); // "foo"
 * ```
 */
export declare function sanitize(path: string): string;
/**
 * Resolves path `segments` into a well-formed path.
 *
 * This function is similar to {@link join}, except it always returns an
 * absolute path based on the current working directory if the input segments
 * are not absolute by themselves.
 * @experimental
 */
export declare function resolve(...segments: string[]): string;
/**
 * Returns the parent path of the given `path`.
 * @experimental
 *
 * @example
 * ```ts
 * import { dirname } from "@ayonli/jsext/path";
 *
 * console.log(dirname("foo/bar")); // "foo"
 * console.log(dirname("/foo/bar")); // "/foo"
 * console.log(dirname("C:\\foo\\bar")); // "C:\\foo"
 * console.log(dirname("file:///foo/bar")); // "file:///foo"
 * console.log(dirname("http://example.com/foo/bar")); // "http://example.com/foo"
 * console.log(dirname("http://example.com/foo")); // "http://example.com"
 * console.log(dirname("http://example.com/foo/bar?foo=bar#baz")); // "http://example.com/foo"
 * ```
 */
export declare function dirname(path: string): string;
/**
 * Return the last portion of the given `path`. Trailing directory separators
 * are ignored, and optional `suffix` is removed.
 * @experimental
 *
 * @example
 * ```ts
 * import { basename } from "@ayonli/jsext/path";
 *
 * console.log(basename("/foo/bar")); // "bar"
 * console.log(basename("c:\\foo\\bar")); // "bar"
 * console.log(basename("file:///foo/bar")); // "bar"
 * console.log(basename("http://example.com/foo/bar")); // "bar"
 * console.log(basename("http://example.com/foo/bar?foo=bar#baz")); // "bar"
 * console.log(basename("http://example.com/foo/bar.txt?foo=bar#baz", ".txt")); // "bar"
 * ```
 */
export declare function basename(path: string, suffix?: string): string;
/**
 * Returns the extension of the `path` with leading period.
 * @experimental
 *
 * @example
 * ```ts
 * import { extname } from "@ayonli/jsext/path";
 *
 * console.log(extname("/foo/bar.txt")); // ".txt"
 * console.log(extname("c:\\foo\\bar.txt")); // ".txt"
 * console.log(extname("file:///foo/bar.txt")); // ".txt"
 * console.log(extname("http://example.com/foo/bar.txt")); // ".txt"
 * console.log(extname("http://example.com/foo/bar.txt?foo=bar#baz")); // ".txt"
 * ```
 */
export declare function extname(path: string): string;
/**
 * Converts the given path to a file URL if it's not one already.
 * @experimental
 *
 * @example
 * ```ts
 * import { toFileUrl } from "@ayonli/jsext/path";
 *
 * console.log(toFileUrl("foo/bar")); // "file:///foo/bar"
 * console.log(toFileUrl("c:\\foo\\bar")); // "file:///c:/foo/bar"
 * ```
 */
export declare function toFileUrl(path: string): string;
/**
 * Converts the given URL to a file system path if it's not one already.
 * @experimental
 *
 * @example
 * ```ts
 * import { toFsPath } from "@ayonli/jsext/path";
 *
 * console.log(toFsPath("file:///foo/bar")); // "/foo/bar"
 * console.log(toFsPath("file:///c:/foo/bar")); // "c:\\foo\\bar"
 * ```
 */
export declare function toFsPath(url: string): string;