# totalist

> A tiny (195B to 220B) utility to recursively list all (total) files in a directory

Latest version **3.0.1** (published 2023-04-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install totalist
pnpm add totalist
yarn add totalist
bun add totalist
```

## Health

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

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

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2023-04-03 |
| First published | 2019-10-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=6 |
| Dependencies | 0 |
| Unpacked size | 7.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 150 |
| Author | Luke Edwards |
| Maintainers | lukeed |
| Keywords | list, recursive, files, glob, tree |

## Links

- npm: https://www.npmjs.com/package/totalist
- Repository: https://github.com/lukeed/totalist
- Homepage: https://github.com/lukeed/totalist#readme
- Issues: https://github.com/lukeed/totalist/issues
- npm.io page: https://npm.io/package/totalist

## 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

- 3.0.1 (latest) — 2023-04-03
- 3.0.0 — 2022-01-17
- 2.0.0 — 2020-08-19
- 1.1.0 — 2020-06-20
- 1.0.1 — 2019-10-24
- 1.0.0 — 2019-10-22
- 0.0.0 — 2019-10-22

## README

# totalist [![build status](https://badgen.now.sh/github/status/lukeed/totalist)](https://github.com/lukeed/totalist/actions) [![codecov](https://badgen.now.sh/codecov/c/github/lukeed/totalist)](https://codecov.io/gh/lukeed/totalist)

> A tiny (195B to 224B) utility to recursively list all (total) files in a directory

Traverse a directory recursively, running a function for **every file** found.

With this module, you easily apply custom logic to decide which file(s) to process without worrying about accidentally accessing a directory or making repeat `fs.Stats` requests.

## Install

```
$ npm install --save totalist
```


## Modes

There are two "versions" of `totalist` available:

#### "async"
> **Node.js:** >= 8.x<br>
> **Size (gzip):** 220 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/totalist/dist/index.js), [ES Module](https://unpkg.com/totalist/dist/index.mjs)

This is the primary/default mode. It makes use of `async`/`await` and [`util.promisify`](https://nodejs.org/api/util.html#util_util_promisify_original).

#### "sync"
> **Node.js:** >= 6.x<br>
> **Size (gzip):** 195 bytes<br>
> **Availability:** [CommonJS](https://unpkg.com/totalist/sync/index.js), [ES Module](https://unpkg.com/totalist/sync/index.mjs)

This is the opt-in mode, ideal for scenarios where `async` usage cannot be supported.


## Usage

***Selecting a Mode***

```js
// import via npm module
import { totalist } from 'totalist';
import { totalist } from 'totalist/sync';
```

***Example Usage***

```js
import { totalist } from 'totalist/sync';

const styles = new Set();
const scripts = new Set();

totalist('src', (name, abs, stats) => {
  if (/\.js$/.test(name)) {
    scripts.add(abs);
    if (stats.size >= 100e3) {
      console.warn(`[WARN] "${name}" might cause performance issues (${stats.size})`);
    }
  } else if (/\.css$/.test(name)) {
    styles.add(abs);
  }
});

console.log([...scripts]);
//=> [..., '/Users/lukeed/.../src/path/to/example.css', ...]
```


## API

### totalist(dir, callback)
Returns: `void`

> **Important:** The "async" usage must be `await`ed or included within a Promise chain.

#### dir
Type: `string`<br>
Required: `true`

The directory to traverse.

This may be a relative _or_ an absolute path.

> **Note**: Node.js will assume a relative path is meant to be resolved from the current location (`process.cwd()`).

#### callback
Type: `Function`<br>
Required: `true`

The callback function to run for _every_ file.

The function receives three parameters:

##### relPath
Type: `String`<br>
The path _relative to_ the initial `dir` value you provided.

##### absPath
Type: `String`<br>
The absolute path of the file.

##### stats
Type: `fs.Stats`<br>
The [`fs.Stats`](https://nodejs.org/api/fs.html#fs_class_fs_stats) object for the file.


## License

MIT © [Luke Edwards](https://lukeed.com)

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