UNPKG

3.08 kBMarkdownView Raw
1# @nodelib/fs.stat
2
3> Get the status of a file with some features.
4
5## :bulb: Highlights
6
7Wrapper around standard method `fs.lstat` and `fs.stat` with some features.
8
9* :beginner: Normally follows symbolic link.
10* :gear: Can safely work with broken symbolic link.
11
12## Install
13
14```console
15npm install @nodelib/fs.stat
16```
17
18## Usage
19
20```ts
21import * as fsStat from '@nodelib/fs.stat';
22
23fsStat.stat('path', (error, stats) => { /* … */ });
24```
25
26## API
27
28### .stat(path, [optionsOrSettings], callback)
29
30Returns an instance of `fs.Stats` class for provided path with standard callback-style.
31
32```ts
33fsStat.stat('path', (error, stats) => { /* … */ });
34fsStat.stat('path', {}, (error, stats) => { /* … */ });
35fsStat.stat('path', new fsStat.Settings(), (error, stats) => { /* … */ });
36```
37
38### .statSync(path, [optionsOrSettings])
39
40Returns an instance of `fs.Stats` class for provided path.
41
42```ts
43const stats = fsStat.stat('path');
44const stats = fsStat.stat('path', {});
45const stats = fsStat.stat('path', new fsStat.Settings());
46```
47
48#### path
49
50* Required: `true`
51* Type: `string | Buffer | URL`
52
53A path to a file. If a URL is provided, it must use the `file:` protocol.
54
55#### optionsOrSettings
56
57* Required: `false`
58* Type: `Options | Settings`
59* Default: An instance of `Settings` class
60
61An [`Options`](#options) object or an instance of [`Settings`](#settings) class.
62
63> :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.
64
65### Settings([options])
66
67A class of full settings of the package.
68
69```ts
70const settings = new fsStat.Settings({ followSymbolicLink: false });
71
72const stats = fsStat.stat('path', settings);
73```
74
75## Options
76
77### `followSymbolicLink`
78
79* Type: `boolean`
80* Default: `true`
81
82Follow symbolic link or not. Call `fs.stat` on symbolic link if `true`.
83
84### `markSymbolicLink`
85
86* Type: `boolean`
87* Default: `false`
88
89Mark symbolic link by setting the return value of `isSymbolicLink` function to always `true` (even after `fs.stat`).
90
91> :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.
92
93### `throwErrorOnBrokenSymbolicLink`
94
95* Type: `boolean`
96* Default: `true`
97
98Throw an error when symbolic link is broken if `true` or safely return `lstat` call if `false`.
99
100### `fs`
101
102* Type: [`FileSystemAdapter`](./src/adapters/fs.ts)
103* Default: A default FS methods
104
105By default, the built-in Node.js module (`fs`) is used to work with the file system. You can replace any method with your own.
106
107```ts
108interface FileSystemAdapter {
109 lstat?: typeof fs.lstat;
110 stat?: typeof fs.stat;
111 lstatSync?: typeof fs.lstatSync;
112 statSync?: typeof fs.statSync;
113}
114
115const settings = new fsStat.Settings({
116 fs: { lstat: fakeLstat }
117});
118```
119
120## Changelog
121
122See the [Releases section of our GitHub project](https://github.com/nodelib/nodelib/releases) for changelog for each release version.
123
124## License
125
126This software is released under the terms of the MIT license.