@nodelib/fs.walk
Advanced tools
The @nodelib/fs.walk package is a Node.js library for efficiently walking a directory tree and listing all the files and directories within it. It provides a way to traverse the filesystem with various options for filtering and handling the results.
Asynchronous directory walking
This feature allows you to walk through directories asynchronously, receiving a callback with the list of all entries (files and directories).
const { walk } = require('@nodelib/fs.walk');
walk('path/to/directory', (error, entries) => {
if (error) {
throw error;
}
for (const entry of entries) {
console.log(entry.path);
}
});Synchronous directory walking
This feature provides a synchronous way to walk through directories, returning an array of all entries.
const { walkSync } = require('@nodelib/fs.walk');
const entries = walkSync('path/to/directory');
for (const entry of entries) {
console.log(entry.path);
}Stream-based directory walking
This feature allows you to walk through directories using a stream interface, which can be more efficient for handling large directories.
const { walkStream } = require('@nodelib/fs.walk');
const stream = walkStream('path/to/directory');
stream.on('data', (entry) => {
console.log(entry.path);
});
stream.on('error', (error) => {
throw error;
});
stream.on('end', () => {
console.log('Finished walking the directory.');
});The 'glob' package provides pattern matching for file paths. It can be used to find files and directories using glob patterns, which is similar to the filtering capabilities of @nodelib/fs.walk. However, glob does not provide a direct API for walking directories and is more focused on pattern matching.
The 'readdirp' package is similar to @nodelib/fs.walk in that it provides a way to recursively read directories and obtain a stream of files. It offers a high level of customization for filtering and handling results, and it can be seen as an alternative with a slightly different API and feature set.
The 'walk' package is another alternative for recursively walking directory trees. It is similar to @nodelib/fs.walk but has a different API and may have different performance characteristics. It also provides events for different types of file system entries, which can be useful for more complex walking scenarios.
A library for efficiently walking a directory recursively.
name, path, dirent and stats (optional).npm install @nodelib/fs.walk
import * as fsWalk from '@nodelib/fs.walk';
fsWalk.walk('path', (error, entries) => { /* … */ });
Also available with the promise interface:
import * as fsWalk from '@nodelib/fs.walk/promises';
await fsWalk.walk('path');
Reads the directory recursively and asynchronously. Requires a callback function.
:book: If you want to use the Promise API, import
@nodelib/fs.walk/promisesor useutil.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());
truestring | Buffer | URLA path to a file. If a URL is provided, it must use the file: protocol.
falseOptions | SettingsSettings classAn Options object or an instance of Settings class.
:book: When you pass a plain object, an instance of the
Settingsclass will be created automatically. If you plan to call the method frequently, use a pre-created instance of theSettingsclass.
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.stringundefinedBy 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']
numberInfinityThe maximum number of concurrent calls to fs.readdir.
:book: 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).
DeepFilterFunctionundefinedA 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');
EntryFilterFunctionundefinedA 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');
ErrorFilterFunctionundefinedA 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';
booleanfalseAdds an instance of fs.Stats class to the Entry.
:book: Always use
fs.readdirwith additionalfs.lstat/fs.statcalls to determine the entry type.
booleanfalseFollow symbolic links or not. Call fs.stat on symbolic link if true.
throwErrorOnBrokenSymbolicLinkbooleantrueThrow an error when symbolic link is broken if true or safely return lstat call if false.
pathSegmentSeparatorstringpath.sepBy 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.
fsFileSystemAdapterBy 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 }
});
signalAbortSignalundefinedA signal to abort the walk. Works only with asynchronous walk.
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.
FAQs
A library for efficiently walking a directory recursively
The npm package @nodelib/fs.walk receives a total of 39,261,949 weekly downloads. As such, @nodelib/fs.walk popularity was classified as popular.
We found that @nodelib/fs.walk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.