npm package: @keepsolutions/recursive-readdir-async
Description: Module to recursive read directory async (non blocking). Must be used with Promises. Configurable, extended filtering. etc.
Author: ricard.figuls
Latest version: 1.1.7

[![Build Status](https://travis-ci.org/m0rtadelo/recursive-readdir-async.svg?branch=master)](https://travis-ci.org/m0rtadelo/recursive-readdir-async)
[![Coverage Status](https://coveralls.io/repos/github/m0rtadelo/recursive-readdir-async/badge.svg?branch=master)](https://coveralls.io/github/m0rtadelo/recursive-readdir-async?branch=master)
[![Known Vulnerabilities](https://snyk.io/test/github/m0rtadelo/recursive-readdir-async/badge.svg?targetFile=package.json)](https://snyk.io/test/github/m0rtadelo/recursive-readdir-async?targetFile=package.json)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/5e14bf445b434f3f9603a61b6f851f14)](https://www.codacy.com/app/m0rtadelo/recursive-readdir-async?utm_source=github.com&utm_medium=referral&utm_content=m0rtadelo/recursive-readdir-async&utm_campaign=Badge_Grade)
![GitHub top language](https://img.shields.io/github/languages/top/m0rtadelo/recursive-readdir-async.svg)
[![npm version](https://badge.fury.io/js/recursive-readdir-async.svg)](https://badge.fury.io/js/recursive-readdir-async)

# recursive-readdir-async

NPM Module to recursive read directory async (non blocking). Returns Promise. Configurable, with callback for extended filtering and progress status. Quiet, NO dependencies.
As non blocking module it is perfect to be used in any javascript based Desktop applications.

> This module uses Promises and can't be used in old javascript engines.

> This is a fork of M0rtadelo great module (https://www.npmjs.com/package/recursive-readdir-async). The only difference to the original code is that it fixes the following bug - https://github.com/m0rtadelo/recursive-readdir-async/issues/3

## Installation

For normal usage into a project, you must install as a NPM dependency. The next command will do all the work:

```
npm install --save recursive-readdir-async
```

After install, you can use the module using the _require_ key:

```javascript
// Assign recursive-readdir-async to constant
const rra = require("recursive-readdir-async");
// use it
```

## Usage

Example of basic usage:

```javascript
const rra = require("recursive-readdir-async");
const list = await rra.list(".");
console.log(list);
```

```javascript
const rra = require("recursive-readdir-async");
rra.list(".").then(function (list) {
  console.log(list);
});
```

Example with full features:

```javascript
const rra = require("recursive-readdir-async");
const options = {
  mode: rra.LIST,
  recursive: true,
  stats: false,
  ignoreFolders: true,
  extensions: false,
  deep: false,
  realPath: true,
  normalizePath: true,
  include: [],
  exclude: [],
  readContent: false,
  encoding: "base64",
};
const list = await rra.list(".", options, function (obj, index, total) {
  console.log(`${index} of ${total} ${obj.path}`);
  if (obj.name == "folder2") return true; // return true to delete item
});
if (list.error) console.error(list.error);
else console.log(list);
```

## Options

An options object can be passed to configure the module. The next options can be used:

- **mode (LIST | TREE)** : The list will return an array of items. The tree will return the items structured like the file system. _Default: list_
- **recursive (true | false)** : If true, files and folders of folders and subfolders will be listed. If false, only the files and folders of the select directory will be listed. _Default: true_
- **stats (true | false)** : If true a `stats` object ([with file information](https://nodejs.org/api/fs.html#fs_class_fs_stats)) will be added to every item. If false this info is not added. _Default: false_
- **ignoreFolders (true | false)** : If true and mode is LIST, the list will be returned with files only. If true and mode is TREE, the directory structures without files will be deleted. If false, all empty and non empty directories will be listed. _Default: true_
- **extensions (true | false)** : If true, lowercase extensions will be added to every item in the `extension` object property (`file.TXT` => `info.extension = ".txt"`). _Default: false_
- **deep (true | false)** : If true, folder depth information will be added to every item starting with 0 (initial path), and will be incremented by 1 in every subfolder. _Default: false_
- **normalizePath (true | false)** : Normalizes windows style paths by replacing double backslahes with single forward slahes (unix style). _Default: true_
- **realPath (true | false)** : Computes the canonical pathname by resolving `.`, `..` and symbolic links. _Default: true_
- **include (Array of String)** : Positive filter the items: only items which [DO](http://www.ietf.org/rfc/rfc2119.txt) (partially or completely) match one of the strings in the `include` array will be returned. _Default: []_
- **exclude (Array of String)** : Negative filter the items: only items which [DO NOT](http://www.ietf.org/rfc/rfc2119.txt) (partially or completely) match _any_ of the strings in the `exclude` array will be returned. _Default: []_
- **readContent (true | false)** : Adds the content of the file into the item (base64 format). _Default: false_
- **encoding (String)**: Sets the encoding of the file data (ascii, base64, binary, hex, ucs2/ucs-2/utf16le/utf-16le, utf8/utf-8, latin1). _Default: base64_

### Notes

- Counter-intuitive to some folks, an _empty_ `include` array is treated same as setting it to `null` / `undefined`: no include filter will be applied.
  Obviously, an _empty_ `exclude` array acts similar: no `exclude` filter will be applied.
- The `include` and `exclude` options interact.

  **When `mode` is TREE**

  - Directories which [DO NOT](http://www.ietf.org/rfc/rfc2119.txt) match the `include` criteria themselves but contain items which [DO](http://www.ietf.org/rfc/rfc2119.txt) _are kept_ in the returned items tree. I.e. _inclusion of the child_ has precedence over _rejection of the parent_.
  - Directories which [DO](http://www.ietf.org/rfc/rfc2119.txt) match one of the `exclude` criteria themselves but contain items which [DO NOT](http://www.ietf.org/rfc/rfc2119.txt) _will not_ be kept in the returned items tree. I.e. _exclusion of the parent_ has precedence over _remaining of the child_.

  **When `mode` is LIST**

  As the directory tree is flattened into a list, directories and their children (subdirectories and files) are filtered through the `exclude` and `include` rules independently, hence `include` and `exclude` will only interact when an item matches _both_ filters. See below:

  **Common ground: `mode` is LIST or TREE**

  - `exclude` has precedence over `include`: exclusion rules are applied before the inclusion rules. Hence when an item matches both a string in the `include` array and a string in the `exclude` array, the item will be _excluded_ (removed) from the list.

- Reading data from the filesystem can have unexpected behaviors. Use the `readContent` option with responsability.

## Object structure

The function will return an object and never throw an error. All errors will be added to the returned object. The return object in LIST mode looks like this:

```json
[
  {
    "name": "item_name",
    "path": "/absolute/path/to/item",
    "fullname": "/absolute/path/to/item/item_name",
    "extension": "",
    "isDirectory": true,
    "stats": {}
  },
  {
    "name": "file.txt",
    "path": "/absolute/path/to/item/item_name",
    "fullname": "/absolute/path/to/item/item_name/file.txt",
    "extension": ".txt",
    "isDirectory": false,
    "data": "base64/utf8/etc.",
    "stats": {}
  },
  {
    "name": "UCASE.JPEG",
    "path": "/absolute/path/to/item/item_name",
    "fullname": "/absolute/path/to/item/item_name/UCASE.JPEG",
    "extension": ".jpeg",
    "isDirectory": false,
    "data": "base64/utf8/etc.",
    "stats": {}
  }
]
```

The same example for TREE mode:

```json
[
  {
    "name": "item_name",
    "path": "/absolute/path/to/item",
    "fullname": "/absolute/path/to/item/item_name",
    "isDirectory": true,
    "stats": {},
    "content": [
      {
        "name": "file.txt",
        "path": "/absolute/path/to/item/item_name",
        "fullname": "/absolute/path/to/item/item_name/file.txt",
        "extension": ".txt",
        "isDirectory": false,
        "data": "base64/utf8/etc.",
        "stats": {}
      },
      {
        "name": "UCASE.JPEG",
        "path": "/absolute/path/to/item/item_name",
        "fullname": "/absolute/path/to/item/item_name/UCASE.JPEG",
        "extension": ".jpeg",
        "isDirectory": false,
        "data": "base64/utf8/etc.",
        "stats": {}
      }
    ]
  }
]
```

> `isDirectory` only exists if `stats`, `recursive`,`readContent` or `ignoreFolders` are `true` or `mode` is TREE

> `stats` only exists if `options.stats` is `true`

> `extension` only exists if `options.extensions` is `true`

> `data` only exists if `options.readContent` is `true`

## Errors handling

All errors will be added to the returned object. If an error occurs on the main call, the error will be returned like this:

```json
{
  "error": {
    "message": "ENOENT: no such file or directory, scandir '/inexistentpath'",
    "errno": -4058,
    "code": "ENOENT",
    "syscall": "scandir",
    "path": "/inexistentpath"
  },
  "path": "/inexistentpath"
}
```

For errors with files and folders, the error will be added to the item like this:

```json
[
    {
        "name":"item_name",
        "path":"/absolute/path/to/item",
        "fullname":"/absolute/path/to/item/item_name",
        "error":{

        }
    }
    {
        "name":"file.txt",
        "path":"/absolute/path/to/item",
        "fullname":"/absolute/path/to/item/file.txt",
        "error":{

        }
    }
]
```

More information on: https://m0rtadelo.github.io/recursive-readdir-async/global.html