kaven-utils/src/KavenUtility.FileSystem.d.ts

Utils for Node.js.

/********************************************************************
 * @author:      Kaven
 * @email:       kaven@wuwenkai.com
 * @website:     http://blog.kaven.xyz
 * @file:        [Kaven-Utils] /src/KavenUtility.FileSystem.ts
 * @create:      2021-08-06 23:39:38.618
 * @modify:      2025-10-24 16:32:50.692
 * @version:     6.1.2
 * @times:       113
 * @lines:       780
 * @copyright:   Copyright © 2021-2025 Kaven. All Rights Reserved.
 * @description: [description]
 * @license:     [license]
 ********************************************************************/
import { ILoggingAgent, ITextLines } from "kaven-basic";
import { Stats } from "node:fs";
import { ICopyFileOptions, IDeleteFilesByExtensionOptions, IFileEnumerateOptions } from "./base/Interfaces.js";
/**
 * Simple wrap for existsSync
 * @see https://nodejs.org/docs/latest-v8.x/api/html#fs_fs_existssync_path
 * @since 3.0.0
 * @since 2021-08-06
 */
export declare function IsPathExistSync(...paths: string[]): boolean;
/**
 * @since 3.0.0
 * @version 2021-08-06
 */
export declare function GetFileStats(path: string): Promise<Stats | undefined>;
/**
 * @since 2.0.2
 * @version 2021-08-06
 */
export declare function IsFile(path: string): Promise<boolean | undefined>;
/**
 * @since 1.0.5
 * @version 2021-08-06
 */
export declare function IsDirectory(path: string): Promise<boolean | undefined>;
/**
 * @since 1.0.9
 * @version 2021-08-06
 */
export declare function GetFileSizeInBytes(path: string): Promise<number | undefined>;
/**
 * @since 3.0.0
 * @version 2021-08-07
 */
export declare function GetFileSize(path: string, baseOn1024?: boolean): Promise<string | undefined>;
/***
 * @since 3.0.0
 * @version 2023-12-06
 */
export declare function DeleteFile(file: string): Promise<void>;
/**
 * @since 5.4.0
 * @version 2023-12-06
 */
export declare function DeleteFileIfExists(file: string): Promise<boolean>;
/**
 * @since 5.4.0
 * @version 2025-10-14
 */
export declare function TryDeleteFile(file: string, logger?: ILoggingAgent): Promise<boolean>;
/**
 * @since 4.0.0
 * @version 2023-12-06
 */
export declare function TryDeleteFiles(...files: string[]): Promise<void>;
/**
 * @since 3.0.0
 * @version 2023-12-06
 */
export declare function DeleteDirectory(path: string): Promise<void>;
/**
 * @since 5.4.0
 * @version 2025-10-14
 */
export declare function TryDeleteDirectory(path: string, logger?: ILoggingAgent): Promise<void>;
/**
 * @since 1.0.9
 * @version 2025-10-24
 * @return The first directory path created.
 */
export declare function MakeDirectory(path: string): Promise<string | undefined>;
/**
 * @since 5.4.0
 * @version 2025-10-14
 */
export declare function TryMakeDirectory(path: string, logger?: ILoggingAgent): Promise<string | undefined>;
/**
 * @since 1.0.9
 * @version 2025-10-24
 */
export declare function MakeDirectorySync(path: string): string | undefined;
/**
 * @since 5.4.0
 * @version 2025-10-24
 */
export declare function TryMakeDirectorySync(path: string, logger?: ILoggingAgent): string | undefined;
/**
 * @since 5.4.0
 * @version 2023-12-06
 */
export declare function Delete(...paths: string[]): Promise<void>;
/**
 * @since 5.4.0
 * @version 2023-12-06
 */
export declare function TryDelete(...paths: string[]): Promise<void>;
/**
 * Copies a file from the source path to the destination path asynchronously.
 *
 * @example "/path/to/source/file.txt" -> "/path/to/destination/file.txt"
 * @param src - The source path of the file to be copied.
 * @param dest - The destination path where the file will be copied.
 * @param checkSrcExists - If true, checks whether the source file exists before copying.
 * @returns A Promise that resolves to true if the file is copied successfully, or false if the source file doesn't exist.
 * @since 3.0.0
 * @version 2025-10-24
 */
export declare function CopyFile(src: string, dest: string, options?: ICopyFileOptions): Promise<boolean>;
/**
 *
 * @param path
 * @param len
 * @since 3.0.0
 * @version 2021-08-07
 */
export declare function TruncateFile(path: string, len?: number): Promise<void>;
/**
 *
 * @param dest
 * @param src
 * @since 1.0.5
 * @version 2021-08-06
 */
export declare function CopyFileSync(src: string, dest: string): void;
/**
 * Recursively copies the contents of a directory from the source path to the destination path asynchronously.
 *
 * @example "/path/to/source/directory" -> "/path/to/destination/directory"
 * @param src - The source path of the directory to be copied.
 * @param dest - The destination path where the directory and its contents will be copied.
 * @returns A Promise that resolves when the directory and its contents are copied successfully.
 * @since 3.0.0
 * @version 2025-10-24
 */
