source: trip-planner-front/node_modules/@nodelib/fs.walk/README.md

Last change on this file was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 6.0 KB
Line 
1# @nodelib/fs.walk
2
3> A library for efficiently walking a directory recursively.
4
5## :bulb: Highlights
6
7* :moneybag: Returns useful information: `name`, `path`, `dirent` and `stats` (optional).
8* :rocket: On Node.js 10.10+ uses the mechanism without additional calls to determine the entry type for performance reasons. See [`old` and `modern` mode](https://github.com/nodelib/nodelib/blob/master/packages/fs/fs.scandir/README.md#old-and-modern-mode).
9* :gear: Built-in directories/files and error filtering system.
10* :link: Can safely work with broken symbolic links.
11
12## Install
13
14```console
15npm install @nodelib/fs.walk
16```
17
18## Usage
19
20```ts
21import * as fsWalk from '@nodelib/fs.walk';
22
23fsWalk.walk('path', (error, entries) => { /* … */ });
24```
25
26## API
27
28### .walk(path, [optionsOrSettings], callback)
29
30Reads the directory recursively and asynchronously. Requires a callback function.
31
32> :book: If you want to use the Promise API, use `util.promisify`.
33
34```ts
35fsWalk.walk('path', (error, entries) => { /* … */ });
36fsWalk.walk('path', {}, (error, entries) => { /* … */ });
37fsWalk.walk('path', new fsWalk.Settings(), (error, entries) => { /* … */ });
38```
39
40### .walkStream(path, [optionsOrSettings])
41
42Reads the directory recursively and asynchronously. [Readable Stream](https://nodejs.org/dist/latest-v12.x/docs/api/stream.html#stream_readable_streams) is used as a provider.
43
44```ts
45const stream = fsWalk.walkStream('path');
46const stream = fsWalk.walkStream('path', {});
47const stream = fsWalk.walkStream('path', new fsWalk.Settings());
48```
49
50### .walkSync(path, [optionsOrSettings])
51
52Reads the directory recursively and synchronously. Returns an array of entries.
53
54```ts
55const entries = fsWalk.walkSync('path');
56const entries = fsWalk.walkSync('path', {});
57const entries = fsWalk.walkSync('path', new fsWalk.Settings());
58```
59
60#### path
61
62* Required: `true`
63* Type: `string | Buffer | URL`
64
65A path to a file. If a URL is provided, it must use the `file:` protocol.
66
67#### optionsOrSettings
68
69* Required: `false`
70* Type: `Options | Settings`
71* Default: An instance of `Settings` class
72
73An [`Options`](#options) object or an instance of [`Settings`](#settings) class.
74
75> :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.
76
77### Settings([options])
78
79A class of full settings of the package.
80
81```ts
82const settings = new fsWalk.Settings({ followSymbolicLinks: true });
83
84const entries = fsWalk.walkSync('path', settings);
85```
86
87## Entry
88
89* `name` — The name of the entry (`unknown.txt`).
90* `path` — The path of the entry relative to call directory (`root/unknown.txt`).
91* `dirent` — An instance of [`fs.Dirent`](./src/types/index.ts) class.
92* [`stats`] — An instance of `fs.Stats` class.
93
94## Options
95
96### basePath
97
98* Type: `string`
99* Default: `undefined`
100
101By default, all paths are built relative to the root path. You can use this option to set custom root path.
102
103In the example below we read the files from the `root` directory, but in the results the root path will be `custom`.
104
105```ts
106fsWalk.walkSync('root'); // → ['root/file.txt']
107fsWalk.walkSync('root', { basePath: 'custom' }); // → ['custom/file.txt']
108```
109
110### concurrency
111
112* Type: `number`
113* Default: `Infinity`
114
115The maximum number of concurrent calls to `fs.readdir`.
116
117> :book: The higher the number, the higher performance and the load on the File System. If you want to read in quiet mode, set the value to `4 * os.cpus().length` (4 is default size of [thread pool work scheduling](http://docs.libuv.org/en/v1.x/threadpool.html#thread-pool-work-scheduling)).
118
119### deepFilter
120
121* Type: [`DeepFilterFunction`](./src/settings.ts)
122* Default: `undefined`
123
124A function that indicates whether the directory will be read deep or not.
125
126```ts
127// Skip all directories that starts with `node_modules`
128const filter: DeepFilterFunction = (entry) => !entry.path.startsWith('node_modules');
129```
130
131### entryFilter
132
133* Type: [`EntryFilterFunction`](./src/settings.ts)
134* Default: `undefined`
135
136A function that indicates whether the entry will be included to results or not.
137
138```ts
139// Exclude all `.js` files from results
140const filter: EntryFilterFunction = (entry) => !entry.name.endsWith('.js');
141```
142
143### errorFilter
144
145* Type: [`ErrorFilterFunction`](./src/settings.ts)
146* Default: `undefined`
147
148A function that allows you to skip errors that occur when reading directories.
149
150For example, you can skip `ENOENT` errors if required:
151
152```ts
153// Skip all ENOENT errors
154const filter: ErrorFilterFunction = (error) => error.code == 'ENOENT';
155```
156
157### stats
158
159* Type: `boolean`
160* Default: `false`
161
162Adds an instance of `fs.Stats` class to the [`Entry`](#entry).
163
164> :book: Always use `fs.readdir` with additional `fs.lstat/fs.stat` calls to determine the entry type.
165
166### followSymbolicLinks
167
168* Type: `boolean`
169* Default: `false`
170
171Follow symbolic links or not. Call `fs.stat` on symbolic link if `true`.
172
173### `throwErrorOnBrokenSymbolicLink`
174
175* Type: `boolean`
176* Default: `true`
177
178Throw an error when symbolic link is broken if `true` or safely return `lstat` call if `false`.
179
180### `pathSegmentSeparator`
181
182* Type: `string`
183* Default: `path.sep`
184
185By 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.
186
187### `fs`
188
189* Type: `FileSystemAdapter`
190* Default: A default FS methods
191
192By default, the built-in Node.js module (`fs`) is used to work with the file system. You can replace any method with your own.
193
194```ts
195interface FileSystemAdapter {
196 lstat: typeof fs.lstat;
197 stat: typeof fs.stat;
198 lstatSync: typeof fs.lstatSync;
199 statSync: typeof fs.statSync;
200 readdir: typeof fs.readdir;
201 readdirSync: typeof fs.readdirSync;
202}
203
204const settings = new fsWalk.Settings({
205 fs: { lstat: fakeLstat }
206});
207```
208
209## Changelog
210
211See the [Releases section of our GitHub project](https://github.com/nodelib/nodelib/releases) for changelog for each release version.
212
213## License
214
215This software is released under the terms of the MIT license.
Note: See TracBrowser for help on using the repository browser.