@catbee/utils/directory/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 fs from 'node: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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
declare function watchDir(dirPath: string, callback: (eventType: 'rename' | 'change', filename: string | null) => void): () => void;
/**
 * Recursively finds files matching a simple pattern (supports '*' and '?').
 *
 * @param {string} pattern - Simple pattern to match files (e.g., '*.ts', 'src/*.js').
 * @param {object} [options] - Options for matching files.
 * @param {string} [options.cwd=process.cwd()] - Base directory to start searching from.
 * @param {boolean} [options.dot=false] - Include dotfiles in matches.
 * @returns {Promise<string[]>} Array of matched file paths.
 */
declare function findFilesByPattern(pattern: string, options?: {
    cwd?: string;
    dot?: 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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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.
 */
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>;

export { copyDir, createTempDir, deleteDirRecursive, emptyDir, ensureDir, ensureEmptyDir, findFilesByPattern, findInDir, findNewestFile, findOldestFile, getDirSize, getDirStats, getSubdirectories, isDirectory, listFiles, moveDir, walkDir, watchDir, watchDirRecursive };