A library for efficiently walking a directory recursively.
name
, path
, dirent
and stats
(optional).old
and modern
mode.npm install @nodelib/fs.walk
import * as fsWalk from '@nodelib/fs.walk';
fsWalk.walk('path', (error, entries) => { /* … */ });
Reads the directory recursively and asynchronously. Requires a callback function.
If you want to use the Promise API, use
util.promisify
.
fsWalk.walk('path', (error, entries) => { /* … */ });
fsWalk.walk('path', {}, (error, entries) => { /* … */ });
fsWalk.walk('path', new fsWalk.Settings(), (error, entries) => { /* … */ });
Reads the directory recursively and asynchronously. Readable Stream is used as a provider.
const stream = fsWalk.walkStream('path');
const stream = fsWalk.walkStream('path', {});
const stream = fsWalk.walkStream('path', new fsWalk.Settings());
Reads the directory recursively and synchronously. Returns an array of entries.
const entries = fsWalk.walkSync('path');
const entries = fsWalk.walkSync('path', {});
const entries = fsWalk.walkSync('path', new fsWalk.Settings());
true
string | Buffer | URL
A path to a file. If a URL is provided, it must use the file:
protocol.
false
Options | Settings
Settings
classAn Options
object or an instance of Settings
class.
When you pass a plain object, an instance of the
Settings
class will be created automatically. If you plan to call the method frequently, use a pre-created instance of theSettings
class.
A class of full settings of the package.
const settings = new fsWalk.Settings({ followSymbolicLinks: true });
const entries = fsWalk.walkSync('path', settings);
name
— The name of the entry (unknown.txt
).path
— The path of the entry relative to call directory (root/unknown.txt
).dirent
— An instance of fs.Dirent
class.stats
] — An instance of fs.Stats
class.string
undefined
By default, all paths are built relative to the root path. You can use this option to set custom root path.
In the example below we read the files from the root
directory, but in the results the root path will be custom
.
fsWalk.walkSync('root'); // → ['root/file.txt']
fsWalk.walkSync('root', { basePath: 'custom' }); // → ['custom/file.txt']
number
Infinity
The maximum number of concurrent calls to fs.readdir
.
The higher the number, the higher performance and the load on the File System. If you want to read in quiet mode, set the value to
4 * os.cpus().length
(4 is default size of thread pool work scheduling).
DeepFilterFunction
undefined
A function that indicates whether the directory will be read deep or not.
// Skip all directories that starts with `node_modules`
const filter: DeepFilterFunction = (entry) => !entry.path.startsWith('node_modules');
EntryFilterFunction
undefined
A function that indicates whether the entry will be included to results or not.
// Exclude all `.js` files from results
const filter: EntryFilterFunction = (entry) => !entry.name.endsWith('.js');
ErrorFilterFunction
undefined
A function that allows you to skip errors that occur when reading directories.
For example, you can skip ENOENT
errors if required:
// Skip all ENOENT errors
const filter: ErrorFilterFunction = (error) => error.code == 'ENOENT';
boolean
false
Adds an instance of fs.Stats
class to the Entry
.
Always use
fs.readdir
with additionalfs.lstat/fs.stat
calls to determine the entry type.
boolean
false
Follow symbolic links or not. Call fs.stat
on symbolic link if true
.
boolean
true
Throw an error when symbolic link is broken if true
or safely return lstat
call if false
.
string
path.sep
By default, this package uses the correct path separator for your OS (\
on Windows, /
on Unix-like systems). But you can set this option to any separator character(s) that you want to use instead.
FileSystemAdapter
By default, the built-in Node.js module (fs
) is used to work with the file system. You can replace any method with your own.
interface FileSystemAdapter {
lstat: typeof fs.lstat;
stat: typeof fs.stat;
lstatSync: typeof fs.lstatSync;
statSync: typeof fs.statSync;
readdir: typeof fs.readdir;
readdirSync: typeof fs.readdirSync;
}
const settings = new fsWalk.Settings({
fs: { lstat: fakeLstat }
});
See the Releases section of our GitHub project for changelog for each release version.
This software is released under the terms of the MIT license.