@nodelib/fs.stat

What is @nodelib/fs.stat?

The @nodelib/fs.stat package is a utility for Node.js that provides an efficient way to get the status of a file or directory. It wraps the fs.stat, fs.lstat, and fs.fstat functions from the Node.js file system module with additional features such as following symbolic links and handling errors more gracefully.

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

Getting file status

This feature allows you to asynchronously get the status of a file. The callback provides either an error or the stats object.

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

stat('path/to/file', (error, stats) => {
  if (error) {
    console.error(error);
    return;
  }

  console.log(stats);
});

Getting file status synchronously

This feature allows you to synchronously get the status of a file. It either returns the stats object or throws an error.

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

try {
  const stats = statSync('path/to/file');
  console.log(stats);
} catch (error) {
  console.error(error);
}

Getting file status with a promise

This feature allows you to get the status of a file using promises. It resolves with the stats object or rejects with an error.

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

stat('path/to/file').then(stats => {
  console.log(stats);
}).catch(error => {
  console.error(error);
});

Other packages similar to @nodelib/fs.stat

fs-extra

fs-extra is a package that builds on the Node.js fs module, providing additional methods and ensuring consistency across platforms. It includes methods like copy, remove, and mkdirs that are not present in @nodelib/fs.stat, but it also provides fs.stat functionality.

graceful-fs

graceful-fs is a drop-in replacement for the fs module that makes file system operations more robust by queuing them and retrying on failure. It includes all the methods of the fs module, including fs.stat, but does not add new features specifically for fs.stat like @nodelib/fs.stat does.

README

@nodelib/fs.stat

Get the status of a file with some features.

:bulb: Highlights

Wrapper around standard method fs.lstat and fs.stat with some features.

• :beginner: Normally follows symbolic link.
• :gear: Can safely work with broken symbolic link.

Install

npm install @nodelib/fs.stat

Usage

import * as fsStat from '@nodelib/fs.stat';

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

Also available with the promise interface:

import * as fsStat from '@nodelib/fs.stat/promises';

await fsStat.stat('path');

API

.stat(path, [optionsOrSettings], callback)

Returns an instance of fs.Stats class for provided path with standard callback-style.

:book: If you want to use the Promise API, import @nodelib/fs.stat/promises or use util.promisify.

fsStat.stat('path', (error, stats) => { /* … */ });
fsStat.stat('path', {}, (error, stats) => { /* … */ });
fsStat.stat('path', new fsStat.Settings(), (error, stats) => { /* … */ });

.statSync(path, [optionsOrSettings])

Returns an instance of fs.Stats class for provided path.

const stats = fsStat.stat('path');
const stats = fsStat.stat('path', {});
const stats = fsStat.stat('path', new fsStat.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 fsStat.Settings({ followSymbolicLink: false });

const stats = fsStat.stat('path', settings);

Options

followSymbolicLink

• Type: boolean
• Default: true

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

markSymbolicLink

• Type: boolean
• Default: false

Mark symbolic link by setting the return value of isSymbolicLink function to always true (even after fs.stat).

:book: Can be used if you want to know what is hidden behind a symbolic link, but still continue to know that it is a symbolic link.

throwErrorOnBrokenSymbolicLink

• Type: boolean
• Default: true

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

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

const settings = new fsStat.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.