readdirp
Recursive version of fs.readdir. Exposes a stream API and a promise API.
For more examples, check out examples
directory.
API
const stream = readdirp(root[, options])
— Stream API
Reads given root recursively and returns a
stream
of entry infosOptionally can be used like
for await (const entry of stream)
with node.js 10+ (asyncIterator
).on('data', (entry) => {})
entry info for every file / dir.on('warn', (error) => {})
non-fatalError
that prevents a file / dir from being processed. Example: inaccessible to the user.on('error', (error) => {})
fatalError
which also ends the stream. Example: illegal options where passed.on('end')
— we are done. Called when all entries were found and no more will be emitted.on('close')
— stream is destroyed viastream.destroy()
. Could be useful if you want to manually abort even on a non fatal error. At that point the stream is no longerreadable
and no more entries, warning or errors are emittedTo learn more about streams, consult the very detailed nodejs streams documentation or the stream-handbook
const entries = await readdirp.promise(root[, options])
— Promise API. Returns a list of entry infos.
First argument is awalys root
, path in which to start reading and recursing into subdirectories.
options
fileFilter: ["*.js"]
: filter to include or exclude files. AFunction
, Glob string or Array of glob strings.Function: a function that takes an entry info as a parameter and returns true to include or false to exclude the entry
Glob string: a string (e.g.,
*.js
) which is matched using picomatch, so go there for more information. Globstars (**
) are not supported since specifying a recursive pattern for an already recursive function doesn't make sense. Negated globs (as explained in the minimatch documentation) are allowed, e.g.,!*.txt
matches everything but text files.Array of glob strings: either need to be all inclusive or all exclusive (negated) patterns otherwise an error is thrown.
['*.json', '*.js']
includes all JavaScript and Json files.['!.git', '!node_modules']
includes all directories except the '.git' and 'node_modules'.Directories that do not pass a filter will not be recursed into.
directoryFilter: ['!.git']
: filter to include/exclude directories found and to recurse into. Directories that do not pass a filter will not be recursed into.depth: 5
: depth at which to stop recursing even if more subdirectories are foundtype: 'files'
: determines if data events on the stream should be emitted for'files'
(default),'directories'
,'files_directories'
, or'all'
. Setting to'all'
will also include entries for other types of file descriptors like character devices, unix sockets and named pipes.alwaysStat: false
: always returnstats
property for every file. Default isfalse
, readdirp will returnDirent
entries. Setting it totrue
can double readdir execution time - use it only when you need filesize
,mtime
etc. Cannot be enabled on node <10.10.0.lstat: false
: include symlink entries in the stream along with files. Whentrue
,fs.lstat
would be used instead offs.stat
EntryInfo
EntryInfo
Has the following properties:
path: 'assets/javascripts/react.js'
: path to the file/directory (relative to given root)fullPath: '/Users/dev/projects/app/assets/javascripts/react.js'
: full path to the file/directory foundbasename: 'react.js'
: name of the file/directorydirent: fs.Dirent
: built-in dir entry object - only withalwaysStat: false
stats: fs.Stats
: built in stat object - only withalwaysStat: true
Changelog
3.5 (Oct 13, 2020) disallows recursive directory-based symlinks. Before, it could have entered infinite loop.
3.4 (Mar 19, 2020) adds support for directory-based symlinks.
3.3 (Dec 6, 2019) stabilizes RAM consumption and enables perf management with
highWaterMark
option. Fixes race conditions related tofor-await
looping.3.2 (Oct 14, 2019) improves performance by 250% and makes streams implementation more idiomatic.
3.1 (Jul 7, 2019) brings
bigint
support tostat
output on Windows. This is backwards-incompatible for some cases. Be careful. It you use it incorrectly, you'll see "TypeError: Cannot mix BigInt and other types, use explicit conversions".3.0 brings huge performance improvements and stream backpressure support.
Upgrading 2.x to 3.x:
Signature changed from
readdirp(options)
toreaddirp(root, options)
Replaced callback API with promise API.
Renamed
entryType
option totype
Renamed
entryType: 'both'
to'files_directories'
EntryInfo
Renamed
stat
tostats
Emitted only when
alwaysStat: true
dirent
is emitted instead ofstats
by default withalwaysStat: false
Renamed
name
tobasename
Removed
parentDir
andfullParentDir
properties
Supported node.js versions:
3.x: node 8+
2.x: node 0.6+
License
Copyright (c) 2012-2019 Thorsten Lorenz, Paul Miller (https://paulmillr.com)
MIT License, see LICENSE file.
Last updated