@catbee/utils 0.0.8-next.0 → 0.0.8-rc.0

package/build/esm/utils/fs.utils.d.ts

@@ -0,0 +1,164 @@
+import { BufferEncoding } from './crypto.utils';
+import { Stats } from 'fs';
+/**
+ * Checks whether a file or directory exists at the given path.
+ *
+ * @param {string} path - The file or directory path to check.
+ * @returns {Promise<boolean>} Resolves to `true` if the path exists, `false` otherwise.
+ */
+export declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Reads and parses a JSON file from the specified path.
+ *
+ * @typeParam T - The expected type of the parsed JSON object.
+ * @param {string} path - The path to the JSON file.
+ * @returns {Promise<T | null>} The parsed object, or `null` if reading or parsing fails.
+ */
+export declare function readJsonFile<T = any>(path: string): Promise<T | null>;
+/**
+ * Writes a JavaScript object to a file as formatted JSON.
+ *
+ * @param {string} path - The destination file path.
+ * @param {any} data - The object to serialize and write.
+ * @param {number} [space=2] - Number of spaces for JSON formatting.
+ * @returns {Promise<void>} Resolves when writing is complete.
+ */
+export declare function writeJsonFile(path: string, data: any, space?: number): Promise<void>;
+/**
+ * Deletes a file if it exists.
+ *
+ * @param {string} path - The file path to delete.
+ * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.
+ */
+export declare function deleteFileIfExists(path: string): Promise<boolean>;
+/**
+ * Reads a text file from the specified path.
+ *
+ * @param {string} path - The path to the text file.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
+ */
+export declare function readTextFile(path: string, encoding?: BufferEncoding): Promise<string | null>;
+/**
+ * Writes text content to a file.
+ *
+ * @param {string} path - The destination file path.
+ * @param {string} content - The text content to write.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+export declare function writeTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
+/**
+ * Appends text content to a file.
+ *
+ * @param {string} path - The file path to append to.
+ * @param {string} content - The text content to append.
+ * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+export declare function appendTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
+/**
+ * Copies a file from source to destination.
+ *
+ * @param {string} source - Source file path.
+ * @param {string} destination - Destination file path.
+ * @param {boolean} [overwrite=false] - Whether to overwrite if destination exists.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+export declare function copyFile(source: string, destination: string, overwrite?: boolean): Promise<boolean>;
+/**
+ * Renames/moves a file.
+ *
+ * @param {string} oldPath - Current file path.
+ * @param {string} newPath - New file path.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+export declare function moveFile(oldPath: string, newPath: string): Promise<boolean>;
+/**
+ * Gets file stats if the file exists.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<fs.Stats | null>} File stats object or null if file doesn't exist.
+ */
+export declare function getFileStats(path: string): Promise<Stats | null>;
+/**
+ * Creates a temporary file with optional content.
+ *
+ * @param {object} [options] - Options for creating the temp file.
+ * @param {string} [options.prefix="tmp-"] - Filename prefix.
+ * @param {string} [options.extension=""] - File extension.
+ * @param {string} [options.dir] - Directory to create the file in (defaults to OS temp dir).
+ * @param {string | Buffer} [options.content] - Optional content to write to the file.
+ * @returns {Promise<string>} Path to the created temporary file.
+ */
+export declare function createTempFile({ prefix, extension, dir, content }?: {
+    prefix?: string;
+    extension?: string;
+    dir?: string;
+    content?: string | Buffer;
+}): Promise<string>;
+/**
+ * Streams a file from source to destination.
+ * Useful for large files to avoid loading the entire file into memory.
+ *
+ * @param {string} source - Source file path.
+ * @param {string} destination - Destination file path.
+ * @returns {Promise<void>} Resolves when streaming completes.
+ * @throws {Error} If streaming fails.
+ */
+export declare function streamFile(source: string, destination: string): Promise<void>;
+/**
+ * Reads a directory and returns file names.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @param {object} [options] - Options for reading the directory.
+ * @param {boolean} [options.fullPaths=false] - Whether to return full paths.
+ * @param {RegExp} [options.filter] - Optional regex to filter files.
+ * @returns {Promise<string[]>} Array of file names or paths.
+ * @throws {Error} If directory cannot be read.
+ */
+export declare function readDirectory(dirPath: string, options?: {
+    fullPaths?: boolean;
+    filter?: RegExp;
+}): Promise<string[]>;
+/**
+ * Creates a directory if it doesn't exist.
+ *
+ * @param {string} dirPath - Path to the directory.
+ * @param {boolean} [recursive=true] - Whether to create parent directories.
+ * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
+ */
+export declare function createDirectory(dirPath: string, recursive?: boolean): Promise<boolean>;
+/**
+ * Safely reads and parses a JSON file with error details.
+ *
+ * @typeParam T - The expected type of the parsed JSON object.
+ * @param {string} path - The path to the JSON file.
+ * @returns {Promise<{ data: T | null; error: Error | null }>} Object with data and error properties.
+ */
+export declare function safeReadJsonFile<T = any>(path: string): Promise<{
+    data: T | null;
+    error: Error | null;
+}>;
+/**
+ * Checks if a path points to a file (not a directory).
+ *
+ * @param {string} path - Path to check.
+ * @returns {Promise<boolean>} True if the path is a file, false otherwise.
+ */
+export declare function isFile(path: string): Promise<boolean>;
+/**
+ * Gets the size of a file in bytes.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<number>} Size in bytes or -1 if file doesn't exist.
+ */
+export declare function getFileSize(path: string): Promise<number>;
+/**
+ * Reads a file as a Buffer.
+ *
+ * @param {string} path - Path to the file.
+ * @returns {Promise<Buffer | null>} File contents as Buffer or null if reading fails.
+ */
+export declare function readFileBuffer(path: string): Promise<Buffer | null>;
+//# sourceMappingURL=fs.utils.d.ts.map