📁scan-the-folder

A Node.js utility to recursively maps all files in a folder, extracting each file's name, extension, full directory path, and providing file handles for convenient file access.

---

✨Features

• Recursively scans directories and subdirectories


• Extracts file name, extension, absolute directory, and relative full path


• Supports ignoring specific folders and files, and whitelisting files


• Usable as a CLI tool or as an importable module in your Node.js projects

---

⬇️Installation

Using npm (for import or CLI):

npm install -g scan-the-folder  # global install for CLI usage
or

npm install scan-the-folderlder     # local install to use as a module

---

⚙️Usage

💻CLI Usage

After global installation, run the following command in your terminal:

scan-the-folderlder -f <directory>

Example:

scan-the-folderlder -f ./my-folder

This will output a list of files scanned in the given directory (implement your CLI output as desired).

CLI Options

⚙️ CLI Parameters

• 
  -f, --folder (required)
  
  

  Specifies the folder to scan. Only one folder can be provided.

  
  


• 
  -igD, --ignoreDirs
  
  

  One or more directory names to ignore during the scan. Use this to exclude folders like node_modules or .git.

  
  


• 
  -w, --whitelistFiles
  
  

  One or more file names or extensions to include exclusively. If specified, only these files will be processed.

  
  


• 
  -igF, --ignoreFiles
  
  

  One or more file names to ignore during the scan.

  
  

📦Importing as a Module

You can also import and use scan-the-folder in your Node.js or TypeScript projects:

import { getFilesWithHandlesRecursively } from 'scan-the-folder';
const files = getFilesWithHandlesRecursively('./my-folder', {
  ignoreDirs: ['node_modules', '.git'],
  ignoreFiles: ['README.md'],
  whitelistFiles: ['index.ts', 'index.js'] // Only include these extensions
});
files.forEach(file => {
  console.log(Found file: ${file.fullPath} (${file.extension}));
  // Access the file content using file.handle (fs.ReadStream)
});

---

📝API

getFilesWithHandlesRecursively(dir: string, options?: Options): FileInfo[]

• dir — The root directory to start scanning (string)


• options — Optional object with:
  
  
  
  • ignoreDirs: string[] — Folder names to ignore
  
  
  • ignoreFiles: string[] — File names to ignore
  
  
  • whitelistFiles: string[] — File names to include (if set, only these are included)
  
  
  
  

Returns an array of FileInfo objects:

interface FileInfo {
  name: string;         // File name without extension
  extension: string;    // File extension (e.g., '.js')
  directory: string;    // Absolute directory path of the file
  fullPath: string;     // Relative file path from the input directory
}

---

📜License

MIT License © pSkywalker

---

🤝Contributions

Contributions, issues, and feature requests are welcome!

---

📬Contact

Created by pSkywalker. Feel free to open an issue or submit a pull request.