# @kxghnpm/kx-file-lister-sync

> Simple synchronous file lister

Latest version **1.0.3** (published 2020-04-10) · ISC license · 0 weekly downloads

## Install

```sh
npm install @kxghnpm/kx-file-lister-sync
pnpm add @kxghnpm/kx-file-lister-sync
yarn add @kxghnpm/kx-file-lister-sync
bun add @kxghnpm/kx-file-lister-sync
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2020-04-10 |
| First published | 2020-04-04 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | github.com/kxgh |
| Maintainers | kxghnpm |
| Keywords | filelister |

## Links

- npm: https://www.npmjs.com/package/@kxghnpm/kx-file-lister-sync
- Repository: https://github.com/kxgh/kx-file-lister-sync
- Homepage: https://github.com/kxgh/kx-file-lister-sync#readme
- Issues: https://github.com/kxgh/kx-file-lister-sync/issues
- npm.io page: https://npm.io/package/@kxghnpm/kx-file-lister-sync

## Recent versions

- 1.0.3 (latest) — 2020-04-10
- 1.0.2 — 2020-04-04

## README

# kx-file-lister-sync

Content listing in directories using Node.js. Supporting recursion, stats, detailed output, blacklists, whitelists, size formatters.
Fully synchronous.

## Example

Basic usage:

```javascript
const fl = new (require('@kxghnpm/kx-file-lister-sync'))();
const list = fl.listFiles('../some/folder');
console.log(list)
```
Output:
```
[ '..\\some\\backgorund.js',
  '..\\some\\manifest.js',
  '..\\some\\docs\\cv.ods',
  '..\\some\\docs\\photos\\pic.jpg',
  '..\\some\\docs\\photos\\pic2.jpg' ]
```

More examples at the bottom.

## API

```javascript
const FileLister = require('@kxghnpm/kx-file-lister-sync');
let fl = new FileLister(opts);
```

### Constructor

File lister exports a class, therefore it must be instantiated with ``new`` keyword. Object params ``opts`` is optional.

#### opts

Object opts is passed to contructor. It accepts these properties:

#### detailed

If set to `true` it will list objects with properties
`name` for file name,
`path` for file path
`full` for full file path,
`ext` for extension and
`dir` for whether it is a directory.
Otherwise it returns plain string filepaths. Defaults to `false`

#### stats

Enables detailed mode and each item will also include fs stats. Contains single err property, if could not stat.
Defaults to `false`.

#### blackList

Array of strings or `RegExp`s, or both. Each (non-dir) file will be checked by each blackList entry if it matches it will not be listed.
Matching is done by `String.prototype.endsWith` function on file's name, while regexps are checked by `RegExp.prototype.test`.
Only works if whiteList is empty or missing. Defaults to `[]`

#### whiteList

Does the opposite of what blackList does. If whiteList is specified and has at least one element, all listings ignore blackList
and use whiteList instead. Empty by default.

#### filterDirs

White and black lists also affect diving into directories if set to `true`. Defaults to `false`.

#### sizeFormatter

Value of this property must be a function and should take one `Number` param (file size in bytes) and output anything.
Decorator for file size.

#### sortByName

Whether to sort output entries by name. If set to `false` (default) it will sort output entries by 'directories first'.
Defaults to `false`.

#### ignoreLinks

Output will not contain files that are symbolic links. Defaults to `true`.

### listFiles(dirPath[, recursive, maxDepth])

Lists all files in directories and possibly subdirectories into a single flat array.
  * `dirPath` target directory path
  * `recursive` also lists subdirectories if `true`. Defaults to `true`
  * `maxDepth` do not dive into subdirectories deeper than this number. 0 for just target directory, 1 for target directory
  and their direct subdirectories, `n`

### listOneDir(dirPath)

Lists files **and directories** in target directory.

  * `dirPath` target directory path

### listFilesTree(dirPath[, maxDepth])

Lists files into a deep array, mapping fs's tree structure. 

  * `dirPath` target directory path
  * `maxDepth` do not dive into subdirectories deeper than this number
  
## Which methods are recursive?

| Method        | Recursive?    | Lists dirs?   |
| ------------- |:-------------:|:-------------:|
| listFiles     | yes, settable | no            |
| listOneDir    | no            | yes           |
| listFilesTree | yes           | as a structure|

  
## Examples

Code:

```javascript
const FileLister = require('@kxghnpm/kx-file-lister-sync');
const fl = new FileLister({
    detailed: true,
    sortByName: true,
    whiteList: [/m[ao]/,'.js']
});
const result = fl.listFiles('xx/some');
console.log(result);
```

Outputs to:
```
[ { name: 'backgorund.js',
    path: 'xx\\some\\backgorund.js',
    dir: false,
    ext: '.js',
    full:
     'C:\\Users\\kxgh\\projs\\kx-file-lister-sync\\xx\\some\\backgorund.js' },
  { name: 'manifest.js',
    path: 'xx\\some\\manifest.js',
    dir: false,
    ext: '.js',
    full:
     'C:\\Users\\kxgh\\projs\\kx-file-lister-sync\\xx\\some\\manifest.js' } ]
```
---

Code:

```javascript
const FileLister = require('@kxghnpm/kx-file-lister-sync');
const fl = new FileLister({blackList: ['some'], filterDirs: true});
const result = fl.listFilesTree('xx');
console.log(result);
```

Outputs to:
```
[ [ [ 'xx\\xy\\xz\\ac.js' ], 'xx\\xy\\ab.js' ], 'xx\\aa.js' ]
```
---

Code:

```javascript
const FileLister = require('@kxghnpm/kx-file-lister-sync');
const fl = new FileLister({
    whiteList: [/manifest/i],
    detailed: true
});
const result = fl.listOneDir('xx/some');
console.log(result);
```

Outputs to:

```
[ { name: 'docs',
    path: 'xx\\some\\docs',
    dir: true,
    ext: '',
    full:
     'C:\\Users\\kxgh\\projs\\kx-file-lister-sync\\xx\\some\\docs' },
  { name: 'manifest.js',
    path: 'xx\\some\\manifest.js',
    dir: false,
    ext: '.js',
    full:
     'C:\\Users\\kxgh\\projs\\kx-file-lister-sync\\xx\\some\\manifest.js' } ]
```

---
_Source: https://npm.io/package/@kxghnpm/kx-file-lister-sync · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._