You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Socket
Socket
Sign inDemoInstall

@nodelib/fs.scandir

Package Overview
Dependencies
2
Maintainers
1
Versions
17
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@nodelib/fs.scandir

List files and directories inside the specified directory


Version published
Maintainers
1
Created

Package description

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

Readme

Source

@nodelib/fs.scandir

List files and directories inside the specified directory.

:bulb: Highlights

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

  • :moneybag: Returns useful information: name, path, dirent and stats (optional).
  • :link: Can safely work with broken symbolic links.

Install

npm install @nodelib/fs.scandir

Usage

import * as fsScandir from '@nodelib/fs.scandir';

fsScandir.scandir('path', (error, stats) => { /* … */ });

API

.scandir(path, [optionsOrSettings], callback)

Returns an array of plain objects (Entry) with information about entry for provided path with standard callback-style.

fsScandir.scandir('path', (error, entries) => { /* … */ });
fsScandir.scandir('path', {}, (error, entries) => { /* … */ });
fsScandir.scandir('path', new fsScandir.Settings(), (error, entries) => { /* … */ });

.scandirSync(path, [optionsOrSettings])

Returns an array of plain objects (Entry) with information about entry for provided path.

const entries = fsScandir.scandirSync('path');
const entries = fsScandir.scandirSync('path', {});
const entries = fsScandir.scandirSync('path', new fsScandir.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 fsScandir.Settings({ followSymbolicLinks: false });

const entries = fsScandir.scandirSync('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. When the stats option is enabled, it will be emulated by DirentFromStats class.
  • stats (optional) — An instance of fs.Stats class.

For example, the scandir call for tools directory with one directory inside:

{
	dirent: Dirent { name: 'typedoc', /* … */ },
	name: 'typedoc',
	path: 'tools/typedoc'
}

Options

stats

  • Type: boolean
  • Default: false

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

:book: Always use fs.readdir without the withFileTypes option. ??TODO??

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

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

Package last updated on 28 Jul 2023

Did you know?

Socket

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

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc