@stryke/path/dist/file-path-fns.d.cts

A package containing various utilities that expand the functionality of NodeJs's built-in `path` module

//#region src/file-path-fns.d.ts
interface FindFileNameOptions extends FindFileExtensionOptions {
  /**
   * Require the file extension to be present in the file name.
   *
   * @defaultValue false
   */
  requireExtension?: boolean;
  /**
   * Return the file extension as part of the full file name result.
   *
   * @defaultValue true
   */
  withExtension?: boolean;
}
/**
 * Find the file name from a file path.
 *
 * @example
 * ```ts
 * const fileName = findFileName("C:\\Users\\user\\Documents\\file.txt");
 * // fileName = "file.txt"
 * ```
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns The file name
 */
declare function findFileName(filePath: string, options?: FindFileNameOptions): string;
/**
 * Find the full file path's directories from a file path.
 *
 * @remarks
 * The functionality of this method is similar to the {@link _path.dirname} function in Node's path module.
 *
 * @example
 * ```ts
 * const folderPath = findFilePath("C:\\Users\\user\\Documents\\file.txt");
 * // folderPath = "C:\\Users\\user\\Documents"
 * ```
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns The full file path's directories
 */
declare function findFilePath(filePath: string, options?: FindFileNameOptions): string;
declare const dirname: typeof findFilePath;
/**
 * Find the top most folder containing the file from a file path.
 *
 * @remarks
 * The functionality of this method is similar to the {@link _path.basename} function in Node's path module.
 * If you're looking for the full path of the folder (for example: `C:\\Users\\user\\Documents` instead of just `Documents`) containing the file, use {@link findFilePath} instead.
 *
 * @example
 * const folderPath = findFolderName("C:\\Users\\user\\Documents\\file.txt");
 * // folderPath = "Documents"
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns The folder containing the file
 */
declare function findFolderName(filePath: string, options?: FindFileNameOptions): string;
declare const basename: typeof findFolderName;
interface FindFileExtensionOptions {
  /**
   * Return the full file extension including `.d` and `.map` if present.
   *
   * @defaultValue false
   */
  fullExtension?: boolean;
}
/**
 * Find the file extension from a file path.
 *
 * @remarks
 * The functionality of this method is similar to the {@link path.extname} function in Node's path module.
 * The file extension is the part of the file name that comes after the last dot (`.`) in the file name. If the file name does not contain a dot, or if it ends with a dot, this function will return `undefined`.
 *
 * The returned extension **will not** include the dot, for example `txt` or `js` instead of `.txt` or `.js`.
 *
 * @example
 * ```ts
 * findFileExtension("C:\\Users\\user\\Documents\\file.config.ts"); // Returns "ts"
 * findFileExtension("C:\\Users\\user\\Documents\\file.d.ts"); // Returns "ts"
 * findFileExtension("C:\\Users\\user\\Documents\\file.d.ts", { fullExtension: true }); // Returns "d.ts"
 * findFileExtension("C:\\Users\\user\\Documents\\file.ts.map"); // Returns "ts"
 * findFileExtension("C:\\Users\\user\\Documents\\file.ts.map", { fullExtension: true }); // Returns "ts.map"
 * findFileExtension("C:\\Users\\user\\Documents\\file"); // Returns undefined
 * ```
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns The file extension or undefined if no extension is found
 */
declare function findFileExtension(filePath: string, options?: FindFileExtensionOptions): string | undefined;
declare const extname: typeof findFileExtension;
/**
 * Find the file extension including the `"."` character prefix from a file path.
 *
 * @remarks
 * The file extension is the part of the file name that comes after (and including) the last dot (`.`) in the file name. If the file name does not contain a dot, or if it ends with a dot, this function will return `undefined`.
 *
 * The returned extension **will** include the dot, for example `.txt` or `.js` instead of `txt` or `js`.
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns The file extension (including the `"."` prefix) or undefined if no extension is found
 */
declare function findFileDotExtension(filePath: string, options?: FindFileExtensionOptions): string | undefined;
/**
 * Find the file extension from a file path or an empty string.
 *
 *  @remarks
 * The file extension is the part of the file name that comes after the last dot (`.`) in the file name. If the file name does not contain a dot, or if it ends with a dot, this function will return `undefined`.
 *
 * The returned extension **will not** include the dot, for example `txt` or `js` instead of `.txt` or `.js`.
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns The file extension or an empty string if no extension is found
 */
