README
@aboviq/readdir-recursive
Customizeable async recursive fs.readdir with no dependencies and sane defaults
Why?
- No dependencies / Small
- Asynchronous, i.e. returns a promise (uses async/await under the hood)
- Provides a syncronous version as well
- Sane defaults, i.e. does not recurse into
node_modules
by default - Fully customizable, with options to decide in which folders to recurse into and what files and information to include in the results, with full access to each file's Stats information
Installation
Install @aboviq/readdir-recursive
using npm:
npm install @aboviq/readdir-recursive
Usage
Module usage
const readdirRecursive = require('@aboviq/readdir-recursive');
const files = await readdirRecursive('a/path');
/*
[
"/full-path/a/path/filename.ext",
"/full-path/a/path/nested/folders/another.ext",
...
]
*/
const files = readdirRecursive.sync('a/path');
/*
[
"/full-path/a/path/filename.ext",
"/full-path/a/path/nested/folders/another.ext",
...
]
*/
API
readdirRecursive(dir, options)
Name | Type | Description |
---|---|---|
dir | String |
The folder to read files recursively in, either relative to cwd or an absolute path |
options | Object |
Options for filtering, recursion and transformation |
Returns: Promise<Array>
, all found files transformed according to the transformer and that has not been filtered out
readdirRecursive.sync(dir, options)
Name | Type | Description |
---|---|---|
dir | String |
The folder to read files recursively in, either relative to cwd or an absolute path |
options | Object |
Options for filtering, recursion and transformation |
Returns: Array
, all found files transformed according to the transformer and that has not been filtered out
Options
Note: all function options can be asynchronous (return promises) when using the async version of readdirRecursive
, but not with the sync version.
options.filter
Type: Function
Signature: filter :: Object -> Boolean
Default: () => true
The filter
option is used to decide if a file should be included in the resulting array of files or not. A file is included if the filter function returns a truthy value.
The Object
passed to the filter
function has the following properties:
Name | Type | Description |
---|---|---|
file | String |
The file name, e.g. "file.txt" |
path | String |
The full path to the file, e.g. "/your/folder/sub-folder/file.txt" |
stats | Stats |
A stats object providing information about the file |
options.transform
Type: Function
Signature: transform :: Object -> String
Default: a function returing the full path of each file
The transform
option is used to transform file information into something useful. Every file that passes the filter function will be transformed before being included in the resulting array.
The Object
passed to the transform
function has the following properties:
Name | Type | Description |
---|---|---|
file | String |
The file name, e.g. "file.txt" |
path | String |
The full path to the file, e.g. "/your/folder/sub-folder/file.txt" |
stats | Stats |
A stats object providing information about the file |
options.recurse
Type: Function
Signature: recurse :: Object -> Boolean
Default: a function which won't recurse node_modules
The recurse
option is used to decide if a folder should be recursed into or not. A folder is recursed if the recurse function returns a truthy value.
The Object
passed to the recurse
function has the following properties:
Name | Type | Description |
---|---|---|
dir | String |
The folder name, e.g. "src" |
path | String |
The full path to the folder, e.g. "/your/folder/sub-folder" |
stats | Stats |
A stats object providing information about the folder |
Contributing
See Contribution Guidelines and our Code Of Conduct.
License
MIT © Aboviq AB