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 | * :link: Can safely work with broken symbolic links.
|
11 |
|
12 | ## Install
|
13 |
|
14 | ```console
|
15 | npm install @nodelib/fs.scandir
|
16 | ```
|
17 |
|
18 | ## Usage
|
19 |
|
20 | ```ts
|
21 | import * as fsScandir from '@nodelib/fs.scandir';
|
22 |
|
23 | fsScandir.scandir('path', (error, stats) => { /* … */ });
|
24 | ```
|
25 |
|
26 | ## API
|
27 |
|
28 | ### .scandir(path, [optionsOrSettings], callback)
|
29 |
|
30 | Returns an array of plain objects ([`Entry`](#entry)) with information about entry for provided path with standard callback-style.
|
31 |
|
32 | ```ts
|
33 | fsScandir.scandir('path', (error, entries) => { /* … */ });
|
34 | fsScandir.scandir('path', {}, (error, entries) => { /* … */ });
|
35 | fsScandir.scandir('path', new fsScandir.Settings(), (error, entries) => { /* … */ });
|
36 | ```
|
37 |
|
38 | ### .scandirSync(path, [optionsOrSettings])
|
39 |
|
40 | Returns an array of plain objects ([`Entry`](#entry)) with information about entry for provided path.
|
41 |
|
42 | ```ts
|
43 | const entries = fsScandir.scandirSync('path');
|
44 | const entries = fsScandir.scandirSync('path', {});
|
45 | const entries = fsScandir.scandirSync('path', new fsScandir.Settings());
|
46 | ```
|
47 |
|
48 | #### path
|
49 |
|
50 | * Required: `true`
|
51 | * Type: `string | Buffer | URL`
|
52 |
|
53 | A 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 |
|
61 | An [`Options`](#options) object or an instance of [`Settings`](#settingsoptions) 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 |
|
67 | A class of full settings of the package.
|
68 |
|
69 | ```ts
|
70 | const settings = new fsScandir.Settings({ followSymbolicLinks: false });
|
71 |
|
72 | const entries = fsScandir.scandirSync('path', settings);
|
73 | ```
|
74 |
|
75 | ## Entry
|
76 |
|
77 | * `name` — The name of the entry (`unknown.txt`).
|
78 | * `path` — The path of the entry relative to call directory (`root/unknown.txt`).
|
79 | * `dirent` — An instance of [`fs.Dirent`](./src/types/index.ts) class. When the `stats` option is enabled, it will be emulated by [`DirentFromStats`](./src/utils/fs.ts) class.
|
80 | * `stats` (optional) — An instance of `fs.Stats` class.
|
81 |
|
82 | For example, the `scandir` call for `tools` directory with one directory inside:
|
83 |
|
84 | ```ts
|
85 | {
|
86 | dirent: Dirent { name: 'typedoc', /* … */ },
|
87 | name: 'typedoc',
|
88 | path: 'tools/typedoc'
|
89 | }
|
90 | ```
|
91 |
|
92 | ## Options
|
93 |
|
94 | ### stats
|
95 |
|
96 | * Type: `boolean`
|
97 | * Default: `false`
|
98 |
|
99 | Adds an instance of `fs.Stats` class to the [`Entry`](#entry).
|
100 |
|
101 | > :book: Always use `fs.readdir` without the `withFileTypes` option. ??TODO??
|
102 |
|
103 | ### followSymbolicLinks
|
104 |
|
105 | * Type: `boolean`
|
106 | * Default: `false`
|
107 |
|
108 | Follow symbolic links or not. Call `fs.stat` on symbolic link if `true`.
|
109 |
|
110 | ### `throwErrorOnBrokenSymbolicLink`
|
111 |
|
112 | * Type: `boolean`
|
113 | * Default: `true`
|
114 |
|
115 | Throw an error when symbolic link is broken if `true` or safely use `lstat` call if `false`.
|
116 |
|
117 | ### `pathSegmentSeparator`
|
118 |
|
119 | * Type: `string`
|
120 | * Default: `path.sep`
|
121 |
|
122 | 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.
|
123 |
|
124 | ### `fs`
|
125 |
|
126 | * Type: [`FileSystemAdapter`](./src/adapters/fs.ts)
|
127 | * Default: A default FS methods
|
128 |
|
129 | 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.
|
130 |
|
131 | ```ts
|
132 | interface FileSystemAdapter {
|
133 | lstat?: typeof fs.lstat;
|
134 | stat?: typeof fs.stat;
|
135 | lstatSync?: typeof fs.lstatSync;
|
136 | statSync?: typeof fs.statSync;
|
137 | readdir?: typeof fs.readdir;
|
138 | readdirSync?: typeof fs.readdirSync;
|
139 | }
|
140 |
|
141 | const settings = new fsScandir.Settings({
|
142 | fs: { lstat: fakeLstat }
|
143 | });
|
144 | ```
|
145 |
|
146 | ## Changelog
|
147 |
|
148 | See the [Releases section of our GitHub project](https://github.com/nodelib/nodelib/releases) for changelog for each release version.
|
149 |
|
150 | ## License
|
151 |
|
152 | This software is released under the terms of the MIT license.
|