@nomicfoundation/hardhat-utils 3.0.0-next.0

package/dist/src/fs.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Determines the canonical pathname for a given path, resolving any symbolic
+ * links, and returns it.
+ *
+ * @throws FileNotFoundError if absolutePath doesn't exist.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function getRealPath(absolutePath: string): Promise<string>;
+/**
+ * Recursively searches a directory and its subdirectories for files that
+ * satisfy the specified condition, returning their absolute paths.
+ *
+ * @param dirFrom The absolute path of the directory to start the search from.
+ * @param matches A function to filter files (not directories).
+ * @returns An array of absolute paths. Each file has its true case, except
+ *  for the initial dirFrom part, which preserves the given casing.
+ *  No order is guaranteed. If dirFrom doesn't exist `[]` is returned.
+ * @throws NotADirectoryError if dirFrom is not a directory.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function getAllFilesMatching(dirFrom: string, matches?: (absolutePathToFile: string) => boolean): Promise<string[]>;
+/**
+ * Recursively searches a directory and its subdirectories for directories that
+ * satisfy the specified condition, returning their absolute paths. Once a
+ * directory is found, its subdirectories are not searched.
+ *
+ * Note: dirFrom is never returned, nor `matches` is called on it.
+ *
+ * @param dirFrom The absolute path of the directory to start the search from.
+ * @param matches A function to filter directories (not files).
+ * @returns An array of absolute paths. Each path has its true case, except
+ *  for the initial dirFrom part, which preserves the given casing.
+ *  No order is guaranteed. If dirFrom doesn't exist `[]` is returned.
+ * @throws NotADirectoryError if dirFrom is not a directory.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function getAllDirectoriesMatching(dirFrom: string, matches?: (absolutePathToDir: string) => boolean): Promise<string[]>;
+/**
+ * Determines the true case path of a given relative path from a specified
+ * directory, without resolving symbolic links, and returns it.
+ *
+ * @param from The absolute path of the directory to start the search from.
+ * @param relativePath The relative path to get the true case of.
+ * @returns The true case of the relative path.
+ * @throws FileNotFoundError if the starting directory or the relative path doesn't exist.
+ * @throws NotADirectoryError if the starting directory is not a directory.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function getFileTrueCase(from: string, relativePath: string): Promise<string>;
+/**
+ * Checks if a given path is a directory.
+ *
+ * @param absolutePath The path to check.
+ * @returns `true` if the path is a directory, `false` otherwise.
+ * @throws FileNotFoundError if the path doesn't exist.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function isDirectory(absolutePath: string): Promise<boolean>;
+/**
+ * Reads a JSON file and parses it. The encoding used is "utf8".
+ *
+ * @param absolutePathToFile The path to the file.
+ * @returns The parsed JSON object.
+ * @throws FileNotFoundError if the file doesn't exist.
+ * @throws InvalidFileFormatError if the file is not a valid JSON file.
+ * @throws IsDirectoryError if the path is a directory instead of a file.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function readJsonFile<T>(absolutePathToFile: string): Promise<T>;
+/**
+ * Writes an object to a JSON file. The encoding used is "utf8" and the file is overwritten.
+ * If part of the path doesn't exist, it will be created.
+ *
+ * @param absolutePathToFile The path to the file. If the file exists, it will be overwritten.
+ * @param object The object to write.
+ * @throws JsonSerializationError if the object can't be serialized to JSON.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function writeJsonFile<T>(absolutePathToFile: string, object: T): Promise<void>;
+/**
+ * Reads a file and returns its content as a string. The encoding used is "utf8".
+ *
+ * @param absolutePathToFile The path to the file.
+ * @returns The content of the file as a string.
+ * @throws FileNotFoundError if the file doesn't exist.
+ * @throws IsDirectoryError if the path is a directory instead of a file.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function readUtf8File(absolutePathToFile: string): Promise<string>;
+/**
+ * Writes a string to a file. The encoding used is "utf8" and the file is overwritten by default.
+ * If part of the path doesn't exist, it will be created.
+ *
+ * @param absolutePathToFile The path to the file.
+ * @param data The data to write.
+ * @param flag The flag to use when writing the file. If not provided, the file will be overwritten.
+ * See https://nodejs.org/docs/latest-v20.x/api/fs.html#file-system-flags for more information.
+ * @throws FileAlreadyExistsError if the file already exists and the flag "x" is used.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function writeUtf8File(absolutePathToFile: string, data: string, flag?: string): Promise<void>;
+/**
+ * Reads a file and returns its content as a Uint8Array.
+ *
+ * @param absolutePathToFile The path to the file.
+ * @returns The content of the file as a Uint8Array.
+ * @throws FileNotFoundError if the file doesn't exist.
+ * @throws IsDirectoryError if the path is a directory instead of a file.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function readBinaryFile(absolutePathToFile: string): Promise<Uint8Array>;
+/**
+ * Reads a directory and returns its content as an array of strings.
+ *
+ * @param absolutePathToDir The path to the directory.
+ * @returns An array of strings with the names of the files and directories in the directory.
+ * @throws FileNotFoundError if the directory doesn't exist.
+ * @throws NotADirectoryError if the path is not a directory.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function readdir(absolutePathToDir: string): Promise<string[]>;
+/**
+ * Creates a directory and any necessary directories along the way. If the directory already exists,
+ * nothing is done.
+ *
+ * @param absolutePath The path to the directory to create.
+ * @throws FileSystemAccessError for any error.
+ */
+export declare function mkdir(absolutePath: string): Promise<void>;
+/**
+ * Alias for `mkdir`.
+ * @see mkdir
+ */
+export declare const ensureDir: typeof mkdir;
+/**
+ * Retrieves the last change time of a file or directory's properties.
+ * This includes changes to the file's metadata or contents.
+ *
+ * @param absolutePath The absolute path to the file or directory.
+ * @returns The time of the last change as a Date object.
+ * @throws FileNotFoundError if the path does not exist.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function getChangeTime(absolutePath: string): Promise<Date>;
+/**
+ * Retrieves the last access time of a file or directory's properties.
+ *
+ * @param absolutePath The absolute path to the file or directory.
+ * @returns The time of the last access as a Date object.
+ * @throws FileNotFoundError if the path does not exist.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function getAccessTime(absolutePath: string): Promise<Date>;
+/**
+ * Retrieves the size of a file.
+ *
+ * @param absolutePath The absolute path to the file.
+ * @returns The size of the file in bytes.
+ * @throws FileNotFoundError if the path does not exist.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function getFileSize(absolutePath: string): Promise<number>;
+/**
+ * Checks if a file or directory exists.
+ *
+ * @param absolutePath The absolute path to the file or directory.
+ * @returns A boolean indicating whether the file or directory exists.
+ */
+export declare function exists(absolutePath: string): Promise<boolean>;
+/**
+ * Copies a file from a source to a destination.
+ * If the destination file already exists, it will be overwritten.
+ *
+ * @param source The path to the source file. It can't be a directory.
+ * @param destination The path to the destination file. It can't be a directory.
+ * @throws FileNotFoundError if the source path or the destination path doesn't exist.
+ * @throws IsDirectoryError if the source path or the destination path is a directory.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function copy(source: string, destination: string): Promise<void>;
+/**
+ * Moves a file or directory from a source to a destination. If the source is a
+ * file and the destination is a file that already exists, it will be overwritten.
+ * If the source is a directory and the destination is a directory, it needs to be empty.
+ *
+ * Note: This method may not work when moving files between different mount points
+ * or file systems, as the underlying `fsPromises.rename` method may not support it.
+ *
+ * @param source The path to the source file or directory.
+ * @param destination The path to the destination file or directory.
+ * @throws FileNotFoundError if the source path or the destination path doesn't exist.
+ * @throws DirectoryNotEmptyError if the source path is a directory and the destination
+ * path is a directory that is not empty.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function move(source: string, destination: string): Promise<void>;
+/**
+ * Removes a file or directory recursively.
+ * Exceptions are ignored for non-existent paths.
+ *
+ * @param absolutePath The path to the file or directory to remove.
+ * @throws FileSystemAccessError for any error, except for non-existent path errors.
+ */
+export declare function remove(absolutePath: string): Promise<void>;
+/**
+ * Changes the permissions of a file or directory.
+ *
+ * @param absolutePath The path to the file or directory.
+ * @param mode The permissions to set. It can be a string or a number representing the octal mode.
+ * @throws FileNotFoundError if the path doesn't exist.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function chmod(absolutePath: string, mode: string | number): Promise<void>;
+/**
+ * Creates a file with an empty content. If the file already exists, it will be overwritten.
+ * If part of the path doesn't exist, it will be created.
+ *
+ * @param absolutePath The path to the file to create.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function createFile(absolutePath: string): Promise<void>;
+/**
+ * Empties a directory by recursively removing all its content. If the
+ * directory doesn't exist, it will be created. The directory itself is
+ * not removed.
+ *
+ * @param absolutePath The path to the directory to empty.
+ * @throws NotADirectoryError if the path is not a directory.
+ * @throws FileSystemAccessError for any other error.
+ */
+export declare function emptyDir(absolutePath: string): Promise<void>;
+/**
+ * Looks for a file in the current directory and its parents.
+ *
+ * @param fileName The name of the file to look for.
+ * @param from The directory to start the search from. Defaults to the current working directory.
+ * @returns The absolute path to the file, or `undefined` if it wasn't found.
+ */
+export declare function findUp(fileName: string, from?: string): Promise<string | undefined>;
+export { FileNotFoundError, FileSystemAccessError, InvalidFileFormatError, JsonSerializationError, FileAlreadyExistsError, NotADirectoryError, IsDirectoryError, DirectoryNotEmptyError, } from "./errors/fs.js";
+//# sourceMappingURL=fs.d.ts.map

package/dist/src/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/fs.ts"],"names":[],"mappings":"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"}