bvaughn / progress-estimator

Logs a progress bar and estimation for how long a Promise will take to complete

progress-estimator

Logs a progress bar and estimation for how long a Promise will take to complete. This library tracks previous durations in order to provide more accurate estimates over time.

🎉 Become a sponsor or ☕ Buy me a coffee

Installation

# use npm
npm install progress-estimator

# use yarn
yarn add progress-estimator

Usage example

const createLogger = require('progress-estimator');
const { join } = require('path');

// All configuration keys are optional, but it's recommended to specify a storage location.
// Learn more about configuration options below.
const logger = createLogger({
  storagePath: join(__dirname, '.progress-estimator'),
});

async function run() {
  await logger(promiseOne, "This is a promise");
  await logger(
    promiseTwo,
    "This is another promise. I think it will take about 1 second",
    {
      estimate: 1000
    }
  );
}

API

createLogger(optionalConfiguration)

This method is the default package export. It creates and configures a logger function (documented below). The following configuration options are supported. (They apply only to the logger instance that's returned.)

name	type	Description
logFunction	Function	Custom logging function. Defaults to log-update. Must define .done() and .clear() methods.
spinner	object	Which spinner from the cli-spinners package to use. Defaults to dots.
storagePath	string	Where to record durations between runs. Defaults to os.tmpdir().
theme	object	Custom chalk theme. Look to the default theme for a list of required keys.

logger(promise, labelString, options)

This method logs a progress bar and estimated duration for a promise. It requires at least two parameters– a Promise and a label (e.g. "Running tests"). The label is SHA1 hashed in order to uniquely identify the promise.

An optional third parameter can be provided as well with the following keys:

name	type	Description
estimate	Number	Estimated duration of promise. (This value is used initially, until a history of actual durations have been recorded.)
id	String	Uniquely identifies the promise. This value is needed if the label string is not guaranteed to be unique.

progress-estimator's Issues

Suggestion: Add an explicit value to hash instead of relying on label

I'm using progress-estimator with an ESlint wrapper. The expected runtime is thus dependent on the number of files and can fluctuate a lot (eslint-wrapper singlefile.js vs. eslint-wrapper some/dir).

It'd be nice if the label could be consistent, while still having somewhat usable time estimates.

Suggestion: reduce dependencies by replacing chalk with colorette

Hello, @jorgebucaran created npm package that better than chalk. Its, faster, zero-dependency, blazing fast ;-D alternative.

https://github.com/jorgebucaran/colorette

Can this project use it instead of chalk?

setInterval timer isn't cleared when the promise rejects (in the catch)

https://github.com/bvaughn/progress-estimator/blob/c5bdf72/src/index.js#L70-L72

https://github.com/bvaughn/progress-estimator/blob/c5bdf72/src/index.js#L88-L92

Add github link to package.json

so source code shows up on https://www.npmjs.com/package/progress-estimator

0.3.0 Release?

Hi Brian,

I added progress-estimator to a little script I wrote around the same time you had initially shared it. I've (somewhat regretfully) been adding TypeScript support to my own script, and it looks like pulling progress-estimator from npm results in the 0.2.2 version that doesn't have some of the more recent commits to master.

I'm putting at the repo directly for now, but figured I'd open the issue in case it was of interest to you (or others). Thanks for the neat library!

How to make this work nicely with stdout from other processes?

I have this unfortunate behavior where the progress bar gets carried along with the other logs. Any ideas how I can fix this?

⠹ Building Client  0%                  0.0m, estimated 3.6m
ℹ ｢atl｣: Using [email protected] from typescript
⠼ Building Client  20%                 0.7m, estimated 3.6m
(node:42049) DeprecationWarning: Tapable.apply is deprecated. Call apply on the plugin directly instead
    at Object.pitch (/Users/chet/Code/notion-next/node_modules/worker-loader/dist/index.js:87:19)
    at LOADER_EXECUTION (/Users/chet/Code/notion-next/node_modules/loader-runner/lib/LoaderRunner.js:119:14)
    at runSyncOrAsync (/Users/chet/Code/notion-next/node_modules/loader-runner/lib/LoaderRunner.js:120:4)
    at /Users/chet/Code/notion-next/node_modules/loader-runner/lib/LoaderRunner.js:175:3
    at loadLoader (/Users/chet/Code/notion-next/node_modules/loader-runner/lib/loadLoader.js:36:3)
    at iteratePitchingLoaders (/Users/chet/Code/notion-next/node_modules/loader-runner/lib/LoaderRunner.js:169:2)
    at runLoaders (/Users/chet/Code/notion-next/node_modules/loader-runner/lib/LoaderRunner.js:362:2)
    at NormalModule.doBuild (/Users/chet/Code/notion-next/node_modules/webpack/lib/NormalModule.js:282:3)
    at NormalModule.build (/Users/chet/Code/notion-next/node_modules/webpack/lib/NormalModule.js:429:15)
    at Compilation.buildModule (/Users/chet/Code/notion-next/node_modules/webpack/lib/Compilation.js:369:10)
    at factory.create (/Users/chet/Code/notion-next/node_modules/webpack/lib/Compilation.js:596:14)
    at factory (/Users/chet/Code/notion-next/node_modules/webpack/lib/NormalModuleFactory.js:405:6)
    at hooks.afterResolve.callAsync (/Users/chet/Code/notion-next/node_modules/webpack/lib/NormalModuleFactory.js:155:13)
    at AsyncSeriesWaterfallHook.eval [as callAsync] (eval at create (/Users/chet/Code/notion-next/node_modules/tapable/lib/HookCodeFactory.js:32:10), <anonymous>:6:1)
    at resolver (/Users/chet/Code/notion-next/node_modules/webpack/lib/NormalModuleFactory.js:138:29)
    at process.nextTick (/Users/chet/Code/notion-next/node_modules/webpack/lib/NormalModuleFactory.js:342:9)
⠼ Building Client  67%                 2.4m, estimated 3.6m

Types seem pretty broken

The types seem to be wrong

The types export a bunch of things the library doesn't seem to export. Such as the configure function.

Here are the fixed types:

import { Chalk } from 'chalk';

export interface Spinner {
  interval: number;
  frames: string[];
}

export interface ChalkTheme extends Chalk {
  asciiCompleted: Chalk;
  asciiInProgress: Chalk;
  estimate: Chalk;
  estimateExceeded: Chalk;
  label: Chalk;
  percentage: Chalk;
  progressBackground: Chalk;
  progressForeground: Chalk;
}

export interface Configuration {
  spinner?: Spinner;
  storagePath?: string;
  theme?: ChalkTheme;
}

export type ProgressEstimator = <T>(
  promise: Promise<T>,
  label: string,
  estimatedDuration?: number
) => Promise<T>;

declare const configure: (options: Configuration) => ProgressEstimator;

export default configure;

Suggestion: return configurator, not mutate semi-globals

Your configure() code mutates some semi-global variables. It would be nicer for the end consumer to have the creation function return a new object bound to its own options, to potentially use more than one

Support JSDOC

Hi，bvaughn.

I want to add jsdoc descriptions to all files in this library, because even with ts namespace, type hints will still be lost in js, which is not very good DX. Can I hear your opinion, I'd love to add this feature.

Suggestion: allow parallel tracking of multiple tasks

Looks like this could be achieved by storing the previous estimates by some task identifier. See also #6

Suggestion: a way to inject a function instead of logUpdate

To integrate with listr where you can have many long tasks running in parallel and which uses its own renderer with log-update under the hood and provides a task.output abstraction to update the display, it would be beneficial to split this library's output string generation from printing/updating the terminal.

This can be simply done by providing a way to the caller of logProgress to replace logUpdate with a custom object provided via the logProgress arguments (potentially the fourth or the third should be the options object).