https://github.com/igorskyflyer/npm-recursive-readdir

📖 Fast, type-safe recursive directory reader for Node.js with depth control, entry filtering, and sync/async APIs. 📁
https://github.com/igorskyflyer/npm-recursive-readdir

back-end directory filesystem igorskyflyer javascript node nodejs readdir recursive traversal

Last synced: about 1 month ago
JSON representation

📖 Fast, type-safe recursive directory reader for Node.js with depth control, entry filtering, and sync/async APIs. 📁

Host: GitHub
URL: https://github.com/igorskyflyer/npm-recursive-readdir
Owner: igorskyflyer
License: mit
Created: 2021-06-28T19:36:05.000Z (almost 5 years ago)
Default Branch: main
Last Pushed: 2025-09-22T19:50:09.000Z (9 months ago)
Last Synced: 2025-10-22T08:30:12.138Z (8 months ago)
Topics: back-end, directory, filesystem, igorskyflyer, javascript, node, nodejs, readdir, recursive, traversal
Language: TypeScript
Homepage: https://www.npmjs.com/package/@igorskyflyer/recursive-readdir
Size: 313 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Support: SUPPORT.md

Awesome Lists containing this project

README

          


  

  Recursive ReadDir





  Recursive Directory Reading • Sync And Async Usage • Flexible Filters • Depth Control





  📖 Fast, type-safe recursive directory reader for Node.js with depth control, entry filtering, and sync/async APIs. 📁









## 📃 Table of Contents

- [**Features**](#-features)

- [**Motivation**](#-features)

- [**Usage**](#-usage)

- [**API**](#-api)

  - [**Function-based**](#λ-function-based)

  - [**Class-based**](#-class-based)

- [**Examples**](#️-examples)

- [**Changelog**](#-changelog)

- [**Support**](#-support)

- [**License**](#-license)

- [**Related**](#-related)

- [**Author**](#-author)







## 🤖 Features

- 📂 Reads directories recursively with precise depth control

- 🎯 Filters results by files-only, directories-only, or all entries

- ⚡ Supports both synchronous and asynchronous operations

- 🧩 Accepts custom filter functions for advanced selection

- ✨ Optionally adds trailing slashes to directory paths

- 🛡️ Skips unreadable entries without stopping traversal

- 🏗 Provides a fluent class API for easy configuration

- 💻 Cross-platform paths, powered by [**uPath**](https://www.npmjs.com/package/@igorskyflyer/upath)




## 🎯 Motivation

This npm module was built to provide a reliable and efficient way of listing directories while another project was being developed - a Visual Studio Code extension called [**New Folder**](https://github.com/igorskyflyer/vscode-new-folder), where a custom QuickPick dialog was required to allow the selection of a root directory.




## 🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

```bash

pnpm add @igorskyflyer/recursive-readdir

```

```bash

yarn add @igorskyflyer/recursive-readdir

```

```bash

npm i @igorskyflyer/recursive-readdir

```







## 🤹🏼 API

### λ Function-based

```ts

async function readDir(directory: string, options: RecursiveDirOptions): Promise

```

Asynchronously gets files/directories inside the given directory.




**Params**

_**directory**_: `string` - the directory whose files/directories should be listed,

_**options**_: `RecursiveDirOptions` - additional options.




```ts

 function readDirSync(directory: string, options: RecursiveDirOptions): 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.




```ts

class RecursiveDir

```




**Available methods**

```ts

function readDirSync(directory: string): string[]

```

Synchronously gets files/directories inside the given directory.




**Params**

_**directory**_: `string` - the directory whose files/directories should be listed.




```ts

function readDir(directory: string): Promise

```

Asynchronously gets files/directories inside the given directory.




**Params**

_**directory**_: `string` - the directory whose files/directories should be listed.




```ts

function entries(value: Entry): 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`**.




```ts

function maxDepth(value: Depth): 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.




> ### ℹ️ NOTE

>

> #### Why the default value of `maxDepth` is **_NOT_** `Depth.All`?

>

> It is simple: the value must be explicitly set, since traversal through all child subdirectories is highly resource‑ and time‑consuming. For example, if the directory parameter were set to the root of a drive in combination with `maxDepth = Depth.All`, the operation could become extremely heavy.

>




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`

```ts

maxDepth(Depth.Root)

// return only the files/directories in the current directory

```




`maxDepth = 3`

```ts

maxDepth(3)

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

```




`maxDepth = Depth.All`

```ts

maxDepth(Depth.All)

// return all child files/directories in the current directory

```







```ts

function filter(value: FilterCallback): RecursiveDir

```

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




**Params**

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







```ts

function addTrailingSlash(value: boolean): 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

```ts

import { readDirSync, Depth, Entry, RecursiveDir } from '@igorskyflyer/recursive-readdir'

const testingPath: string = './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: RecursiveDir = 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

```







## 📝 Changelog

📑 Read about the latest changes in the [**CHANGELOG.md**](https://github.com/igorskyflyer/npm-recursive-readdir/blob/main/CHANGELOG.md).







## 🪪 License

Licensed under the [**MIT license**](https://github.com/igorskyflyer/npm-recursive-readdir/blob/main/LICENSE).







## 💖 Support



  I work hard for every project, including this one and your support means a lot to me!

  


  Consider buying me a coffee. ☕

  


  


  

  


  


  Thank you for supporting my efforts! 🙏😊









## 🧬 Related

[**@igorskyflyer/unc-path**](https://www.npmjs.com/package/@igorskyflyer/unc-path)

> _🥽 Provides ways of parsing UNC paths and checking whether they are valid. 🎱_




[**@igorskyflyer/comment-it**](https://www.npmjs.com/package/@igorskyflyer/comment-it)

> _📜 Formats the provided string as a comment, either a single or a multi line comment for the given programming language. 💻_




[**@igorskyflyer/strip-html**](https://www.npmjs.com/package/@igorskyflyer/strip-html)

> _🥞 Removes HTML code from the given string. Can even extract text-only from the given an HTML string. ✨_




[**@igorskyflyer/upath**](https://www.npmjs.com/package/@igorskyflyer/upath)

> _🎍 Provides a universal way of formatting file-paths in Unix-like and Windows operating systems as an alternative to the built-in path.normalize(). 🧬_




[**@igorskyflyer/valid-path**](https://www.npmjs.com/package/@igorskyflyer/valid-path)

> _🧰 Determines whether a given value can be a valid file/directory name. 🏜_




## 👨🏻‍💻 Author

Created by **Igor Dimitrijević** ([*@igorskyflyer*](https://github.com/igorskyflyer/)).

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/igorskyflyer/npm-recursive-readdir

Awesome Lists containing this project

README

Recursive ReadDir

📖 Fast, type-safe recursive directory reader for Node.js with depth control, entry filtering, and sync/async APIs. 📁