scan-the-folder
Version:
Efficiently scans a folder to extract filenames, extensions, and full directory paths, supporting recursive traversal.
118 lines (95 loc) • 4.38 kB
Markdown
<html lang="en">
<body>
<h1><span class="section-icon">📁</span>scan-the-folder</h1>
<p>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.</p>
<hr />
<h2><span class="section-icon">✨</span>Features</h2>
<ul>
<li>Recursively scans directories and subdirectories</li>
<li>Extracts file name, extension, absolute directory, and relative full path</li>
<li>Supports ignoring specific folders and files, and whitelisting files</li>
<li>Usable as a CLI tool or as an importable module in your Node.js projects</li>
</ul>
<hr />
<h2><span class="section-icon">⬇️</span>Installation</h2>
<p><strong>Using npm (for import or CLI):</strong></p>
<pre><code>npm install -g scan-the-folder # global install for CLI usage
# or
npm install scan-the-folderlder # local install to use as a module
</code></pre>
<hr />
<h2><span class="section-icon">⚙️</span>Usage</h2>
<h3><span class="section-icon">💻</span>CLI Usage</h3>
<p>After global installation, run the following command in your terminal:</p>
<pre><code>scan-the-folderlder -f <directory></code></pre>
<p>Example:</p>
<pre><code>scan-the-folderlder -f ./my-folder</code></pre>
<p>This will output a list of files scanned in the given directory (implement your CLI output as desired).</p>
<p><em>CLI Options</em></p>
<section>
<h2>⚙️ CLI Parameters</h2>
<ul>
<li>
<b>-f</b>, <b>--folder</b> <span style="color: red;">(required)</span><br />
<p>Specifies the folder to scan. Only one folder can be provided.</p>
</li>
<li>
<b>-igD</b>, <b>--ignoreDirs</b><br />
<p>One or more directory names to ignore during the scan. Use this to exclude folders like <code>node_modules</code> or <code>.git</code>.</p>
</li>
<li>
<b>-w</b>, <b>--whitelistFiles</b><br />
<p>One or more file names or extensions to include exclusively. If specified, only these files will be processed.</p>
</li>
<li>
<b>-igF</b>, <b>--ignoreFiles</b><br />
<p>One or more file names to ignore during the scan.</p>
</li>
</ul>
</section>
<h3><span class="section-icon">📦</span>Importing as a Module</h3>
<p>You can also import and use <code>scan-the-folder</code> in your Node.js or TypeScript projects:</p>
<pre><code >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)
});
</code></pre>
<hr />
<h2><span class="section-icon">📝</span>API</h2>
<h3>getFilesWithHandlesRecursively(dir: string, options?: Options): FileInfo[]</h3>
<ul>
<li><strong>dir</strong> — The root directory to start scanning (string)</li>
<li><strong>options</strong> — Optional object with:
<ul>
<li><code>ignoreDirs: string[]</code> — Folder names to ignore</li>
<li><code>ignoreFiles: string[]</code> — File names to ignore</li>
<li><code>whitelistFiles: string[]</code> — File names to include (if set, only these are included)</li>
</ul>
</li>
</ul>
<p>Returns an array of <code>FileInfo</code> objects:</p>
<pre><code>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
}
</code></pre>
<hr />
<h2><span class="section-icon">📜</span>License</h2>
<p>MIT License © <a href="https://github.com/pSkywalker" target="_blank" rel="noopener noreferrer">pSkywalker</a></p>
<hr />
<h2><span class="section-icon">🤝</span>Contributions</h2>
<p>Contributions, issues, and feature requests are welcome!</p>
<hr />
<h2><span class="section-icon">📬</span>Contact</h2>
<p>Created by pSkywalker. Feel free to open an issue or submit a pull request.</p>
</body>
</html>