TypeScript TQDM Progress Bar

Common errors

• TypeError: (0 , ts_tqdm__WEBPACK_IMPORTED_MODULE_0__.tqdm) is not a function

  cause Incorrect import statement, often trying to use a CommonJS `require` syntax or a default import when `tqdm` is a named export.
  fix Ensure you are using `import { tqdm } from 'ts-tqdm';` for ESM modules. For older Node.js versions or specific configurations, ensure proper transpilation if using ES Modules.

• Argument of type 'string[]' is not assignable to parameter of type 'number | Iterable<unknown>'.

  cause The `tqdm` function expects either a number (for fixed iterations) or an `Iterable` (like an array or Set). Passing a non-iterable type or a non-number type will result in a TypeScript error.
  fix Ensure the argument passed to `tqdm` is an `Iterable` (e.g., `Array`, `Set`, `Map`) or a `number`. For example, `tqdm([1, 2, 3])` or `tqdm(100)`.

Warnings

• gotcha Direct console logging (e.g., `console.log`) inside a `tqdm` loop can interfere with the progress bar's display, causing flickering or incorrect rendering. `tqdm` re-renders the line constantly.
  Fix: Avoid `console.log` within the loop body. If logging is necessary, consider buffering messages and printing them after the loop, or using `tqdm`'s internal logging mechanisms if available (not currently in `ts-tqdm`), or redirecting logs to a file.
• gotcha When `ts-tqdm` is used in environments without a TTY (e.g., some CI/CD pipelines, background processes without a terminal attached), the progress bar might not render correctly or at all. It relies on terminal capabilities for dynamic updates.
  Fix: Check `process.stdout.isTTY` before conditionally enabling `tqdm`. For non-TTY environments, simply iterate without wrapping in `tqdm` or use a different logging approach. The library will gracefully degrade to no output if no TTY is detected.
• gotcha The library primarily targets Node.js environments and assumes a standard console output. Using it in browser environments directly is not supported and will likely lead to errors related to Node.js-specific globals or console behaviors.
  Fix: Use browser-specific progress bar libraries for front-end applications. `ts-tqdm` is designed for server-side or command-line Node.js scripts.

Install

• npm install ts-tqdm npm
• yarn add ts-tqdm yarn
• pnpm add ts-tqdm pnpm

Imports

• tqdm
  wrong:

  const { tqdm } = require('ts-tqdm');

  correct:

  import { tqdm } from 'ts-tqdm';

  ts-tqdm is primarily an ESM module and expects named imports. CommonJS `require` is not the recommended or natively supported way to import.
• tqdm
  wrong:

  import tqdm from 'ts-tqdm';

  correct:

  import { tqdm } from 'ts-tqdm';

  The `tqdm` function is a named export, not a default export. Using a default import will result in `undefined`.

Quickstart

Demonstrates `tqdm` usage for both fixed iterations and array iteration, with asynchronous tasks.

import { tqdm } from "ts-tqdm";

const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

(async () => {
    console.log('Starting long process...');
    const totalIterations = 50;

    // Iterate over a fixed number of iterations
    for (let i of tqdm(totalIterations, { description: 'Processing items' })) {
        // Simulate an asynchronous task
        await delay(50);
        if (i % 10 === 0) {
            // console.log(`  Processed item ${i}`); // Avoid console.log inside tqdm loop if it interferes with progress bar
        }
    }

    console.log('Finished processing items.\n');

    const data = Array.from({ length: 25 }, (_, i) => `item-${i}`);
    for (let item of tqdm(data, { description: 'Analyzing data' })) {
        await delay(100);
        // console.log(`  Analyzing ${item}`);
    }
    console.log('Data analysis complete.');
})();