@nasriya/atomix
Version:
Composable helper functions for building reliable systems
96 lines (95 loc) • 4 kB
TypeScript
declare class PathUtils {
/**
* Normalizes the given path by resolving it to an absolute path and converting
* it to lowercase if the current platform is Windows.
* @param path_ The path to normalize.
* @returns The normalized path.
* @since v1.0.0
*/
normalizePath(path_: string): string;
/**
* Returns a sanitized and safe file or folder name by replacing or removing illegal characters.
* Illegal characters differ between platforms, so this method handles Windows and POSIX systems.
*
* @param name - The file or folder name to sanitize.
* @param replacement - The character(s) to replace illegal characters with. Defaults to '_'.
* @returns The sanitized safe name.
* @since v1.0.0
* @example
* const safeName = sanitizeName('my*illegal:file?.txt');
* // safeName === 'my_illegal_file_.txt'
*/
sanitizeName(name: string, replacement?: string): string;
/**
* Determines if the given child path is a sub-path of the given parent path.
*
* @param childPath - The path to check as a sub-path.
* @param parentPath - The path to check as the parent.
* @returns True if the child path is a sub-path of the parent path, false otherwise.
* @since v1.0.0
* @example
* const isSub = isSubPath('/path/to/child', '/path/to');
* isSub is true
*/
isSubPath(childPath: string, parentPath: string): boolean;
/**
* Gets the filename of the given path without the file extension.
* @param filePath - The path to get the filename from.
* @returns The filename without extension.
* @since v1.0.0
* @example
* const filename = getFileNameWithoutExtension('/path/to/file.txt');
* filename is 'file'
*/
getFileNameWithoutExtension(filePath: string): string;
/**
* Changes the file extension of the given path to the specified new extension.
* @param filePath - The path to change the extension of.
* @param newExt - The new file extension to set. Must be a valid file extension.
* @returns The modified path with the new extension.
* @throws Error if the provided new extension is not a valid file extension.
* @since v1.0.0
* @example
* const newFilePath = changeExtension('/path/to/file.txt', '.json');
* newFilePath is '/path/to/file.json'
*/
changeExtension(filePath: string, newExt: string): string;
/**
* Checks if the given string is a valid file path.
*
* On Windows, this checks that the path does not contain any of the following characters:
* - `<>:"|?*`
* - ASCII control characters (characters with code points less than 32)
*
* On Unix-like platforms, this only checks that the path is not empty and does not contain the null byte (`\0`).
*
* @param path_ - The path to check.
* @returns True if the path is valid, false otherwise.
* @since v1.0.0
*/
isValidPath(path_: string): boolean;
/**
* Gets the relative path from the current working directory to the given path.
*
* @param path_ - The path to get the relative path from the current working directory.
* @returns The relative path from the current working directory to the given path.
* @since v1.0.0
* @example
* const relativePath = pathUtils.relativeToCwd('/Users/username/Documents/file.txt');
* relativePath is 'Users/username/Documents/file.txt'
*/
relativeToCwd(path_: string): string;
/**
* Heuristically determines if the given string is likely a file path.
*
* @param str - The string to check.
* @returns True if the string is likely a file path, false otherwise.
* @since v1.0.17
* @example
* const isLikelyPath = atomix.path.isLikelyPath('./foo/bar.txt');
* console.log(isLikelyPath); // true
*/
isLikelyPath(str: string): boolean;
}
declare const pathUtils: PathUtils;
export default pathUtils;