@catbee/utils/build/esm/utils/dir.utils.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.

import fs from "fs";
/**
 * Ensures that a directory exists, creating parent directories if needed (like `mkdir -p`).
 *
 * @param {string} dirPath - The directory path to ensure.
 * @returns {Promise<void>} Resolves when the directory exists.
 * @throws {Error} If directory cannot be created.
 */
export declare function ensureDir(dirPath: string): Promise<void>;
/**
 * Recursively lists all files in a directory.
 *
 * @param {string} dirPath - The base directory.
 * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
 * @returns {Promise<string[]>} Array of absolute file paths.
 * @throws {Error} If the directory cannot be read.
 */
export declare function listFiles(dirPath: string, recursive?: boolean): Promise<string[]>;
/**
 * Deletes a directory and all its contents recursively (like `rm -rf`).
 *
 * @param {string} dirPath - Directory to delete.
 * @returns {Promise<void>} Resolves when deletion is complete.
 * @throws {Error} If deletion fails.
 */
export declare function deleteDirRecursive(dirPath: string): Promise<void>;
/**
 * Checks whether a given path is a directory.
 *
 * @param {string} pathStr - Path to check.
 * @returns {Promise<boolean>} True if the path is a directory, else false.
 */
export declare function isDirectory(pathStr: string): Promise<boolean>;
/**
 * Recursively copies a directory and all its contents to a destination.
 *
 * @param {string} src - Source directory path.
 * @param {string} dest - Destination directory path.
 * @returns {Promise<void>} Resolves when copy is complete.
 * @throws {Error} If source does not exist or copy fails.
 */
export declare function copyDir(src: string, dest: string): Promise<void>;
/**
 * Moves a directory to a new location by copying and deleting the original.
 *
 * @param {string} src - Source directory path.
 * @param {string} dest - Destination directory path.
 * @returns {Promise<void>} Resolves when move is complete.
 * @throws {Error} If copy or deletion fails.
 */
export declare function moveDir(src: string, dest: string): Promise<void>;
/**
 * Empties a directory by deleting all files and subdirectories inside it.
 *
 * @param {string} dirPath - Path to the directory to empty.
 * @returns {Promise<void>} Resolves when the directory has been emptied.
 * @throws {Error} If files or subdirectories cannot be removed.
 */
export declare function emptyDir(dirPath: string): Promise<void>;
/**
 * Calculates the total size (in bytes) of all files in a directory (recursive).
 *
 * @param {string} dirPath - Path to the directory.
 * @returns {Promise<number>} Total size in bytes.
 * @throws {Error} If any file stats cannot be read.
 */
export declare function getDirSize(dirPath: string): Promise<number>;
/**
 * Watches a directory for file changes and calls a callback on each event.
 *
 * @param {string} dirPath - Directory path to watch.
 * @param {(eventType: "rename" | "change", filename: string | null) => void} callback - Callback for each change event.
 * @returns {() => void} A function to stop watching the directory.
 */
export declare function watchDir(dirPath: string, callback: (eventType: "rename" | "change", filename: string | null) => void): () => void;
/**
 * Finds files matching a glob pattern.
 *
 * @param {string} pattern - Glob pattern to match files.
 * @param {object} [options] - Options for glob pattern matching.
 * @param {string} [options.cwd] - Current working directory for relative patterns.
 * @param {boolean} [options.dot=false] - Include dotfiles in matches.
 * @param {boolean} [options.nodir=true] - Only match files, not directories.
 * @returns {Promise<string[]>} Array of matched file paths.
 * @throws {Error} If pattern matching fails.
 */
export declare function findFilesByPattern(pattern: string, options?: {
    cwd?: string;
    dot?: boolean;
    nodir?: boolean;
}): Promise<string[]>;
/**
 * Gets all subdirectories in a directory.
 *
 * @param {string} dirPath - The directory to search in.
 * @param {boolean} [recursive=false] - Whether to include subdirectories recursively.
 * @returns {Promise<string[]>} Array of absolute subdirectory paths.
 * @throws {Error} If directory cannot be read.
 */
export declare function getSubdirectories(dirPath: string, recursive?: boolean): Promise<string[]>;
/**
 * Ensures a directory exists and is empty.
 *
 * @param {string} dirPath - Path to the directory.
 * @returns {Promise<void>} Resolves when the directory exists and is empty.
 * @throws {Error} If directory cannot be created or emptied.
 */
