totalist

What is totalist?

The totalist npm package is a simple, fast utility to recursively list all files in a directory, or totalist. It is designed to be minimalistic and efficient, making it suitable for various applications where you need to process or handle files within a directory structure.

What are totalist's main functionalities?

Recursively list all files

This feature allows you to recursively list all files in a specified directory. The callback function receives the name of each file, its absolute path, and its stats object, which includes properties like file size.

const { totalist } = require('totalist');

async function listFiles(dir) {
  await totalist(dir, (name, abs, stats) => {
    console.log(name, abs, stats.size);
  });
}

listFiles('./path/to/directory');

Other packages similar to totalist

glob

The 'glob' package provides functionality to match files using the patterns the shell uses, like stars and stuff. It's more feature-rich than totalist, offering pattern matching and filtering capabilities, but it might be slower for simply listing all files due to the overhead of pattern matching.

readdirp

Readdirp is another package that offers recursive directory reading with a stream API, making it suitable for handling large directories. It provides more options for filtering and handling entries than totalist, but it might be more complex to use for basic file listing tasks.

README

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
Size (gzip): 220 bytes
Availability: CommonJS, ES Module

This is the primary/default mode. It makes use of async/await and util.promisify.

"sync"

Node.js: >= 6.x
Size (gzip): 195 bytes
Availability: CommonJS, ES Module

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

Usage

Selecting a Mode

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

Example Usage

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 awaited or included within a Promise chain.

dir

Type: string
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
Required: true

The callback function to run for every file.

The function receives three parameters:

relPath

Type: String
The path relative to the initial dir value you provided.

absPath

Type: String
The absolute path of the file.

stats

Type: fs.Stats
The fs.Stats object for the file.

License

MIT © Luke Edwards