# list-contents

> Returns a list of paths to the subfolders and subfiles of the specified location.

Latest version **4.0.3** (published 2020-08-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install list-contents
pnpm add list-contents
yarn add list-contents
bun add list-contents
```

## 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 | 4.0.3 |
| Published | 2020-08-18 |
| First published | 2017-07-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 14.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Paweł Rafałko |
| Maintainers | devrafalko |
| Keywords | folder, subfolder, file, subfile, contents, directory, path |

## Links

- npm: https://www.npmjs.com/package/list-contents
- Repository: https://github.com/devrafalko/list-contents
- Homepage: https://github.com/devrafalko/list-contents#readme
- Issues: https://github.com/devrafalko/list-contents/issues
- npm.io page: https://npm.io/package/list-contents

## Dependencies (3)

- [move-on](https://npm.io/package/move-on.md) ^2.1.8
- [of-type](https://npm.io/package/of-type.md) ^3.0.3
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) ^5.1.2

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 4.0.3 (latest) — 2020-08-18
- 4.0.2 — 2018-05-12
- 4.0.1 — 2017-10-09
- 4.0.0 — 2017-10-09
- 3.2.0 — 2017-10-09
- 3.1.0 — 2017-10-06
- 3.0.0 — 2017-09-28
- 2.0.7 — 2017-09-25
- 2.0.6 — 2017-09-25
- 2.0.5 — 2017-09-17
- 2.0.4 — 2017-09-08
- 2.0.3 — 2017-08-01
- 2.0.2 — 2017-08-01
- 2.0.1 — 2017-08-01
- 1.0.0 — 2017-07-30

## README

# Description
`list-contents` is a module that returns a list of paths to the subfolders and subfiles of the specified location.
* Any bugs found? Give me to know on *dev.rafalko@gmail.com* or on [GitHub](https://github.com/devrafalko/list-contents)
* Also check out [**`file-assistant`**](https://www.npmjs.com/package/file-assistant) package that creates, copies or moves the folders and files into the specified path or modifies the files' content according to the given [Array] object (or .json file path) instructions.

# Installation
`npm install list-contents`

```javascript
const list = require('list-contents');
```

# Usage
### `list(path,[config,]callback)`
##### `path` **[String]**
* It should indicate the path to the chosen directory, which subfolders and subfiles should be listed

##### `config` **[Object]**
* if **omitted**, the parameters are set to their default values; *All the elements of all levels are listed*.
* You can configure the `list-contents` module with the following [Object] `config`'s properties:
  * **`depth`** [Number|null] *(default:null)*  
    It indicates how deep the `list-contents` module should explore the folders in the given `path` directory.  
    If set to `null` *(default)* - it lists all subfiles and subfolders of all levels of the `path` directory.  
    If set to 1 - it lists only the one level of `path` directory elements; eg. `./styles`, `./index.html`.  
    If set to 2 - it lists two levels of `path` directory elements; eg. `./styles/css`, `./scripts/ajax.js`  
    etc.
  * **`exclude`** [Array|String] *(default:[])*  
    It indicates the folders' and files' paths that should be ignored and not included into the `files`, `dirs` and `inaccessible` lists.  
    If the folder is indicated, neither the folder nor its contents will be included.  
    When [String], it can indicate the one path to ignore, eg `"./bin"`.  
    When [Array], it can indicate more than one path to ignore, eg. `["./node_modules", "./bin"]`.  
    The given paths **must be relative** to the `path`, otherwise they will be not recognized.  
    You can ignore needless paths, eg. `'./node_modules'` or `'./.git'` to make the `list-contents` module faster.

```javascript
const listContents = require('list-contents');

listContents('./dist', (data)=>{/*...*/});
listContents('./dist', {depth: 5}, (data)=>{/*...*/});
listContents('./dist', {depth: 3, exclude: ['node_modules','.git']}, (data)=>{/*...*/})
```

##### `callback` **[Function]**
* the [Object] argument is passed through **`callback`** function. It has 5 properties:
  * **`error`** [Boolean|Error]
    `null` if the **`path`** is valid, otherwise [Error] object
  * **`dirs`** [Array]  
    The list of all subfolders' paths of the specified **`path`** argument
  * **`files`** [Array]  
    The list of all subfiles' paths of the specified **`path`** argument
  * **`inaccessible`** [Array] **`v3.*.*`**  
    The list of all unrecognized or inaccessible elements' paths of the specified **`path`** argument.  
    If the file or folder is inaccessible, it does not stop retrieving the further files and folders.
  * **`path`** [String]  
    The path that was given as **`path`** parameter

```javascript
const list = require('list-contents');

list("./dist",(o)=>{
  if(o.error) throw o.error;
  console.log('Folders: ', o.dirs);
  console.log('Files: ', o.files);
});
```

# Samples
Assuming that "./dist" path contains the following subfolders and subfiles:
```
dist
 ├ scripts
 │  ├ index.js
 │  └ ajax.js
 ├ styles
 │  ├ css   
 │  │  ├ layout.css
 │  │  └ media.css
 │  └ scss
 │     └ mixins.scss
 └ templates
    ├ main.html
    ├ menubar.html
    ├ login.html
    └ contact.html
```
the module will pass the following object through the `callback` function:
```javascript
{
  error: null,
  path: "./dist",
  dirs: [
    'scripts',
    'templates',
    'styles',
    'styles/css',
    'styles/scss'
  ],
  files: [
    'scripts/ajax.js',
    'scripts/index.js',
    'templates/contact.html',
    'templates/login.html',
    'templates/main.html',
    'templates/menubar.html',
    'styles/css/layout.css',
    'styles/css/media.css',
    'styles/scss/mixins.scss'
  ],
  inaccessible: []
}
```

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