simple-progress-logger/README.md

Tiny terminal progress logger with determinate bar, indeterminate animation, and ETA.

# simple-progress-logger

A tiny, dependency-free (runtime) terminal progress logger with determinate bars, indeterminate loading animation, and ETA display — extracted from the user's custom implementation and packaged for npm.

## Install

    npm i simple-progress-logger

## Usage (CommonJS)

    const { Logger } = require('simple-progress-logger');

    async function demo() {
        const total = 50;
        const log = new Logger({ message: 'Processing items…', total, barLength: 20 });
        for (let i = 0; i <= total; i++) {
            log.update('Crunching…', i);
            await new Promise(r => setTimeout(r, 40));
        }
        log.stop('Done!');
    }

    demo();

## Usage (ESM)

    import { Logger } from 'simple-progress-logger';

    const total = 10;
    const log = new Logger({ message: 'Indexing…', total });
    let i = 0;
    const interval = setInterval(() => {
        i++;
        log.increment();
        if (i >= total) {
            clearInterval(interval);
            log.stop('Complete');
        }
    }, 100);

## API

### `new Logger(options?)`

**Options**

- `message` (string): Label to show next to the bar/animation. Default `''`.
- `total` (number|null): Total units for determinate mode. If `null`, runs indeterminate animation. Default `null`.
- `value` (number): Initial progress value. Default `0`.
- `showProgressBar` (boolean): Show determinate bar. Default `true`.
- `showLoadingAnimation` (boolean): Show indeterminate animation. Default `true`.
- `showEta` (boolean): Show ETA (only in determinate). Default `true`.
- `barLength` (number): Bar/animation width (chars). Default `10`.
- `updateThrottle` (number): Refresh interval (ms). Default `50`.
- `showAvgTimePerItem` (boolean): Append average seconds/item on stop. Default `false`.
- `fullCharacter` (string): Filled bar character. Default `\u2588`.
- `emptyCharacter` (string): Empty bar character. Default `\u2591`.
- `displayMessageFirst` (boolean): Put message before bar. Default `false`.

**Methods**

- `update(message?: string, value?: number|null): this` — Update message and/or value.
- `increment(): this` — Increment value by 1.
- `stop(endMessage?: string): void` — Stop the logger and restore console output.

## Notes

- Console methods (`log`, `warn`, `error`) are temporarily intercepted during determinate progress to keep the bar pinned while printing messages, then restored on `stop()`.
- Works in Node.js ≥ 16.

## License

MIT © 2025 Dean Schulz