@catbee/utils/fs/index.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/*
 * The MIT License
 * 
 * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

import { BufferEncoding } from '@catbee/utils/crypto';
import fs from 'node: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.
 */
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.
 */
declare function readJsonFile<T = any>(path: string): Promise<T | null>;
/**
 * Read and parse JSON file or return a provided default value on error.
 *
 * @typeParam T
 * @param {string} path - Path to JSON file
 * @param {T} defaultValue - Default value to return when read/parse fails
 * @returns {Promise<T>} Parsed JSON or defaultValue
 */
declare function readJsonOrDefault<T = any>(path: string, defaultValue: T): Promise<T>;
/**
 * 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.
 */
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.
 */
declare function deleteFileIfExists(path: string): Promise<boolean>;
/**
 * Reads a file from the specified path.
 *
 * @param {string} path - The path to the file.
 * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
 * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
 */
declare function readFile(path: string, encoding?: BufferEncoding): Promise<string>;
/**
 * Reads a file from the specified path synchronously.
 *
 * @param {string} path - The path to the file.
 * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
 * @returns {string | null} The file contents, or `null` if reading fails.
 */
declare function readFileSync(path: string, encoding?: BufferEncoding): string;
/**
 * Safely reads a file and returns its content along with any error encountered.
 *
 * @param {string} path - The path to the file.
 * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
 * @returns {Promise<{ data: string | null; error: Error | null }>} Object with data and error properties.
 */
declare function safeReadFile(path: string, encoding?: BufferEncoding): Promise<{
    data: string | null;
    error: Error | null;
}>;
/**
 * Safely reads a file synchronously and returns its content along with any error encountered.
 *
 * @param {string} path - The path to the file.
 * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
 * @returns {{ data: string | null; error: Error | null }} Object with data and error properties.
 */
declare function safeReadFileSync(path: string, encoding?: BufferEncoding): {
    data: string | null;
    error: Error | null;
};
/**
 * Writes 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.
 */
declare function writeFile(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.
 */
declare function appendFile(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.
 */
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.
 */
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<fsp.Stats | null>} File stats object or null if file doesn't exist.
 */
declare function getFileStats(path: string): Promise<fs.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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
declare function readFileBuffer(path: string): Promise<Buffer | null>;

export { appendFile, copyFile, createDirectory, createTempFile, deleteFileIfExists, fileExists, getFileSize, getFileStats, isFile, moveFile, readDirectory, readFile, readFileBuffer, readFileSync, readJsonFile, readJsonOrDefault, safeReadFile, safeReadFileSync, safeReadJsonFile, streamFile, writeFile, writeJsonFile };