@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