110 lines
2.8 KiB
Markdown
110 lines
2.8 KiB
Markdown
|
# totalist [](https://github.com/lukeed/totalist/actions) [](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):** 224 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)
|