README.md

🔁 Recursive readdir()

📖 Provides advanced recursive readdir() and readdirSync() functions with high-level of Node-compatibility and much more. 📁

❓ Did you know? 🤔

I've built this npm module because I needed a reliable and efficient npm module for listing directories while building another one of my projects, a Visual Studio Code extension called New Folder and I needed to create a custom QuickPick dialog allowing the user to pick a root directory.

✨ Since v.2.0.0 recursive-readdir is a hybrid module that supports both CommonJS (legacy) and ES modules, thanks to Modern Module.

Features

✅ both class-based and function-based approaches available,

✅ TypeScript ready, declaration files (d.ts) included,

✅ recursive traversal,

✅ maximum depth of traversal configurability,

✅ file-only filtering,

✅ directory-only filtering,

✅ file/directory path name filtering,

✅ error detection methods,

✅ file/directory inaccessibility detection methods,

✅ multiple output formats,

✅ directories optional trailing slash,

✅ custom filter function,

✅ async and sync methods available,

✅ path-safety, see uPath,

✅ universal paths supported, see uPath. 🎉

Usage

Install it by running:

npm i "@igor.dvlpr/recursive-readdir"

API

• function-based,
• class-based

λ Function-based

async function readDir(directory, options): Promise<string[]>

Asynchronously gets files/directories inside the given directory.

Params

directory: String - the directory whose files/directories should be listed,

options: RecursiveDirOptions - additional options.

 function readDirSync(directory, options): string[]

Synchronously gets files/directories inside the given directory.

Params

directory: String - the directory whose files/directories should be listed,

options: RecursiveDirOptions - additional options.

💎 Class-based

For own convenience and code-reuse you can use the class-based approach.

Define the options once and (re)call the readDirSync()/readDir() when needed.

class RecursiveDir

Available methods

function readDirSync(directory): string[]

Synchronously gets files/directories inside the given directory.

Params

directory: String - the directory whose files/directories should be listed.

function readDir(directory): Promise<string[]>

Asynchronously gets files/directories inside the given directory.

Params

directory: the directory whose files/directories should be listed.

function entries(value): RecursiveDir

Sets the entries property which controls whether to list files-only, directories-only or both (default).

Params value: Entry - a value with three possible values - provided as class consts,

• Entry.All,
• Entry.FilesOnly,
• Entry.DirectoriesOnly.

function maxDepth(value): RecursiveDir

Sets maxDepth which controls how many child directories' entries are being listed.

Params

value: Depth - the new maxDepth value.

You can use the 2 predefined values or use an arbitrary value. The predefined values are as follows:

• Depth.All = -1 - return all subdirectories entries,
• Depth.Root = 0 (default) - return only root directory's entries.

🤔 Why the default value of maxDepth is NOT Depth.All when this module provides recursive and subdirectory file traversal?

⚡ Simple, because you need to explicitly set it to that value because traversal through all child subdirectories is very resource/time consuming, just imagine setting the directory parameter to the root of your drive and in conjunction with maxDepth = Depth.All. 😲

To use arbitrary values the provided value parameter must comply with the expression

maxDepth >= Depth.Root

i.e.,

maxDepth >= 0

The value of 0 means that only directory entries found in the directory specified when calling either readDir() or readDirSync() methods are returned. By increasing the number we can set the depth/level of subdirectories that the method should return, e.g.

maxDepth = Depth.Root

maxDepth(Depth.Root)
// return only the files/directories in the current directory

maxDepth = 3

maxDepth(3)
// return the files/directories in the current director files/directories 3-levels deep

maxDepth = Depth.All

maxDepth(Depth.All)
// return all child files/directories in the current directory

function filter(value): RecursiveDir

Sets filter predicate function used for filtering directory entries (directories/files).

Params

value: FilterCallback - the filter function to use when filtering directory entries.

function addTrailingSlash(value): RecursiveDir

Sets whether a trailing slash should be added to directory entries.

Params

value: boolean - a Boolean indicating whether a trailing slash should be added to directory entries.

Examples

const { readDirSync, Depth, Entry, RecursiveDir } = require('@igor.dvlpr/recursive-readdir')
const testingPath = './somePath'

// Function-based approach

console.log(readDirSync('non-existent-directory')) // returns []

console.log(
  readDirSync(testingPath, {
    maxDepth: Depth.All,
    filter: (entry) => entry.isDirectory,
  })
) // returns only subdirectories (all subdirectories)

// the following can be used interchangeably
console.log(
  readDirSync(testingPath, {
    maxDepth: Depth.All,
    entries: Entry.DirectoriesOnly,
  })
) // returns only subdirectories (all subdirectories)

console.log(
  readDirSync(testingPath, {
    maxDepth: Depth.All,
    entries: Entry.FilesOnly,
    filter: (entry) => entry.path.indexOf('.js') > -1,
  })
) // returns only JavaScript - .js files found in all (sub)directories

// Class-based approach

const dir = new RecursiveDir()

dir
  .maxDepth(Depth.All)
  .entries(Entry.FilesOnly)
  .filter((entry) => entry.path.indexOf('.md') > -1)

console.log(dir.readDirSync(testingPath)) // returns only .md (Markdown) files found in all (sub)directories