Debian Codegraph @

nodelib-fsscandir/README.md

raw
1 # @nodelib/fs.scandir
2
3 > List files and directories inside the specified directory.
4
5 ## :bulb: Highlights
6
7 The package is aimed at obtaining information about entries in the directory.
8
9 * :moneybag: Returns useful information: `name`, `path`, `dirent` and `stats` (optional).
10 * :gear: On Node.js 10.10+ uses the mechanism without additional calls to determine the entry type. See [`old` and `modern` mode](#old-and-modern-mode).
11 * :link: Can safely work with broken symbolic links.
12
13 ## Install
14
15 ```console
16 npm install @nodelib/fs.scandir
17 ```
18
19 ## Usage
20
21 ```ts
22 import * as fsScandir from '@nodelib/fs.scandir';
23
24 fsScandir.scandir('path', (error, stats) => { /* … */ });
25 ```
26
27 ## API
28
29 ### .scandir(path, [optionsOrSettings], callback)
30
31 Returns an array of plain objects ([`Entry`](#entry)) with information about entry for provided path with standard callback-style.
32
33 ```ts
34 fsScandir.scandir('path', (error, entries) => { /* … */ });
35 fsScandir.scandir('path', {}, (error, entries) => { /* … */ });
36 fsScandir.scandir('path', new fsScandir.Settings(), (error, entries) => { /* … */ });
37 ```
38
39 ### .scandirSync(path, [optionsOrSettings])
40
41 Returns an array of plain objects ([`Entry`](#entry)) with information about entry for provided path.
42
43 ```ts
44 const entries = fsScandir.scandirSync('path');
45 const entries = fsScandir.scandirSync('path', {});
46 const entries = fsScandir.scandirSync(('path', new fsScandir.Settings());
47 ```
48
49 #### path
50
51 * Required: `true`
52 * Type: `string | Buffer | URL`
53
54 A path to a file. If a URL is provided, it must use the `file:` protocol.
55
56 #### optionsOrSettings
57
58 * Required: `false`
59 * Type: `Options | Settings`
60 * Default: An instance of `Settings` class
61
62 An [`Options`](#options) object or an instance of [`Settings`](#settingsoptions) class.
63
64 > :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.
65
66 ### Settings([options])
67
68 A class of full settings of the package.
69
70 ```ts
71 const settings = new fsScandir.Settings({ followSymbolicLinks: false });
72
73 const entries = fsScandir.scandirSync('path', settings);
74 ```
75
76 ## Entry
77
78 * `name` — The name of the entry (`unknown.txt`).
79 * `path` — The path of the entry relative to call directory (`root/unknown.txt`).
80 * `dirent` — An instance of [`fs.Dirent`](./src/types/index.ts) class. On Node.js below 10.10 will be emulated by [`DirentFromStats`](./src/utils/fs.ts) class.
81 * `stats` (optional) — An instance of `fs.Stats` class.
82
83 For example, the `scandir` call for `tools` directory with one directory inside:
84
85 ```ts
86 {
87 dirent: Dirent { name: 'typedoc', /* … */ },
88 name: 'typedoc',
89 path: 'tools/typedoc'
90 }
91 ```
92
93 ## Options
94
95 ### stats
96
97 * Type: `boolean`
98 * Default: `false`
99
100 Adds an instance of `fs.Stats` class to the [`Entry`](#entry).
101
102 > :book: Always use `fs.readdir` without the `withFileTypes` option. ??TODO??
103
104 ### followSymbolicLinks
105
106 * Type: `boolean`
107 * Default: `false`
108
109 Follow symbolic links or not. Call `fs.stat` on symbolic link if `true`.
110
111 ### `throwErrorOnBrokenSymbolicLink`
112
113 * Type: `boolean`
114 * Default: `true`
115
116 Throw an error when symbolic link is broken if `true` or safely use `lstat` call if `false`.
117
118 ### `pathSegmentSeparator`
119
120 * Type: `string`
121 * Default: `path.sep`
122
123 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.
124
125 ### `fs`
126
127 * Type: [`FileSystemAdapter`](./src/adapters/fs.ts)
128 * Default: A default FS methods
129
130 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.
131
132 ```ts
133 interface FileSystemAdapter {
134 lstat?: typeof fs.lstat;
135 stat?: typeof fs.stat;
136 lstatSync?: typeof fs.lstatSync;
137 statSync?: typeof fs.statSync;
138 readdir?: typeof fs.readdir;
139 readdirSync?: typeof fs.readdirSync;
140 }
141
142 const settings = new fsScandir.Settings({
143 fs: { lstat: fakeLstat }
144 });
145 ```
146
147 ## `old` and `modern` mode
148
149 This package has two modes that are used depending on the environment and parameters of use.
150
151 ### old
152
153 * Node.js below `10.10` or when the `stats` option is enabled
154
155 When working in the old mode, the directory is read first (`fs.readdir`), then the type of entries is determined (`fs.lstat` and/or `fs.stat` for symbolic links).
156
157 ### modern
158
159 * Node.js 10.10+ and the `stats` option is disabled
160
161 In the modern mode, reading the directory (`fs.readdir` with the `withFileTypes` option) is combined with obtaining information about its entries. An additional call for symbolic links (`fs.stat`) is still present.
162
163 This mode makes fewer calls to the file system. It's faster.
164
165 ## Changelog
166
167 See the [Releases section of our GitHub project](https://github.com/nodelib/nodelib/releases) for changelog for each release version.
168
169 ## License
170
171 This software is released under the terms of the MIT license.