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