rrdir

rrdir recursively reads a directory and returns entries within via an async iterator or async/sync as Array. It can typically iterate millions of files in a matter of seconds. The async iterator holds only one directory level in memory at a time, the Array variants hold all entries.

This module is able to read any path including ones that contain invalid UTF-8 sequences.

Benchmark	rrdir	fdir
async	60ms	59ms
sync	153ms	167ms
async + glob	57ms	56ms
sync + glob	169ms	185ms
async + exclude	37ms	37ms
sync + exclude	114ms	107ms
async iterator	78ms	—

Results for 122K entries (111K files, 11K dirs), Node.js on macOS. rrdir returns richer entries (path + directory + symlink) while fdir returns only paths. fdir uses picomatch for glob matching, rrdir has a built-in glob matcher. Run with make bench.

Usage

npm i rrdir

import {rrdir, rrdirAsync, rrdirSync} from "rrdir";

for await (const entry of rrdir("dir")) {
  // => {path: 'dir/file', directory: false, symlink: false}
}

const entries = await rrdirAsync("dir");
// => [{path: 'dir/file', directory: false, symlink: false}]

const entries = rrdirSync("dir");
// => [{path: 'dir/file', directory: false, symlink: false}]

API

rrdir(dir, [options])

rrdirAsync(dir, [options])

rrdirSync(dir, [options])

rrdir is an async iterator which yields entry. rrdirAsync and rrdirSync return an Array of entry.

dir String | Uint8Array

The directory to read, either absolute or relative. Pass a Uint8Array to switch the module into Uint8Array mode which is required to be able to read every file, like for example files with names that are invalid UTF-8 sequences.

options Object

• stats boolean: Whether to include entry.stats. Will reduce performance. Default: false.
• followSymlinks boolean: Whether to follow symlinks for both recursion and stat calls. Default: false.
• exclude Array: Path globs to exclude, e.g. ["**.js"]. Excluding a directory prunes its subtree. Default: undefined.
• include Array: Path globs to include, e.g. ["**.map"]. Default: undefined.

include and exclude support * (any characters except /), ** (any characters) and ? (one character except /). Character classes and brace expansion are not supported.

• strict boolean: Whether to throw immediately when reading an entry fails. Default: false.
• insensitive boolean: Whether include and exclude match case-insensitively. Default: false.

entry Object

• path string | Uint8Array: The path to the entry, will be relative if dir is given relative. If dir is a Uint8Array, this will be too. Always present.
• directory boolean: Boolean indicating whether the entry is a directory. undefined on error.
• symlink boolean: Boolean indicating whether the entry is a symbolic link. undefined on error.
• stats Object: A fs.stats object, present when options.stats is set. undefined on error.
• err Error: Any error encountered while reading this entry. undefined on success.

© silverwind, distributed under BSD licence