@nodelib/fs.scandir

What is @nodelib/fs.scandir?

The @nodelib/fs.scandir package is a Node.js library that provides a way to read the contents of a directory with the ability to get detailed information about each entry. It supports both synchronous and asynchronous operations and can handle errors gracefully. It is a low-level package that can be used to build more complex file system utilities.

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

Asynchronous directory scanning

This feature allows you to asynchronously scan a directory and obtain an array of entries, each representing a file or directory within the scanned directory.

const { scandir } = require('@nodelib/fs.scandir');

scandir('/path/to/directory', (error, entries) => {
  if (error) {
    console.error(error);
    return;
  }
  entries.forEach((entry) => {
    console.log(entry);
  });
});

Synchronous directory scanning

This feature allows you to synchronously scan a directory and obtain an array of entries, similar to the asynchronous version but blocking the event loop until the operation is complete.

const { scandirSync } = require('@nodelib/fs.scandir');

try {
  const entries = scandirSync('/path/to/directory');
  entries.forEach((entry) => {
    console.log(entry);
  });
} catch (error) {
  console.error(error);
}

Stream-based directory scanning

This feature provides a stream interface for directory scanning, allowing you to process entries as they are read, which can be more memory-efficient for large directories.

const { scandirStream } = require('@nodelib/fs.scandir');

const stream = scandirStream('/path/to/directory');
stream.on('data', (entry) => {
  console.log(entry);
});
stream.on('error', (error) => {
  console.error(error);
});
stream.on('end', () => {
  console.log('Scanning is complete.');
});

Other packages similar to @nodelib/fs.scandir

fs-extra

fs-extra is a package that extends the built-in fs module with additional methods and improvements. It includes methods for directory scanning, but it is a more comprehensive file system utility library.

readdirp

readdirp is a package that provides recursive directory reading with a stream interface. It is similar to @nodelib/fs.scandir's stream feature but focuses on recursive scanning and filtering.

glob

glob is a package that allows pattern matching for filenames. It can be used to scan directories and filter files based on glob patterns, which is different from the straightforward directory listing provided by @nodelib/fs.scandir.

README

@nodelib/fs.scandir

List files and directories inside the specified path.

:bulb: Highlights

The package is aimed at obtaining information about entries in the directory.

• :dart: Filter system.
• :gear: Ready for the future development of Node.js (#15699).

Install

$ npm install @nodelib/fs.scandir

Usage

const fsScandir = require('@nodelib/fs.scandir');

fsScandir.scandir('root').then((entries) => {
    console.log(entries); // => [{ name: 'name', path: 'root/name', ino: 0, is... }]
});

API

fsScandir.scandir(path, [options])

Returns a Promise<DirEntry[]> for provided path.

fsScandir.scandirSync(path, [options])

Returns a DirEntry[] for provided path.

path

• Type: string | Buffer | URL

The path to scan.

options

• Type: Object

See options section for more detailed information.

Options

stats

• Type: boolean
• Default: false

Include information (fs.Stats) about the file or not.

followSymlinks

• Type: boolean
• Default: true

Please, take a look at description inside the fs.stat package.

throwErrorOnBrokenSymlinks

• Type: boolean
• Default: false

Please, take a look at description inside the fs.stat package.

preFilter

• Type: Function ((name: string) => boolean)
• Default: null

Name-based entries filter.

filter

• Type: Function ((entry: DirEntry) => boolean)
• Default: null

DirEntry-based entries filter.

sort

• Type: Function ((a: DirEntry, b: DirEntry) => number)
• Default: null

Sort entries on the basis of DirEntry. Uses the standard sort method.

DirEntry interface

Please, take a look at types/entry.ts file.

Changelog

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

License

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