fs-readdir-recursive

fs-readdir-recursive provides a simple utility function for recursively reading directory contents in Node.js. It scans through a directory tree and returns an array of all file paths found, with support for custom filtering functions to exclude certain files (by default, it ignores hidden files starting with a dot).

Package Information

• Package Name: fs-readdir-recursive
• Package Type: npm
• Language: JavaScript
• Installation: npm install fs-readdir-recursive

Core Imports

const read = require('fs-readdir-recursive');

Basic Usage

const read = require('fs-readdir-recursive');

// Read all files in a directory (excluding dot files by default)
const files = read('./my-directory');
console.log(files);
// Output: ['file1.txt', 'subdir/file2.js', 'subdir/nested/file3.md']

// Read with custom filter
const files = read('./my-directory', function(name, index, dir) {
  return name[0] !== '.' && name !== 'node_modules';
});

Capabilities

Directory Reading

Recursively reads a directory and returns all file paths as an array.

/**
 * Recursively read a directory and return all file paths
 * @param {string} root - The root directory path to scan
 * @param {function} [filter] - Optional filter function to exclude files
 * @returns {string[]} Array of relative file paths from the root directory
 */
function read(root, filter);

Parameters:

• root (string): The root directory path to scan
• filter (function, optional): Filter function that receives three parameters:
  • name (string): The filename being processed
  • index (number): The index of the file in the directory listing
  • dir (string): The full directory path containing the file
  • Returns true to include the file, false to exclude it

Return Value:

Returns an array of strings representing relative file paths from the root directory. Paths use forward slashes as separators regardless of platform. Returns an empty array if the root directory doesn't exist.

Default Filter:

By default, the function uses a built-in filter that excludes files starting with a dot:

function noDotFiles(name) {
  return name[0] !== '.';
}

Usage Examples:

const read = require('fs-readdir-recursive');

// Basic usage - excludes dot files by default
const allFiles = read('./src');

// Custom filter to exclude specific directories and files
const jsFiles = read('./project', function(name, index, dir) {
  // Exclude dot files and node_modules directory
  return name[0] !== '.' && 
         name !== 'node_modules';
});

// Filter based on directory path
const srcFiles = read('./project', function(name, index, dir) {
  // Only include files not in test directories
  return !dir.includes('/test/') && !dir.includes('\\test\\');
});

// Returns empty array for non-existent directories
const empty = read('./does-not-exist');
console.log(empty); // []

Error Handling:

• Returns an empty array if the root directory doesn't exist
• Uses synchronous filesystem operations that may throw errors on permission issues
• Handles symlinks by following them (both file and directory symlinks)
• Gracefully handles broken symlinks by ignoring them

File Path Format:

• All returned paths are relative to the provided root directory
• Uses forward slashes (/) as path separators on all platforms
• Does not include the root directory name in the returned paths
• Example: if scanning /home/user/project, returns ['src/index.js', 'package.json'] not ['/home/user/project/src/index.js']