hbh-fs

A lightweight, modern Node.js filesystem utility package providing a set of convenient functions for working with files and directories. Includes recursive operations, JSON helpers, and flexible directory listings.

---

Installation

          
            1npm install hbh-fs
          
        

or using Yarn:

          
            1yarn add hbh-fs
          
        

---

Importing

          
            1// ES Modules2import { FSHelper } from 'hbh-fs';4// CommonJS5const { FSHelper } = require('hbh-fs');
          
        

---

API Overview

1. Directory Operations

FSHelper.createFolder(folderPath)

Creates a folder (including parent directories if needed).

          
            1await FSHelper.createFolder('./myFolder');
          
        

Returns:

          
            1{ success: boolean, message: string, path: string }
          
        

---

FSHelper.deleteFolder(folderPath)

Deletes a folder recursively.

          
            1await FSHelper.deleteFolder('./myFolder');
          
        

Returns:

          
            1{ success: boolean, message: string, path: string }
          
        

---

FSHelper.moveFolder(oldPath, newPath)

Moves or renames a folder.

          
            1await FSHelper.moveFolder('./oldFolder', './newFolder');
          
        

Returns:

          
            1{ success: boolean, message: string, from: string, to: string }
          
        

---

FSHelper.deleteEmptyDirs(dir, options)

Recursively deletes empty directories.

Options:

• verbose (boolean) – log actions
• dryRun (boolean) – simulate deletions
• maxDepth (number) – maximum recursion depth
• exclude (string[]) – directory names to skip
• excludeRegex (RegExp[]) – regex patterns to skip

          
            1await FSHelper.deleteEmptyDirs('.', { dryRun: true, verbose: true });
          
        

---

2. Path & Existence Checks

• FSHelper.pathExists(path) – returns true if a path exists.
• FSHelper.fileExists(filePath) – structured response if file exists.
• FSHelper.folderExists(folderPath) – structured response if folder exists.
• FSHelper.isExist – alias for folderExists.

---

3. JSON Utilities

FSHelper.writeJSON(filePath, data)

Writes a JavaScript object to a JSON file.

          
            1await FSHelper.writeJSON('./data.json', { hello: 'world' });
          
        

FSHelper.readJSON(filePath)

Reads a JSON file into a JavaScript object.

          
            1const result = await FSHelper.readJSON('./data.json');2console.log(result.data);
          
        

Returns:

          
            1{ success: boolean, message: string, data?: any, path: string }
          
        

---

4. Directory Listing & Walkers

FSHelper.List.flat(dir, baseDir)

Recursively lists files and directories in a flat structure.

          
            1const files = await FSHelper.List.flat('.', '.');
          
        

Output:

          
            1[{ type: 'file'|'directory', name: 'relative/path', size?: number }]
          
        

---

FSHelper.List.tree(dir)

Recursively lists files and directories as a tree structure.

          
            1const tree = await FSHelper.List.tree('.');
          
        

Output:

          
            1{2  folder1: { file1: 'file', subfolder: { file2: 'file' } },3  file3: 'file'4}
          
        

---

FSHelper.List.directories(dir)

Lists immediate directory contents (non-recursive).

          
            1const dirs = await FSHelper.List.directories('.');
          
        

Output:

          
            1[{ name: 'folder1', type: 'directory' }, { name: 'file.txt', type: 'file' }]
          
        

---

5. Exclusion Utilities

• FSHelper.exclude.add(matcher) – add a string, regex, or function to globally exclude files/folders.
• FSHelper.exclude.should(name) – checks if a file/folder should be excluded.

          
            1FSHelper.exclude.add(/^_/); // exclude all names starting with "_"
          
        

---

6. Utility Functions

• FSHelper.getDirectories(dirPath, options) – returns a list of directories, with optional filtering and sorting.
• Flexible filtering using regex, strings, or custom functions.

---

7. Text Replacement Utility

Recursively replaces multiple patterns in all files within a directory.

Parameters:

Example Usage:

          
            1import { FSHelper } from 'hbh-fs';3(async () => {4  // Replace text in all files recursively5  await FSHelper.replaceInFiles('./myFolder', [6    { value: 'World', replaced: 'Universe' },7    { value: 'hello', replaced: 'hi' }8  ]);10  console.log('✅ Text replacement complete!');11})();
          
        

Behavior:

1. Traverses all subdirectories recursively.
2. Reads each file as UTF-8 text.
3. Replaces all occurrences of value with replaced.
4. Writes the updated content back to the file.

---

Example Usage

          
            1import { FSHelper } from 'hbh-fs';3(async () => {4  // Create a folder5  console.log(await FSHelper.createFolder('./myFolder'));7  // Write JSON8  await FSHelper.writeJSON('./myFolder/data.json', { hello: 'world' });10  // List files recursively11  const files = await FSHelper.List.flat('./myFolder', './myFolder');12  console.log(files);14  // Delete empty folders (dry run)15  await FSHelper.deleteEmptyDirs('./myFolder', { dryRun: true, verbose: true });16})();
          
        

---

Features

• Modern async/await API using fs/promises.
• Recursive directory deletion and traversal.
• Flexible JSON read/write helpers.
• Exclusion system (string, regex, function).
• Simple, flat, and tree directory listings.
• Fully type-safe responses for existence checks and operations.

---

License

ISC – Free for personal and commercial use.