You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`readdir-enhanced`adds several features to the built-in `fs.readdir()` function. All of the enhanced features are opt-in, which makes `readdir-enhanced` [fully backward compatible by default](#backward-compatible). You can enable any of the features by passing-in an `options` argument as the second parameter.
115
+
Readdir Enhanced adds several features to the built-in `fs.readdir()` function. All of the enhanced features are opt-in, which makes Readdir Enhanced [fully backward compatible by default](#backward-compatible). You can enable any of the features by passing-in an `options` argument as the second parameter.
116
116
117
117
118
118
119
119
<a id="deep"></a>
120
120
Crawl Subdirectories
121
121
----------------------------------
122
-
By default, `readdir-enhanced` will only return the top-level contents of the starting directory. But you can set the `deep` option to recursively traverse the subdirectories and return their contents as well.
122
+
By default, Readdir Enhanced will only return the top-level contents of the starting directory. But you can set the `deep` option to recursively traverse the subdirectories and return their contents as well.
123
123
124
124
### Crawl ALL subdirectories
125
125
126
126
The `deep` option can be set to `true` to traverse the entire directory structure.
The `deep` option can be set to a number to only traverse that many levels deep. For example, calling `readdir("my/directory", {deep:2})` will return `subdir1/file.txt` and `subdir1/subdir2/file.txt`, but it _won't_ return `subdir1/subdir2/subdir3/file.txt`.
@@ -161,7 +161,7 @@ For simple use-cases, you can use a [regular expression](https://developer.mozil
161
161
> **NOTE:** Glob patterns [_always_ use forward-slashes](https://github.com/isaacs/node-glob#windows), even on Windows. This _does not_ apply to regular expressions though. Regular expressions should use the appropraite path separator for the environment. Or, you can match both types of separators using `[\\/]`.
162
162
163
163
```javascript
164
-
importreaddirfrom"readdir-enhanced";
164
+
importreaddirfrom"@jsdevtools/readdir-enhanced";
165
165
166
166
// Only crawl the "lib" and "bin" subdirectories
167
167
// (notice that the "node_modules" subdirectory does NOT get crawled)
@@ -182,7 +182,7 @@ For more advanced recursion, you can set the `deep` option to a function that ac
182
182
> **NOTE:** The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object that's passed to the function has additional `path` and `depth` properties. The `path` is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath). The `depth` is the number of subdirectories beneath the base path (see [`options.deep`](#deep)).
183
183
184
184
```javascript
185
-
importreaddirfrom"readdir-enhanced";
185
+
importreaddirfrom"@jsdevtools/readdir-enhanced";
186
186
187
187
// Crawl all subdirectories, except "node_modules"
188
188
functionignoreNodeModules (stats) {
@@ -213,7 +213,7 @@ For simple use-cases, you can use a [regular expression](https://developer.mozil
213
213
> **NOTE:** Glob patterns [_always_ use forward-slashes](https://github.com/isaacs/node-glob#windows), even on Windows. This _does not_ apply to regular expressions though. Regular expressions should use the appropraite path separator for the environment. Or, you can match both types of separators using `[\\/]`.
214
214
215
215
```javascript
216
-
importreaddirfrom"readdir-enhanced";
216
+
importreaddirfrom"@jsdevtools/readdir-enhanced";
217
217
218
218
// Find all .txt files
219
219
readdir("my/directory", {filter:"*.txt"});
@@ -231,7 +231,7 @@ For more advanced filtering, you can specify a filter function that accepts an [
231
231
> **NOTE:** The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object that's passed to the filter function has additional `path` and `depth` properties. The `path` is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath). The `depth` is the number of subdirectories beneath the base path (see [`options.deep`](#deep)).
232
232
233
233
```javascript
234
-
importreaddirfrom"readdir-enhanced";
234
+
importreaddirfrom"@jsdevtools/readdir-enhanced";
235
235
236
236
// Only return file names containing an underscore
All of the `readdir-enhanced` functions listed above return an array of strings (paths). But in some situations, the path isn't enough information. Setting the `stats` option returns an array of [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) objects instead of path strings. The `fs.Stats` object contains all sorts of useful information, such as the size, the creation date/time, and helper methods such as `isFile()`, `isDirectory()`, `isSymbolicLink()`, etc.
255
+
All of the Readdir Enhanced functions listed above return an array of strings (paths). But in some situations, the path isn't enough information. Setting the `stats` option returns an array of [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) objects instead of path strings. The `fs.Stats` object contains all sorts of useful information, such as the size, the creation date/time, and helper methods such as `isFile()`, `isDirectory()`, `isSymbolicLink()`, etc.
256
256
257
257
> **NOTE:** The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) objects that are returned also have additional `path` and `depth` properties. The `path` is relative to the starting directory by default, but you can customize this via [`options.basePath`](#basepath). The `depth` is the number of subdirectories beneath the base path (see [`options.deep`](#deep)).
By default all `readdir-enhanced` functions return paths that are relative to the starting directory. But you can use the `basePath` option to customize this. The `basePath` will be prepended to all of the returned paths. One common use-case for this is to set `basePath` to the absolute path of the starting directory, so that all of the returned paths will be absolute.
274
+
By default all Readdir Enhanced functions return paths that are relative to the starting directory. But you can use the `basePath` option to customize this. The `basePath` will be prepended to all of the returned paths. One common use-case for this is to set `basePath` to the absolute path of the starting directory, so that all of the returned paths will be absolute.
By default, `readdir-enhanced` uses the correct path separator for your OS (`\` on Windows, `/` on Linux & MacOS). But you can set the `sep` option to any separator character(s) that you want to use instead. This is usually used to ensure consistent path separators across different OSes.
303
+
By default, Readdir Enhanced uses the correct path separator for your OS (`\` on Windows, `/` on Linux & MacOS). But you can set the `sep` option to any separator character(s) that you want to use instead. This is usually used to ensure consistent path separators across different OSes.
By default, `readdir-enhanced` uses the default [Node.js FileSystem module](https://nodejs.org/api/fs.html) for methods like `fs.stat`, `fs.readdir` and `fs.lstat`. But in some situations, you can want to use your own FS methods (FTP, SSH, remote drive and etc). So you can provide your own implementation of FS methods by setting `options.fs` or specific methods, such as `options.fs.stat`.
325
+
By default, Readdir Enhanced uses the default [Node.js FileSystem module](https://nodejs.org/api/fs.html) for methods like `fs.stat`, `fs.readdir` and `fs.lstat`. But in some situations, you can want to use your own FS methods (FTP, SSH, remote drive and etc). So you can provide your own implementation of FS methods by setting `options.fs` or specific methods, such as `options.fs.stat`.
`readdir-enhanced` is fully backward-compatible with Node.js' built-in `fs.readdir()` and `fs.readdirSync()` functions, so you can use it as a drop-in replacement in existing projects without affecting existing functionality, while still being able to use the enhanced features as needed.
351
+
Readdir Enhanced is fully backward-compatible with Node.js' built-in `fs.readdir()` and `fs.readdirSync()` functions, so you can use it as a drop-in replacement in existing projects without affecting existing functionality, while still being able to use the enhanced features as needed.
// Use it just like Node's built-in fs.readdir function
357
357
readdir("my/directory", (er, files) => { ... });
@@ -364,18 +364,18 @@ let files = readdirSync("my/directory");
364
364
365
365
A Note on Streams
366
366
----------------------------------
367
-
The `readdir-enhanced` streaming API follows the Node.js streaming API. A lot of questions around the streaming API can be answered by reading the [Node.js documentation.](https://nodejs.org/api/stream.html). However, we've tried to answer the most common questions here.
367
+
The Readdir Enhanced streaming API follows the Node.js streaming API. A lot of questions around the streaming API can be answered by reading the [Node.js documentation.](https://nodejs.org/api/stream.html). However, we've tried to answer the most common questions here.
368
368
369
369
### Stream Events
370
370
371
-
All events in the Node.js streaming API are supported by `readdir-enhanced`. These events include "end", "close", "drain", "error", plus more. [An exhaustive list of events is available in the Node.js documentation.](https://nodejs.org/api/stream.html#stream_class_stream_readable)
371
+
All events in the Node.js streaming API are supported by Readdir Enhanced. These events include "end", "close", "drain", "error", plus more. [An exhaustive list of events is available in the Node.js documentation.](https://nodejs.org/api/stream.html#stream_class_stream_readable)
372
372
373
373
#### Detect when the Stream has finished
374
374
375
375
Using these events, we can detect when the stream has finished reading files.
376
376
377
377
```javascript
378
-
importreaddirfrom"readdir-enhanced";
378
+
importreaddirfrom"@jsdevtools/readdir-enhanced";
379
379
380
380
// Build the stream using the Streaming API
381
381
let stream =readdir.stream("my/directory")
@@ -389,7 +389,7 @@ stream.on("end", () => {
389
389
390
390
### Paused Streams vs. Flowing Streams
391
391
392
-
As with all Node.js streams, a `readdir-enhanced` stream starts in "paused mode". For the stream to start emitting files, you'll need to switch it to "flowing mode".
392
+
As with all Node.js streams, a Readdir Enhanced stream starts in "paused mode". For the stream to start emitting files, you'll need to switch it to "flowing mode".
393
393
394
394
There are many ways to trigger flowing mode, such as adding a `stream.data()` handler, using `stream.pipe()` or calling `stream.resume()`.
395
395
@@ -419,7 +419,7 @@ To build the project locally on your computer:
419
419
420
420
License
421
421
--------------------------
422
-
`readdir-enhanced` is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
422
+
Readdir Enhanced is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
0 commit comments