export declare function CopyDirectory(src: string, dest: string, options?: ICopyFileOptions): Promise<void>;
/**
 * Copies a file or a directory from the source path to the destination path asynchronously.
 * If the source is a directory, its entire contents will be recursively copied.
 *
 * @example
 *     "/path/to/source/directory" -> "/path/to/destination/directory"
 *     "/path/to/source/file.txt" -> "/path/to/destination/file.txt"
 * @param src - The source path of the file or directory to be copied.
 * @param dest - The destination path where the file or directory will be copied.
 * @returns A Promise that resolves to true if the file or directory is copied successfully, or false if it doesn't exist.
 * @since 3.0.0
 * @version 2025-10-24
 */
export declare function CopyFileOrDirectory(src: string, dest: string, options?: ICopyFileOptions): Promise<boolean>;
/**
 * Copies an array of files or directories to a destination directory asynchronously.
 *
 * @example
 *      1. "/path/to/source/file.txt" -> "/path/to/destination"
 *      2. "/path/to/source/directory" -> "/path/to/destination"
 *      3. ["/path/to/source/file.txt", "/path/to/source/directory"] -> "/path/to/destination"
 * @param files - An array of file or directory paths to be copied.
 * @param destDir - The destination directory where the files or directories will be copied.
 * @since 3.0.0
 * @version 2025-10-24
 */
export declare function CopyToDirectory(files: string | string[], destDir: string, options?: ICopyFileOptions): Promise<void>;
/**
 * @since 1.0.5
 * @version 2021-12-07
 */
export declare function GetFileExtension(fileName: string, trimDot?: boolean, toLowerCase?: boolean): string;
/**
 *
 * @param fileName
 * @version 2018-11-06
 * @since 1.0.5
 */
export declare function GetFileName(fileName: string): string;
/**
 * @since 4.1.0
 * @version 2023-12-05
 */
export declare function AppendPathToDirectory(dir: string | undefined, path: string): string;
/**
 * @since 5.4.0
 * @version 2025-10-24
 */
export declare function AppendPathThenCreateDirectory(dir: string | undefined, path: string): string;
/**
 * @since 5.4.0
 * @version 2025-10-24
 */
export declare function AppendPathThenCreateParentDirectory(dir: string | undefined, path: string): string;
/**
 *
 * @param path
 * @param dir
 * @since 4.3.1
 * @version 2022-06-29
 */
export declare function PathIsSubOfDirectory(path: string, dir: string): boolean;
/**
 * @since 4.3.1
 * @version 2022-06-29
 */
export declare function PathNeedExclude(path: string, excludePaths: string[]): boolean;
/**
 * Asynchronously finds a subdirectory with a specific name in the given directory.
 * Returns the name of the subdirectory if found, or undefined otherwise.
 *
 * @param dir - The path of the directory to search.
 * @param name - The name of the subdirectory to find.
 * @param [ignoreCase=false] - If true, performs a case-insensitive comparison.
 * @returns A Promise that resolves to the name of the found subdirectory or undefined if not found.
 * @since 5.0.5
 * @version 2023-11-25
 */
export declare function FindSubdirectoryByName(dir: string, name: string, ignoreCase?: boolean): Promise<string | undefined>;
/**
 * @param {string} data
 * @param {string} path
 * @since 1.0.6
 * @version 2024-11-01
 */
export declare function SaveStringToFile(data: string, path: string): Promise<string>;
/**
 *
 * @param path
 * @param options
 * @since 1.0.5
 * @version 2025-07-12
 */
export declare function GetFileContent(path: string, options?: BufferEncoding): Promise<string>;
/**
 * @since 5.0.1
 * @version 2025-06-21
 */
export declare function GetFileContentSync(path: string, options?: BufferEncoding): string;
/**
 * @param {string} path
 * @since 1.0.12
 * @version 2023-12-11
 */
export declare function LoadJsonFile<T>(path: string): Promise<T>;
/**
 * @param {string} path
 * @since 5.0.1
 * @version 2023-12-11
 */
export declare function LoadJsonFileSync<T>(path: string): T;
/**
 * @since 3.0.1
 * @version 2025-06-18
 */
export declare function GetFileLines(fileName: string): Promise<ITextLines>;
/**
 * @param data
 * @param path
 * @since 5.0.1
 * @version 2023-11-18
 */
export declare function SaveStringToFileSync(data: string, path: string): string;
/**
 * @since 5.4.3
 * @version 2025-10-14
 */
export declare function DeleteFilesByExtension(src: string | string[], extensions: string[], options?: IDeleteFilesByExtensionOptions): Promise<void>;
/**
 * Asynchronously enumerates files starting from one or more input paths.
 *
 * This async generator yields file paths (as strings) discovered while traversing
 * the provided path(s). Directory traversal is breadth-first (queue-based).
 *
 * @example
 * // Recursively enumerate all files under "src" and "test"
 * for await (const file of EnumerateFiles(["src", "test"])) {
 *   console.log(file);
 * }
 *
 * @since 6.1.1
 * @version 2025-10-23
 */
export declare function EnumerateFiles(input: string | string[], options?: IFileEnumerateOptions): AsyncIterable<string>;