1 | # rrdir
|
2 | [![](https://img.shields.io/npm/v/rrdir.svg?style=flat)](https://www.npmjs.org/package/rrdir) [![](https://img.shields.io/npm/dm/rrdir.svg)](https://www.npmjs.org/package/rrdir) [![](https://packagephobia.com/badge?p=rrdir)](https://packagephobia.com/result?p=rrdir)
|
3 |
|
4 | > Recursive directory reader with a delightful API
|
5 |
|
6 | `rrdir` recursively reads a directory and returns entries within via an async iterator or async/sync as Array. It can typically iterate millions of files in a matter of seconds. Memory usage is `O(1)` for the async iterator and `O(n)` for the Array variants.
|
7 |
|
8 | Contrary to other similar modules, this module is optionally able to read any path including ones that contain invalid UTF-8 sequences.
|
9 |
|
10 | ## Usage
|
11 | ```console
|
12 | npm i rrdir
|
13 | ```
|
14 | ```js
|
15 | import {rrdir, rrdirAsync, rrdirSync} from "rrdir";
|
16 |
|
17 | for await (const entry of rrdir("dir")) {
|
18 | // => {path: 'dir/file', directory: false, symlink: false}
|
19 | }
|
20 |
|
21 | const entries = await rrdirAsync("dir");
|
22 | // => [{path: 'dir/file', directory: false, symlink: false}]
|
23 |
|
24 | const entries = rrdirSync("dir");
|
25 | // => [{path: 'dir/file', directory: false, symlink: false}]
|
26 |
|
27 | ```
|
28 |
|
29 | ## API
|
30 | ### `rrdir(dir, [options])`
|
31 | ### `rrdirAsync(dir, [options])`
|
32 | ### `rrdirSync(dir, [options])`
|
33 |
|
34 | `rrdir` is an async iterator which yields `entry`. `rrdirAsync` and `rrdirSync` return an Array of `entry`.
|
35 |
|
36 | #### `dir` *String* | *Uint8Array*
|
37 |
|
38 | The directory to read, either absolute or relative. Pass a `Uint8Array` to switch the module into `Uint8Array` mode which is required to be able to read every file, like for example files with names that are invalid UTF-8 sequences.
|
39 |
|
40 | #### `options` *Object*
|
41 |
|
42 | - `stats` *boolean*: Whether to include `entry.stats`. Will reduce performance. Default: `false`.
|
43 | - `followSymlinks` *boolean*: Whether to follow symlinks for both recursion and `stat` calls. Default: `false`.
|
44 | - `exclude` *Array*: Path globs to exclude, e.g. `["**.js"]`. Default: `undefined`.
|
45 | - `include` *Array*: Path globs to include, e.g. `["**.map"]`. Default: `undefined`.
|
46 | - `strict` *boolean*: Whether to throw immediately when reading an entry fails. Default: `false`.
|
47 | - `insensitive` *boolean*: Whether `include` and `exclude` match case-insensitively. Default: `false`.
|
48 |
|
49 | #### `entry` *Object*
|
50 |
|
51 | - `path` *string* | *Uint8Array*: The path to the entry, will be relative if `dir` is given relative. If `dir` is a `Uint8Array`, this will be too. Always present.
|
52 | - `directory` *boolean*: Boolean indicating whether the entry is a directory. `undefined` on error.
|
53 | - `symlink` *boolean*: Boolean indicating whether the entry is a symbolic link. `undefined` on error.
|
54 | - `stats` *Object*: A [`fs.stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object, present when `options.stats` is set. `undefined` on error.
|
55 | - `err` *Error*: Any error encountered while reading this entry. `undefined` on success.
|
56 |
|
57 | © [silverwind](https://github.com/silverwind), distributed under BSD licence
|