totalist

Common errors

• TypeError: totalist is not a function

  cause Attempting to use `require` for `totalist` in a pure ESM context, or using a CommonJS `require` call that doesn't correctly resolve the module's default export when `exports` are defined.
  fix For ESM projects, use `import { totalist } from 'totalist';` or `import { totalist } from 'totalist/sync';`. If still encountering issues in a CommonJS context, ensure your Node.js version is compatible with `exports` maps or consider using `totalist` v2.x.

• UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'size' of undefined

  cause The asynchronous `totalist` function was called but not `await`ed, leading to subsequent code attempting to use data (like `stats.size`) before the callback had a chance to populate it.
  fix Always `await` the asynchronous `totalist` call: `await totalist(dir, callback);`. Ensure the calling function is marked `async`.

• Error: Cannot find module 'totalist/sync'

  cause This error typically indicates that the module resolution failed to locate the synchronous variant of totalist, possibly due to an incorrect path, a non-standard module resolution setup, or a problem with the installed package.
  fix Verify the package is installed correctly (`npm install totalist`). Ensure your import statement is exactly `import { totalist } from 'totalist/sync';` and your bundler/Node.js environment supports subpath exports.

Warnings

• breaking Version 3.0.0 introduced native ESM support via the `exports` mapping in `package.json`. This may cause breaking changes for Node.js versions 13.0 through 13.7 due to their experimental and rapidly evolving module resolution behavior. Users on these specific Node.js versions should upgrade to a later stable release (14+ recommended) or remain on `totalist` v2.x.
  Fix: Upgrade Node.js to a stable version (14+) or use `totalist` v2.x if upgrading Node.js is not possible.
• gotcha The default `totalist` export is asynchronous and returns a Promise. It must be `await`ed or handled within a Promise chain to ensure all files are processed before subsequent code executes. Failing to `await` it will result in the function returning immediately without processing files, potentially leading to incorrect program state.
  Fix: Ensure `await totalist(dir, callback);` is used within an `async` function, or chain with `.then(() => { ... })`.
• gotcha There are two distinct modes: asynchronous (`totalist`) and synchronous (`totalist/sync`). Incorrectly importing the async version when synchronous behavior is expected, or vice-versa, can lead to unexpected execution flow or errors. The sync version requires `import { totalist } from 'totalist/sync';`.
  Fix: Choose the correct import path based on your required execution mode: `import { totalist } from 'totalist';` for async, or `import { totalist } from 'totalist/sync';` for sync.

Install

• npm install totalist npm
• yarn add totalist yarn
• pnpm add totalist pnpm

Imports

• totalist
  wrong:

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

  correct:

  import { totalist } from 'totalist';

  This is the default async version. In v3+, `require` might work depending on bundler/Node.js version, but direct ESM import is preferred. This must be `await`ed.
• totalist (sync)
  wrong:

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

  correct:

  import { totalist } from 'totalist/sync';

  This imports the synchronous version, suitable for contexts where async/await is not an option or desired. ESM import is preferred in v3+.
• fs.Stats type

  import type { Stats } from 'fs';

  The callback receives an `fs.Stats` object. Import `Stats` type from Node's built-in 'fs' module for TypeScript.

Quickstart

This quickstart demonstrates how to use `totalist/sync` to recursively scan a directory and categorize files based on their extensions. It sets up a temporary directory with various files and then logs the categorized absolute paths and file sizes.

import { totalist } from 'totalist/sync';
import { resolve } from 'path';
import { fileURLToPath } from 'url';
import { existsSync, mkdirSync, writeFileSync } from 'fs';

// Create a dummy directory for demonstration
const __dirname = fileURLToPath(new URL('.', import.meta.url));
const testDir = resolve(__dirname, 'temp_files');
if (!existsSync(testDir)) {
  mkdirSync(testDir, { recursive: true });
}
writeFileSync(resolve(testDir, 'file1.js'), 'console.log("file1");');
writeFileSync(resolve(testDir, 'style.css'), 'body { color: red; }');
writeFileSync(resolve(testDir, 'another.js'), 'console.log("file2");');
mkdirSync(resolve(testDir, 'subdir'), { recursive: true });
writeFileSync(resolve(testDir, 'subdir', 'nested.txt'), 'nested content');

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

try {
  totalist(testDir, (name, abs, stats) => {
    if (name.endsWith('.js')) {
      scripts.add(abs);
    } else if (name.endsWith('.css')) {
      styles.add(abs);
    } else {
      others.add(abs);
    }
    console.log(`Processing: ${name} (size: ${stats.size} bytes)`);
  });

  console.log('\n--- Summary ---');
  console.log('JavaScript files:', [...scripts]);
  console.log('CSS files:', [...styles]);
  console.log('Other files:', [...others]);
} catch (error) {
  console.error('Error listing files:', error);
}

// Clean up dummy directory (optional, but good for examples)
// import { rmSync } from 'fs';
// rmSync(testDir, { recursive: true, force: true });