furi/lib/index.d.mts

File URI manipulation library

/**
 * @module furi
 */
/// <reference types="node" resolution-mode="require"/>
/**
 * A class representing a normalized absolute `file://` URI.
 *
 * This is a subclass of `url.URL` with the following extra checks:
 * - The protocol is `file:`.
 * - The pathname does not contain consecutive slashes (`a//b`) ("normalization").
 * - The pathname does not contain the `.` or `..` segments (enforced by `url.URL` already).
 * - The host `localhost` is represented as the empty string (enforced by `url.URL` already).
 *
 * This class extends `url.URL`. This means that you can pass it to any
 * function expecting a `url.URL`. It also means that the URI is always
 * absolute.
 *
 * Notes:
 * - A single trailing slash is allowed.
 * - The hostname is allowed to be any string. A non-empty string is used by Windows to represents
 *   files on a network drive. An empty string means `localhost`.
 * - The `username`, `password` and `port` properties are always `""` (enforced by `url.URL`
 *   already). This implies that `host` only contains `hostname`.
 * - The `search` and `hash` properties can have any value.
 */
export declare class Furi extends URL {
  constructor(input: UrlLike);
  get protocol(): string;
  set protocol(value: string);
  get pathname(): string;
  set pathname(value: string);
  hasTrailingSlash(): boolean;
  setTrailingSlash(hasTrailingSlash: boolean): void;
  toSysPath(windowsLongPath?: boolean): string;
  toPosixPath(): string;
  toWindowsShortPath(): string;
  toWindowsLongPath(): string;
}
/**
 * A `URL` instance or valid _absolute_ URL string.
 */
export type UrlLike = URL | string;
/**
 * Normalizes the input to a `Furi` instance.
 *
 * @param input URL string or instance to normalize.
 * @returns `Furi` instance. It is always a new instance.
 */
export declare function asFuri(input: UrlLike): Furi;
/**
 * Normalizes the input to a writable `URL` instance.
 *
 * @param input URL string or instance to normalize.
 */
export declare function asWritableUrl(input: UrlLike): URL;
/**
 * Appends the provided components to the pathname of `base`.
 *
 * It does not mutate the inputs.
 * If component list is non-empty, the `hash` and `search` are set to the
 * empty string.
 *
 * @param base Base URL.
 * @param paths Paths to append. A path is either a string representing a relative or absolute file URI, or an array
 *              of components. When passing an array of components, each component will be URI-encoded before being
 *              appended.
 * @returns Joined URL.
 */
export declare function join(base: UrlLike, ...paths: readonly (string | readonly string[])[]): Furi;
/**
 * Computes the relative or absolute `file://` URI from `from` to `to`.
 *
 * The result is an absolute URI only if the arguments have different hosts
 * (for example when computing a URI between different Windows networked drives).
 *
 * If both URIs are equivalent, returns `""`.
 *
 * Otherwise, returns a relative URI starting with `"./"` or `"../".
 *
 * @param from Source URI.
 * @param to Destination URI.
 * @returns Relative (or absolute) URI between the two arguments.
 */
export declare function relative(from: UrlLike, to: UrlLike): string;
/**
 * Returns the basename of the file URI.
 *
 * This function is similar to Node's `require("path").basename`.
 *
 * @param furi Absolute `file://` URI.
 * @param ext Extension (will be removed if present).
 * @returns URI-encoded basename.
 */
export declare function basename(furi: UrlLike, ext?: string): string;
/**
 * Returns the parent URL.
 *
 * If `input` is the root, it returns itself (saturation).
 * If `input` has a trailing separator, it is first removed.
 *
 * @param input Input URL.
 * @returns Parent URL.
 */
export declare function parent(input: UrlLike): URL;
/**
 * Detect if the current platform uses Windows-style paths.
 *
 * This used automatically in functions prefixed by `sys` to get system-dependent behavior.
 */
export declare function isWindows(): boolean;
/**
 * Converts a File URI to a system-dependent path.
 *
 * Use `toPosixPath`, `toWindowsShortPath` or `toWindowsLongPath` if you
 * want system-independent results.
 *
 * Example:
 * ```js
 * // On a Windows system:
 * toSysPath("file:///C:/dir/foo");
 * // -> "C:\\dir\\foo";
 * toSysPath("file:///C:/dir/foo", true);
 * // -> "\\\\?\\C:\\dir\\foo";
 *
 * // On a Posix system:
 * toSysPath("file:///dir/foo");
 * // -> "/dir/foo";
 * ```
 *
 * @param furi File URI to convert.
 * @param windowsLongPath Use long paths on Windows. (default: `false`)
 * @return System-dependent path.
 */
export declare function toSysPath(furi: UrlLike, windowsLongPath?: boolean): string;
/**
 * Converts a File URI to a Windows short path.
 *
 * The result is either a short device path or a short UNC server path.
 *
 * Example:
 * ```js
 * toSysPath("file:///C:/dir/foo");
 * // -> "C:\\dir\\foo";
 * toSysPath("file://server/Users/foo");
 * // -> "\\\\server\\Users\\foo";
 * ```
 *
 * @param furi File URI to convert.
 * @return Windows short path.
 */
export declare function toWindowsShortPath(furi: UrlLike): string;
/**
 * Converts a File URI to a Windows long path.
 *
 * The result is either a long device path or a long UNC server path.
 *
 * Example:
 * ```js
 * toWindowsPath("file:///C:/dir/foo");
 * // -> "\\\\?\\C:\\dir\\foo";
 * toWindowsPath("file://server/Users/foo");
 * // -> "\\\\?\\unc\\server\\Users\\foo";
 * ```
 *
 * @param furi File URI to convert.
 * @return Windows long path.
 */
export declare function toWindowsLongPath(furi: UrlLike): string;
/**
 * Converts a File URI to a Posix path.
 *
 * Requires the host to be either an empty string or `"localhost"`.
 *
 * Example:
 * ```js
 * toPosixPath("file:///dir/foo");
 * // -> "/dir/foo";
 * ```
 *
 * @param furi File URI to convert.
 * @return Posix path.
 */
export declare function toPosixPath(furi: UrlLike): string;
/**
 * Converts an absolute system-dependent path to a frozen URL object.
 *
 * Use `fromPosixPath` or `fromWindowsPath` if you want system-independent
 * results.
 *
 * Example:
 * ```js
 * // On a Windows system:
 * fromSysPath("C:\\dir\\foo");
 * // -> new URL("file:///C:/dir/foo");
 *
 * // On a Posix system:
 * fromSysPath("/dir/foo");
 * // -> new URL("file:///dir/foo");
 * ```
 *
 * @param absPath Absolute system-dependent path to convert
 * @return Frozen `file://` URL object.
 */
export declare function fromSysPath(absPath: string): URL;
/**
 * Converts an absolute Windows path to a frozen URL object.
 *
 * Example:
 * ```js
 * fromWindowsPath("C:\\dir\\foo");
 * // -> new URL(file:///C:/dir/foo");
 * fromWindowsPath("\\\\?\\unc\\server\\Users\\foo");
 * // -> new URL("file://server/Users/foo");
 * ```
 *
 * @param absPath Absolute Windows path to convert
 * @return Frozen `file://` URL object.
 */
export declare function fromWindowsPath(absPath: string): URL;
/**
 * Converts an absolute Posix path to a frozen URL object.
 *
 * Example:
 * ```js
 * fromPosixPath("/dir/foo");
 * // -> new URL(file:///dir/foo");
 * ```
 *
 * @param absPath Absolute Posix path to convert
 * @return Frozen `file://` URL object.
 */
export declare function fromPosixPath(absPath: string): URL;