@qntm-code/progress-logger

A simple progress logger for Node.js that outputs progress and estimated time remaining to the console.

• @qntm-code/progress-logger
  • Installation
    • npm
    • yarn
  • Usage
    • Constructor Arguments
    • Methods
      • tick
      • dispose
    • Asynchronous Example
    • Synchronous example

Installation

You can install via npm or yarn.

npm

npm install --save @qntm-code/progress-logger

yarn

yarn add @qntm-code/progress-logger

Usage

Constructor Arguments

First you must create a new instance of the ProgressLogger class. The constructor takes the following arguments:

| Argument | Type | Description | | --------------------- | ---------------------------- | --------------------------------------------------------------------------------------- | | total | number | The total number of items to process. | | message | string | The message to display before the progress bar. | | bytes | Optional boolean | Whether the total is bytes. Will format output accordingly | | averageTimeSampleSize | Optional number | The number of items to use when calculating the average time per item. Defaults to 100. | | preventOverwrite | Optional boolean | Prevent overwriting the previous log of the bar | | logFunction | Optional (...args) => void | Provide a custom logging function | | throttleMs | Optional number | Minimum time (ms) between progress renders. Defaults to 0 (disabled). |

Note: if your processing loop finishes faster than throttleMs, you may only see the final "Finished …" log.

Methods

tick

Call tick on the ProgressLogger to notify the progress bar that item(s) have been processed. This method takes the following arguments:

| Argument | Type | Optional | Description | | -------- | ------ | -------- | ------------------------------------------------------------ | | amount | number | true | The number of items that were just processed (not the total) | | duration | number | true | The time taken to process the current item(s). |

If you don't pass a duration argument when calling tick, the average time will be calculated using the durations between each time tick is called. This is useful if you are processing items in batches as multiple items may be being processed at the same time.

dispose

If you want to stop using the ProgressLogger due to an error in your process, you must call dispose on the ProgressLogger instance to ensure the progress logger is disposed and prevent a memory leak. The ProgressLogger will automatically dispose itself if it reaches 100%.

Asynchronous Example

import { ProgressLogger } from '@qntm-code/progress-logger';

async function someAsyncProcess(): Promise<void> {
  // Do something
}

async function main(): Promise<void> {
  const itemsToProcess = [
    /* Some data */
  ];
  const total = itemsToProcess.length;

  const logger = new ProgressLogger({
    total,
    message: 'Processing',
    throttleMs: 100,
  });

  for (const item of itemsToProcess) {
    await someAsyncProcess();
    logger.tick();
  }
}

Synchronous example

import { ProgressLogger } from '@qntm-code/progress-logger';

function main(): void {
  const total = 100_000;
  const logger = new ProgressLogger({ total, message: 'Processing', throttleMs: 100 });

  for (let i = 0; i < total; i++) {
    // Do synchronous work
    logger.tick();
  }
}