declare function findFileExtensionSafe(filePath: string, options?: FindFileExtensionOptions): string;
/**
 * Find the file extension including the `"."` character prefix from a file path or an empty string.
 *
 *  @remarks
 * The file extension is the part of the file name that comes after (and including) the last dot (`.`) in the file name. If the file name does not contain a dot, or if it ends with a dot, this function will return `undefined`.
 *
 * The returned extension **will** include the dot, for example `.txt` or `.js` instead of `txt` or `js`.
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns The file extension (including the `"."` prefix) or an empty string if no extension is found
 */
declare function findFileDotExtensionSafe(filePath: string, options?: FindFileExtensionOptions): string;
/**
 * Check if a file path has a file name.
 *
 * @param filePath - The file path to process
 * @returns An indicator specifying if the file path has a file name
 */
declare function hasFileName(filePath: string): boolean;
/**
 * Check if a file path has a file path.
 *
 * @param filePath - The file path to process
 * @returns An indicator specifying if the file path has a file path
 */
declare function hasFilePath(filePath: string): boolean;
/**
 * Check if a file path has a folder name.
 *
 * @param filePath - The file path to process
 * @returns An indicator specifying if the file path has a folder name
 */
declare function hasFolderName(filePath: string): boolean;
/**
 * Check if a file path has a file extension.
 *
 * @param filePath - The file path to process
 * @param options - Options to control the file name extraction
 * @returns An indicator specifying if the file path has a file extension
 */
declare function hasFileExtension(filePath: string, options?: FindFileExtensionOptions): boolean;
/**
 * Resolve the file path to an absolute path.
 *
 * @param path - The path to resolve
 * @param cwd - The current working directory
 * @returns The resolved path
 */
declare function resolvePath(path: string, cwd?: any): string;
declare function resolve(...paths: string[]): string;
/**
 * Resolve the file path to an absolute path.
 *
 * @param paths - The paths to resolve
 * @returns The resolved path
 */
declare function resolvePaths(...paths: string[]): string;
/**
 * Get the relative path from one file to another.
 *
 * @remarks
 * This function is similar to the `path.relative` function in Node's path module.
 *
 * @param from - The base path to start from
 * @param to - The target path to resolve relative to the base path
 * @returns The relative path from the base path to the target path
 */
declare function relative(from: string, to: string): string;
/**
 * Get the relative path from one file to another.
 *
 * @remarks
 * This function wraps the `path.relative` function in Node's path module.
 *
 * @param from - The base path to start from
 * @param to - The target path to resolve relative to the base path
 * @param withEndSlash - Whether to include a trailing slash at the end of the path
 * @returns The relative path from the base path to the target path
 */
declare function relativePath(from: string, to: string, withEndSlash?: boolean): string;
/**
 * Find the file path relative to the workspace root path.
 *
 * @param filePath - The file path to process
 * @returns The resolved file path
 */
declare function relativeToCurrentDir(filePath: string): string;
/**
 * Check if the path is a relative path.
 *
 * @param path - The path to check
 * @returns An indicator specifying if the path is a relative path
 */
declare function parsePath(path: string, options?: FindFileNameOptions): {
  root: string;
  dir: string;
  base: string;
  ext: string;
  name: string;
};
/**
 * Rename the file name with a new name.
 *
 * @param filePath - The current file path being processed
 * @param newFileName - The updated file name being processed
 * @param options - Options to control the file name extraction
 * @returns The modified or unmodified file path.
 */
declare function renameFile(filePath: string, newFileName: string, options?: FindFileNameOptions): string;
//#endregion
export { FindFileExtensionOptions, FindFileNameOptions, basename, dirname, extname, findFileDotExtension, findFileDotExtensionSafe, findFileExtension, findFileExtensionSafe, findFileName, findFilePath, findFolderName, hasFileExtension, hasFileName, hasFilePath, hasFolderName, parsePath, relative, relativePath, relativeToCurrentDir, renameFile, resolve, resolvePath, resolvePaths };
//# sourceMappingURL=file-path-fns.d.cts.map