Socket
Socket
Sign inDemoInstall

@nodelib/fs.walk

Package Overview
Dependencies
6
Maintainers
1
Versions
14
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@nodelib/fs.walk

A library for efficiently walking a directory recursively


Version published
Maintainers
1
Weekly downloads
33,425,853
decreased by-7.99%

Weekly downloads

Package description

What is @nodelib/fs.walk?

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.

What are @nodelib/fs.walk's main functionalities?

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.');
});

Other packages similar to @nodelib/fs.walk

Readme

Source

@nodelib/fs.walk

A library for efficiently walking a directory recursively.

:bulb: Highlights

  • :moneybag: Returns useful information: name, path, dirent and stats (optional).
  • :rocket: On Node.js 10.10+ uses the mechanism without additional calls to determine the entry type for performance reasons. See old and modern mode.
  • :gear: Built-in directories/files and error filtering system.
  • :link: Can safely work with broken symbolic links.

Install

npm install @nodelib/fs.walk

Usage

import * as fsWalk from '@nodelib/fs.walk';

fsWalk.walk('path', (error, entries) => { /* … */ });

API

.walk(path, [optionsOrSettings], callback)

Reads the directory recursively and asynchronously. Requires a callback function.

:book: 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) => { /* … */ });

.walkStream(path, [optionsOrSettings])

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());

.walkSync(path, [optionsOrSettings])

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());
path
  • Required: true
  • Type: string | Buffer | URL

A path to a file. If a URL is provided, it must use the file: protocol.

optionsOrSettings
  • Required: false
  • Type: Options | Settings
  • Default: An instance of Settings class

An Options object or an instance of Settings class.

:book: 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 the Settings class.

Settings([options])

A class of full settings of the package.

const settings = new fsWalk.Settings({ followSymbolicLinks: true });

const entries = fsWalk.walkSync('path', settings);

Entry

  • 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.

Options

basePath

  • Type: string
  • Default: 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']

concurrency

  • Type: number
  • Default: Infinity

The 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).

deepFilter

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');

entryFilter

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');

errorFilter

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';

stats

  • Type: boolean
  • Default: false

Adds an instance of fs.Stats class to the Entry.

:book: Always use fs.readdir with additional fs.lstat/fs.stat calls to determine the entry type.

  • Type: boolean
  • Default: false

Follow symbolic links or not. Call fs.stat on symbolic link if true.

  • Type: boolean
  • Default: true

Throw an error when symbolic link is broken if true or safely return lstat call if false.

pathSegmentSeparator

  • Type: string
  • Default: 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.

fs

  • Type: FileSystemAdapter
  • Default: A default FS methods

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 }
});

Changelog

See the Releases section of our GitHub project for changelog for each release version.

License

This software is released under the terms of the MIT license.

Keywords

FAQs

Last updated on 08 Jul 2021

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.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc