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