# readdir-glob

> Recursive fs.readdir with streaming API and glob filtering.

Latest version **3.0.0** (published 2026-02-23) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install readdir-glob
pnpm add readdir-glob
yarn add readdir-glob
bun add readdir-glob
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2026-02-23 |
| First published | 2020-07-22 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 71.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Yann Armelin |
| Maintainers | yqnn |
| Keywords | recursive, fs, stream, streams, readdir, filesystem, find, filter, glob |

## Links

- npm: https://www.npmjs.com/package/readdir-glob
- Repository: https://github.com/Yqnn/node-readdir-glob
- Issues: https://github.com/Yqnn/node-readdir-glob/issues
- Funding: https://github.com/sponsors/yqnn
- npm.io page: https://npm.io/package/readdir-glob

## Dependencies (1)

- [minimatch](https://npm.io/package/minimatch.md) ^10.2.2

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 3.0.0 (latest) — 2026-02-23
- 2.0.3 — 2026-02-23
- 2.0.2 — 2026-02-19
- 2.0.1 — 2024-10-28
- 2.0.0 — 2024-04-12
- 1.1.3 — 2023-04-05
- 1.1.2 — 2022-07-01
- 1.1.1 — 2020-10-06
- 1.1.0 — 2020-09-21
- 1.0.0 — 2020-07-22

## README

# Readdir-Glob
![Build Status](https://github.com/Yqnn/node-readdir-glob/actions/workflows/test.yml/badge.svg?branch=master) [![Coverage Status](https://coveralls.io/repos/github/Yqnn/node-readdir-glob/badge.svg?branch=master)](https://coveralls.io/github/Yqnn/node-readdir-glob?branch=master)

Recursive version of fs.readdir wih stream API and glob filtering.
Uses the `minimatch` library to do its matching.

Requirements:
- 1.x.x requires Node.js 10.0 or later.
- 2.x.x requires Node.js 14.0 or later.
- 3.x.x requires Node.js 18.0 or later.

## Performances

Compared to `glob`, `readdir-glob` is memory efficient: no matter the file system size, or the number of returned files, the memory usage is constant.

The CPU cost is proportional to the number of files in `root` folder, minus the number files in `options.skip` folders.

**Advice**: For better performances use `options.skip` to restrict the search as much as possible.

## Usage

Install with npm
```
npm i readdir-glob
```

```javascript
// CommonJS:
const readdirGlob = require('readdir-glob');
// ESM:
import readdirGlob from 'readdir-glob';

const globber = readdirGlob('.', {pattern: '**/*.js'});
globber.on('match', match => {
    // m.relative: relative path of the matched file
    // m.absolute: absolute path of the matched file
    // m.stat: stat of the matched file (only if stat:true option is used)
});
globber.on('error', err => {
    console.error('fatal error', err);
});
globber.on('end', (m) => {
    console.log('done');
});
```

## readdirGlob(root, [options])

* `root` `{String}` Path to be read recursively, *default*: `'.'`
* `options` `{Object}` Options, *default*: `{}`

Returns a EventEmitter reading given root recursively.

### Properties

* `options`: The options object passed in.
* `paused`: Boolean which is set to true when calling `pause()`.
* `aborted` Boolean which is set to true when calling `abort()`.  There is no way at this time to continue a glob search after aborting.

### Events

* `match`: Every time a match is found, this is emitted with the specific thing that matched.
* `end`: When the matching is finished, this is emitted with all the matches found. 
* `error`: Emitted when an unexpected error is encountered.

### Methods

* `pause()`: Temporarily stop the search
* `resume()`: Resume the search
* `abort()`: Stop the search forever

### Options

* `pattern`: Glob pattern or Array of Glob patterns to match the found files with. A file has to match at least one of the provided patterns to be returned.
* `ignore`: Glob pattern or Array of Glob patterns to exclude matches. If a file or a folder matches at least one of the provided patterns, it's not returned. It doesn't prevent files from folder content to be returned. Note: `ignore` patterns are *always* in `dot:true` mode.
* `skip`: Glob pattern or Array of Glob patterns to exclude folders. If a folder matches one of the provided patterns, it's not returned, and it's not explored: this prevents any of its children to be returned. Note: `skip` patterns are *always* in `dot:true` mode.
* `mark`: Add a `/` character to directory matches.
* `stat`: Set to true to stat *all* results.  This reduces performance.
* `silent`: When an unusual error is encountered when attempting to read a directory, a warning will be printed to stderr.  Set the `silent` option to true to suppress these warnings.
* `nodir`: Do not match directories, only files.
* `follow`: Follow symlinked directories. Note that requires to stat *all* results, and so reduces performance.

The following options apply only if `pattern` option is set, and are forwarded to `minimatch`:
* `dot`: Allow `pattern` to match filenames starting with a period, even if the pattern does not explicitly have a period in that spot.
* `noglobstar`: Disable `**` matching against multiple folder names.
* `nocase`: Perform a case-insensitive match.  Note: on case-insensitive filesystems, non-magic patterns will match by default, since `stat` and `readdir` will not raise errors.
* `matchBase`: Perform a basename-only match if the pattern does not  contain any slash characters.  That is, `*.js` would be treated as equivalent to `**/*.js`, matching all js files in all directories.


## References

Unit-test set is based on [node-glob](https://www.npmjs.com/package/glob) tests.

---
_Source: https://npm.io/package/readdir-glob · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._