{"id":40078076,"url":"https://github.com/andre487/node-console-progress-bar-tqdm","last_synced_at":"2026-01-19T09:03:29.421Z","repository":{"id":224143859,"uuid":"762374994","full_name":"andre487/node-console-progress-bar-tqdm","owner":"andre487","description":"Progress bar in console for Node.js in the style of TQDM Python library.","archived":false,"fork":false,"pushed_at":"2024-03-01T11:01:01.000Z","size":509,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-31T06:25:57.530Z","etag":null,"topics":["cli","cli-app","commonjs-modules","console","esmodules","for-await-of","indicator","iterate","iterator","loop","nodejs","nodejs-cli","progress","progress-bar","terminal","tqdm","typescript-library"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/node-console-progress-bar-tqdm","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andre487.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-23T16:42:46.000Z","updated_at":"2025-07-01T02:44:00.000Z","dependencies_parsed_at":"2024-03-01T11:31:51.954Z","dependency_job_id":null,"html_url":"https://github.com/andre487/node-console-progress-bar-tqdm","commit_stats":{"total_commits":68,"total_committers":1,"mean_commits":68.0,"dds":0.0,"last_synced_commit":"610ab9072cedfe0ca64520efc17c7afcee48f97c"},"previous_names":["andre487/node-console-progress-bar-tqdm"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/andre487/node-console-progress-bar-tqdm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre487%2Fnode-console-progress-bar-tqdm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre487%2Fnode-console-progress-bar-tqdm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre487%2Fnode-console-progress-bar-tqdm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre487%2Fnode-console-progress-bar-tqdm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andre487","download_url":"https://codeload.github.com/andre487/node-console-progress-bar-tqdm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andre487%2Fnode-console-progress-bar-tqdm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28565001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T08:53:44.001Z","status":"ssl_error","status_checked_at":"2026-01-19T08:52:40.245Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-app","commonjs-modules","console","esmodules","for-await-of","indicator","iterate","iterator","loop","nodejs","nodejs-cli","progress","progress-bar","terminal","tqdm","typescript-library"],"created_at":"2026-01-19T09:03:28.808Z","updated_at":"2026-01-19T09:03:29.415Z","avatar_url":"https://github.com/andre487.png","language":"TypeScript","readme":"# TQDM-like progress bar for Node.js console applications\n\nFull name: `node-console-progress-bar-tqdm`\n\n[![Test commit](https://github.com/andre487/node-console-progress-bar-tqdm/actions/workflows/test-commit.yml/badge.svg)](https://github.com/andre487/node-console-progress-bar-tqdm/actions/workflows/test-commit.yml)\n[![Downloads](https://img.shields.io/npm/dm/node-console-progress-bar-tqdm.svg?style=flat-square)](https://www.npmjs.com/package/node-console-progress-bar-tqdm)\n[![NPM Version](https://img.shields.io/npm/v/node-console-progress-bar-tqdm.svg?style=flat-square)](https://www.npmjs.com/package/node-console-progress-bar-tqdm)\n\nThis is a library that implements progress bar in console for Node.js in the style of\n[tqdm](https://tqdm.github.io/) Python library.\n\nThis library implements very similar interface and options set.\n\nLanguage support: TypeScript and JavaScript with CommonJS and EcmaScript modules.\n\nInput data support: `Array`, `Number`, `Generator`, `AsyncGenerator`, `Iterable`, `Iterator`, `AsyncIterable`, `AsyncIterator`.\nWhen `Number` is passed as an input, there will be iterations over a range from 0 to this number.\n\nTested on Linux, macOS and Windows.\n\nNode.js 16+ is required.\n\n## Table of contents\n\n  * [How does it look?](#how-does-it-look)\n  * [Quick examples](#quick-examples)\n  * [Installation](#installation)\n  * [Quick reference](#quick-reference)\n  * [Examples](#examples)\n\n## How does it look?\n\n```\n  50% |████████████████████████████████████████████████                                                 |  50/100 [00:01.630\u003c00:01.630, 0.033s/it]\n```\n\nhttps://github.com/andre487/node-console-progress-bar-tqdm/assets/1009104/afac1fe2-da92-433f-8791-4754f736feab\n\n## Quick examples\n\n```ts\nimport {tqdm, TqdmProgress} from 'node-console-progress-bar-tqdm';\n\n// Array as Iterable with length\nfor (const item: number of tqdm([1, 2, 3, 4, 5])) {\n    doSomeWorkOn(item);\n}\n\n// Number generates range\nfor (const idx: number of tqdm(100_000)) {\n    doSomeWorkOn(idx);\n}\n\n// Generator as Iterable without length\nconst inp1: Generator\u003cItem\u003e = itemGenerator();\nfor (const item: Item of tqdm(inp1)) {\n    doSomeWorkOn(item);\n}\n\n// AsyncGenerator as AsyncIterable\nconst inp2: AsyncGenerator\u003cItem\u003e = itemAsyncGenerator();\nfor await (const item: Item of tqdm(inp2, {total: 100})) {\n    doSomeWorkOn(item);\n}\n\n// Progress bar without using in a loop directly\nconst pb = new TqdmProgress({\n    total: items.length,\n    progressColor: '#f1d3c4',\n});\n// render the empty progress bar\npb.render();\nitems.forEach((item) =\u003e {\n    doSomeWorkOn(item);\n    // update progress bar by 1 item\n    progressBar.update();\n});\n// force render for printing delayed symbols and other finalization (not required)\npb.close();\n\n// Progress bar without using in a loop but with suitable wrapper with automatic opening and closing\nconst res1 = TqdmProgress.withProgress((progressBar) =\u003e {\n    return items.map((item) =\u003e {\n        const res = doSomeWorkOn(item);\n        // update progress bar by 1 item\n        progressBar.update();\n        return res;\n    });\n}, {total: items.length, progressColor: '$128'});\nhandleResult(res1);\n\n// An async version of the previous case\nconst res2 = await TqdmProgress.withAsyncProgress(async (progressBar) =\u003e {\n    const res: HandledItem[] = [];\n    for await (const item of getAsyncItems()) {\n        res.push(await doSomeWorkOn(item));\n        // update progress bar by 1 item\n        progressBar.update();\n    }\n    return res;\n}, {total: estimateItemsCount(), progressColor: '$200'});\nhandleResult(res2);\n```\n\n## Installation\n\n```shell\nnpm install --save node-console-progress-bar-tqdm\nyarn add node-console-progress-bar-tqdm\npnpm install node-console-progress-bar-tqdm\n```\n\n## Quick reference\n\nThis is a quick API reference. It's useful to look to some examples that are below.\n\n```ts\n// When using custom unit names, different forms of unir name could be passed.\nexport type TqdmUnitTable = Record\u003cIntl.LDMLPluralRule, string\u003e;\nexport type TqdmUnitOption = string | [string, string] | TqdmUnitTable;\n\nexport type TqdmOptions = {\n    // Description, the prefix for the progress bar.\n    description?: string;\n\n    // The width of the entire output message.\n    // By default, the output fills whole the line.\n    maxColWidth?: number;\n\n    // \"Braces\" around the progress bar.\n    // Default: [\"|\", \"|\"].\n    progressBraces?: [string, string];\n\n    // Symbol for building the progress bar.\n    // Default: \"█\".\n    progressSymbol?: string;\n\n    // Color of the progress bar in terminal format.\n    // If it's not set will be color by default.\n    // This value is corresponding to ANSI format: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors\n    // Examples:\n    //   1. 4-bit (8) colors: \"black\", \"red\", …, \"white\".\n    //   2. 8-bit (256) colors, prefix \"$\": \"$16\", \"$17\", …, \"$255\".\n    //   3. 24-bit colors: \"#ccc\", \"#00ff12\" – CSS-like color literal.\n    progressColor?: string;\n\n    // Counter initial value.\n    // Default: 0.\n    initial?: number;\n\n    // The number of expected iterations.\n    // If not specified and `input` has `length`, `input.length` will be used.\n    // If `input` is number, this number will be used.\n    total?: number;\n\n    // Step of the progress.\n    // Default: 1.\n    step?: number;\n\n    // Value that will be used to define the unit of each iteration.\n    // It can be a string: \"thing\", a tuple: [\"one thing\", \"many things\"]\n    // or a table:\n    // {\n    //   \"zero\":  \"0 things\",\n    //   \"one\":   \"1 thing\",\n    //   \"two\":   \"2 things\",\n    //   \"few\":   \"few things\",\n    //   \"many\":  \"many things\",\n    //   \"other\": \"some things\"\n    // }\n    // Default: \"it\".\n    unit?: TqdmUnitOption;\n\n    // If true, the number of iterations will be reduced/scaled\n    // automatically and a metric prefix following the\n    // International System of Units standard will be added\n    // (kilo, mega, etc.).\n    // Default: false.\n    unitScale?: boolean;\n\n    // Stream to write the progress bar.\n    // Default: `process.stderr`.\n    stream?: NodeJS.WritableStream,\n\n    // Minimum progress display update interval in milliseconds.\n    // Default: 50ms.\n    minInterval?: number;\n\n    // Force output like the stream is a terminal.\n    // Try to emulate the terminal behavior.\n    forceTerminal?: boolean;\n};\n\n// Input type of the library main method.\n// It means that Array, Generator and AsyncGenerator can be used as well as these generic types.\nexport type TqdmInput = Iterable\u003cunknown\u003e |\n    Iterator\u003cunknown\u003e |\n    AsyncIterable\u003cunknown\u003e |\n    AsyncIterator\u003cunknown\u003e |\n    number;\n\n// The main method that generated progress bar with an original data iterator.\nexport declare function tqdm\u003cTInput extends TqdmInput\u003e(input: TInput, opts?: TqdmOptions): Tqdm\u003cTInput\u003e;\n\n// The main class thar implements the iterator over rhe original data and progress bar rendering.\nexport declare class Tqdm\u003cTInput extends TqdmInput\u003e implements Iterable\u003cTqdmItem\u003cTInput\u003e\u003e, AsyncIterable\u003cTqdmItem\u003cTInput\u003e\u003e, ITqdmSyncIteratorContainer\u003cTqdmItem\u003cTInput\u003e\u003e, ITqdmAsyncIteratorContainer\u003cTqdmItem\u003cTInput\u003e\u003e {\n    constructor(input: TInput, options?: TqdmOptions);\n    [Symbol.iterator](): TqdmSyncResultIteratorReturn\u003cTInput\u003e;\n    [Symbol.asyncIterator](): TqdmAsyncResultIteratorReturn\u003cTInput\u003e;\n    nextSync(): TqdmIteratorResultSync\u003cTInput\u003e;\n    nextAsync(): TqdmIteratorResultAsync\u003cTInput\u003e;\n}\n\n// Progress bar class.\n// Can be used when there is no need for iterator over originall data.\nexport declare class TqdmProgress implements ITqdmProgress {\n    constructor(options: TqdmOptions);\n    update(by?: number): void;\n    render(force?: boolean): void;\n    close(): void;\n}\n```\n\n## Examples\n\nIn these examples, besides the main goal, different input collections are illustrated\nas well as different module types: TypeScript, EcmaScript modules, CommonJS modules.\n\nYou can run these examples from this repository:\n\n```shell\ncd example\nnpm ci\nnpm start\n```\n\n| File | Title | Description | Tags |\n| ---- | ----- | ----------- | ---- |\n| [basic.cjs](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/basic.cjs) | Basic example | Iterate over an array without any options | `CJS`, `Array`, `defaults` |\n| [generator.mjs](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/generator.mjs) | Generator examples | A couple of examples where we iterate over generator | `ESM`, `Generator`, `with/without total` |\n| [countdown.mjs](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/countdown.mjs) | Countdown | Countdown, progress bar changes from full to empty | `ESM`, `Iterator`, `countdown` |\n| [unit-scaling.cjs](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/unit-scaling.cjs) | Unit scaling, range iteration | Example with iteration over number range defined by `total` with unit scaling (k,M,G,T) | `CJS`, `Number`, `units`, `unit scaling` |\n| [custom-progress-bar.mts](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/custom-progress-bar.mts) | Custom progress style | Fully customized progress bar written on TypeScript | `TS`, `Generator`, `units`, `color`, `styling`, `max width` |\n| [sync-iterator-input.mts](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/sync-iterator-input.mts) | Iteration over sync iterator | Example with Iterator and Iterable as input | `TS`, `Iterable`, `color`, `styling` |\n| [async-iterator-input.mts](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/async-iterator-input.mts) | Iteration over async iterator | Example with AsyncIterator and AsyncIterable as input | `TS`, `AsyncIterable`, `async`, `for/await`, `color`, `styling` |\n| [progress-with-no-iteration.cjs](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/progress-with-no-iteration.cjs) | Using progress bar directly | There is no iteration over tqdm iterator, direct TqdmProgress usage. Progress split to 2 parts | `CJS`, `TqdmProgress`, `no tqdm()`, `flush output`, `resuming`, `color` |\n| [progress-with-no-iteration-ctx.mts](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/progress-with-no-iteration-ctx.mts) | Using progress bar through context helpers | There is no tqdm function, using withProgress and withAsyncProgress helpers | `TS`, `TqdmProgress`, `withProgress`, `withAsyncProgress`, `no tqdm()`, `color`, `styling`, `emoji` |\n| [direct-iteration.mts](https://github.com/andre487/node-console-progress-bar-tqdm/blob/main/example/examples/direct-iteration.mts) | Direct usage of Tqdm class | Very advanced example with direct Tqdm usage | `TS`, `Generator`, `AsyncGenerator`, `async`, `async/await`, `no loop`, `units`, `color`, `styling` |\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandre487%2Fnode-console-progress-bar-tqdm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandre487%2Fnode-console-progress-bar-tqdm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandre487%2Fnode-console-progress-bar-tqdm/lists"}