# node-readfiles

> A lightweight Node.js module to recursively read files in a directory using ES6 Promises

Latest version **0.4.0** (published 2026-01-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-readfiles
pnpm add node-readfiles
yarn add node-readfiles
bun add node-readfiles
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2026-01-09 |
| First published | 2016-05-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 98.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 7 |
| Author | guatedude2 |
| Maintainers | guatedude2 |
| Keywords | readfiles, read, readfile, readdir, dir, path, pattern, fs |

## Links

- npm: https://www.npmjs.com/package/node-readfiles
- Repository: https://github.com/guatedude2/node-readfiles
- Homepage: https://github.com/guatedude2/node-readfiles#readme
- Issues: https://github.com/guatedude2/node-readfiles/issues
- npm.io page: https://npm.io/package/node-readfiles

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 0.4.0 (latest) — 2026-01-09
- 0.3.1 — 2022-06-15
- 0.3.0 — 2022-06-01
- 0.2.0 — 2016-05-19
- 0.1.0 — 2016-05-19
- 0.0.9 — 2016-05-18
- 0.0.8 — 2016-05-18
- 0.0.7 — 2016-05-18
- 0.0.6 — 2016-05-18
- 0.0.5 — 2016-05-18
- 0.0.4 — 2016-05-18
- 0.0.3 — 2016-05-18
- 0.0.2 — 2016-05-18

## README

# node-readfiles
A lightweight node.js module to recursively read files in a directory using ES6 Promises.

## Installation

    npm install node-readfiles

## Usage

You can safely add `readfiles` anywhere in your project.

```javascript
var readfiles = require('node-readfiles');
```

### _Promise(files):_ readfiles(dir, [options], [callback])
Asynchronusly read the files in a directory returning a **Promise**.

#### dir
A relative or absolute path of the directory to read files.

#### options

An optional object parameter with the following properties:

* **reverse**: a boolean value that reverses the order of the list of files before traversing them (defaults to false)
* **filenameFormat**: one of `readfiles.FULL_PATH`, `readfiles.RELATIVE`, or `readfiles.FILENAME`, whether the callback's returns the full-path, relative-path or only the filenames of the traversed files. (default is `readfiles.RELATIVE`)
* **rejectOnError**: a boolean value whether to stop and trigger the "doneCallback" when an error occurs (defaults to true)
* **filter**: a string, or an array of strings of path expression that match the files being read (defaults to '**')
  * `?` matches one character
  * `*` matches zero or more characters
  * `**` matches zero or more 'directories' in a path
* **readContents**: a boolean value whether to read the file contents when traversing the files <sup>[\[1\]](#read-files)</sup> (defaults to true)
* **encoding**: a string with the encoding used when reading a file (defaults to 'utf8')
* **depth**: an integer value which limits the number sub-directories levels to traverse for the given path where `-1` is infinte, and `0` is none (defaults to -1)
* **hidden**: a boolean value whether to include hidden files prefixed with a `.` (defaults to false)


### callback(err, filename, content, stat)

The optional callback function is triggered everytime a file is found. If there's an error while reading the file the `err` parameter will contain the error that occured, When `readContents` is true, the `contents` parameter will be populated with the contents of the file encoded using the `encoding` option. For convenience the `stat` result object is passed to the callback for you to use.

<span id="read-files">[1]</span> The `contents` parameter will be `null` when the `readContents` option is `false`.


##### Asynchronous Callback
When working with asynchronous operations, you can simply return a `function (next) { ... }` which will enabled you to completed your asynchronous operation until you call `next()`. 

```javascript
readfiles('/path/to/dir/', function (err, filename, content, stat) {
  if (err) throw err;
  return function (next) {
    setTimeout(function () {
      console.log('File ' + filename);
      next();
    }, 3000);
  };
});
```


### _Promise(files)_

When calling `readfiles`, an ES6 Promise is returned with an array of all the files that were found. You can then call `then` or `catch` to see if `readfiles` encountered an error.

```javascript
var readfiles = require('node-readfiles');

readfiles('/path/to/dir/', function (err, filename, content) {
  if (err) throw err;
  console.log('File ' + filename + ':');
  console.log(content);
}).then(function (files) {
  console.log('Read ' + files.length + ' file(s)');
}).catch(function (err) {
  console.log('Error reading files:', err.message);
});
```

## Examples

The default behavior, is to recursively list all files in a directory. By default `readfiles` will exclude all dot files.

```javascript
readfiles('/path/to/dir/', function (err, filename, content) {
  if (err) throw err;
  console.log('File ' + filename + ':');
  console.log(content);
}).then(function (files) {
  console.log('Read ' + files.length + ' file(s)');
  console.log(files.join('\n'));
});
```

Read all files in a directory, excluding sub-directories.

```javascript
readfiles('/path/to/dir/', {
  depth: 0
}, function (err, filename, content) {
  if (err) throw err;
  console.log('File ' + filename + ':');
  console.log(content);
}).then(function (files) {
  console.log('Read ' + files.length + ' file(s)');
  console.log(files.join('\n'));
});
```

The above can also be accomplished using the `filter` option.

```javascript
readfiles('/path/to/dir/', {
  filter: '*' // instead of the default '**'
}, function (err, filename, content) {
  if (err) throw err;
  console.log('File ' + filename + ':');
  console.log(content);
}).then(function (files) {
  console.log('Read ' + files.length + ' file(s)');
  console.log(files.join('\n'));
});
```

Recursively read all files with "txt" extension in a directory and display the contents.

```javascript
readfiles('/path/to/dir/', {
  filter: '*.txt'
}, function (err, filename, content) {
  if (err) throw err;
  console.log('File ' + filename + ':');
  console.log(content);
}).then(function (files) {
  console.log('Read ' + files.length + ' file(s)');
});

```

Recursively read all files with that match "t?t" in a directory and display the contents.

```javascript
readfiles('/path/to/dir/', {
  filter: '*.t?t'
}, function (err, filename, content) {
  if (err) throw err;
  console.log('File ' + filename + ':');
  console.log(content);
}).then(function (files) {
  console.log('Read ' + files.length + ' file(s)');
});

```

Recursively list all json files in a directory including all sub-directories, without reading the files.

```javascript
readfiles('/path/to/dir/', {
  filter: '*.json',
  readContents: false
}, function (err, filename, content) {
  if (err) throw err;
  console.log('File ' + filename);
});

```

## License
MIT licensed (See LICENSE.txt)

---
_Source: https://npm.io/package/node-readfiles · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._