export declare function ensureEmptyDir(dirPath: string): Promise<void>;
/**
 * Creates a temporary directory with optional auto-cleanup.
 *
 * @param {object} [options] - Options for the temporary directory.
 * @param {string} [options.prefix='tmp-'] - Prefix for the directory name.
 * @param {string} [options.parentDir=os.tmpdir()] - Parent directory.
 * @param {boolean} [options.cleanup=false] - Whether to register cleanup on process exit.
 * @returns {Promise<{ path: string, cleanup: () => Promise<void> }>} Object with directory path and cleanup function.
 * @throws {Error} If directory cannot be created.
 */
export declare function createTempDir(options?: {
    prefix?: string;
    parentDir?: string;
    cleanup?: boolean;
}): Promise<{
    path: string;
    cleanup: () => Promise<void>;
}>;
/**
 * Finds the newest file in a directory.
 *
 * @param {string} dirPath - Directory to search.
 * @param {boolean} [recursive=false] - Whether to search subdirectories.
 * @returns {Promise<string | null>} Path to the newest file or null if no files.
 * @throws {Error} If directory cannot be read.
 */
export declare function findNewestFile(dirPath: string, recursive?: boolean): Promise<string | null>;
/**
 * Finds the oldest file in a directory.
 *
 * @param {string} dirPath - Directory to search.
 * @param {boolean} [recursive=false] - Whether to search subdirectories.
 * @returns {Promise<string | null>} Path to the oldest file or null if no files.
 * @throws {Error} If directory cannot be read.
 */
export declare function findOldestFile(dirPath: string, recursive?: boolean): Promise<string | null>;
/**
 * Finds files or directories in a directory matching a predicate function.
 *
 * @param {string} dirPath - Directory to search.
 * @param {(path: string, stat: fs.Stats) => boolean | Promise<boolean>} predicate - Function to test each path.
 * @param {boolean} [recursive=false] - Whether to search subdirectories.
 * @returns {Promise<string[]>} Array of matching paths.
 * @throws {Error} If directory cannot be read.
 */
export declare function findInDir(dirPath: string, predicate: (path: string, stat: fs.Stats) => boolean | Promise<boolean>, recursive?: boolean): Promise<string[]>;
/**
 * Watches a directory recursively for file changes.
 *
 * @param {string} dirPath - Base directory path to watch.
 * @param {(eventType: "rename" | "change", filename: string) => void} callback - Callback for each change event.
 * @param {boolean} [includeSubdirs=true] - Whether to watch subdirectories.
 * @returns {Promise<() => void>} A function to stop watching the directory.
 * @throws {Error} If directory cannot be watched.
 */
export declare function watchDirRecursive(dirPath: string, callback: (eventType: "rename" | "change", filename: string) => void, includeSubdirs?: boolean): Promise<() => void>;
/**
 * Gets detailed directory statistics including file count, directory count, and size.
 *
 * @param {string} dirPath - Path to the directory.
 * @returns {Promise<{ fileCount: number, dirCount: number, totalSize: number }>} Directory statistics.
 * @throws {Error} If directory cannot be read.
 */
export declare function getDirStats(dirPath: string): Promise<{
    fileCount: number;
    dirCount: number;
    totalSize: number;
}>;
/**
 * Walks through a directory hierarchy, calling a visitor function for each entry.
 *
 * @param {string} dirPath - Starting directory path.
 * @param {object} options - Options for walking the directory.
 * @param {(entry: { path: string, name: string, isDirectory: boolean, stats: fs.Stats }) => boolean | void | Promise<boolean | void>} options.visitorFn -
 *   Function called for each file/directory. Return false to skip a directory.
 * @param {'pre' | 'post'} [options.traversalOrder='pre'] - Whether to visit directories before or after their contents.
 * @throws {Error} If directory cannot be read.
 */
export declare function walkDir(dirPath: string, options: {
    visitorFn: (entry: {
        path: string;
        name: string;
        isDirectory: boolean;
        stats: fs.Stats;
    }) => boolean | void | Promise<boolean | void>;
    traversalOrder?: "pre" | "post";
}): Promise<void>;
//# sourceMappingURL=dir.utils.d.ts.map