wukong-progress 0.1.1 → 0.1.2

package/README.md

@@ -1,219 +1,254 @@
-# wukong-progress
-
-🎨 A Node.js / ESM style CLI progress bar library that supports:
-
-- Single / multiple progress bars
-- Group / Stage / prefix
-- Concurrent task API (wrap async functions)
-- Automatic terminal width adaptation
-- Optional colored output (chalk, auto fallback)
-- JSON fallback (for non-TTY environments)
-- Full ESM + Node.js 18+ compatible
-- Works on Windows / Linux / macOS
-
----
-## English | [简体中文](./README.zh-CN.md)
----
-## 🚀 Installation
-
-```bash
-yarn add wukong-progress chalk
-# or
-npm install wukong-progress chalk
-```
-
----
-
-## ⚡️ Basic Usage
-
-### Single Progress Bar
-
-```js
-import chalk from "chalk";
-import { createMultiBar } from "wukong-progress";
-
-const mb = createMultiBar();
-const bar = mb.create(100, {
-  prefix: chalk.cyan("Build"),
-  format: "Build [:bar] :percent :current/:total",
-});
-
-async function run() {
-  for (let i = 0; i <= 100; i++) {
-    await new Promise((r) => setTimeout(r, 20));
-    bar.tick();
-  }
-  mb.stop();
-  console.log(chalk.green("\nDone!\n"));
-}
-
-run();
-```
-
-### Multiple Progress Bars
-
-```js
-import chalk from "chalk";
-import { createMultiBar } from "wukong-progress";
-
-const mb = createMultiBar();
-const build = mb.create(100, {
-  prefix: chalk.blue("Build"),
-  format: "Build [:bar] :percent",
-});
-const test = mb.create(50, {
-  prefix: chalk.magenta("Test"),
-  format: "Test  [:bar] :percent",
-});
-
-async function run() {
-  for (let i = 0; i <= 100; i++) {
-    await new Promise((r) => setTimeout(r, 15));
-    if (i <= 50) test.tick();
-    build.tick();
-  }
-  mb.stop();
-  console.log(chalk.green("\nAll tasks done!\n"));
-}
-
-run();
-```
-
----
-
-### Group / Stage / prefix
-
-```js
-import chalk from "chalk";
-import { createMultiBar } from "wukong-progress";
-
-const mb = createMultiBar();
-const buildGroup = mb.group("Build Group");
-buildGroup.create(50, {
-  prefix: chalk.blue("Compile"),
-  format: "Compile [:bar] :percent",
-});
-buildGroup.create(30, {
-  prefix: chalk.cyan("Bundle"),
-  format: "Bundle  [:bar] :percent",
-});
-
-const testGroup = mb.group("Test Group");
-testGroup.create(20, {
-  prefix: chalk.magenta("Unit"),
-  format: "Unit [:bar] :percent",
-});
-testGroup.create(10, {
-  prefix: chalk.yellow("E2E"),
-  format: "E2E  [:bar] :percent",
-});
-
-async function run() {
-  const allTasks = [...buildGroup.bars, ...testGroup.bars];
-
-  for (let i = 0; i < 50; i++) {
-    await new Promise((r) => setTimeout(r, 20));
-    allTasks.forEach((bar) => {
-      if (!bar.state.complete) bar.tick();
-    });
-  }
-
-  mb.stop();
-  console.log(chalk.green("\nGroups completed!\n"));
-}
-
-run();
-```
-
----
-
-### JSON Fallback (non-TTY / CI)
-
-```js
-import { Writable } from "node:stream";
-import { createMultiBar } from "wukong-progress";
-
-let out = "";
-const stream = new Writable({
-  write(chunk, _, cb) {
-    out += chunk;
-    cb();
-  },
-});
-
-const mb = createMultiBar({ stream, json: true });
-const bar = mb.create(5, { prefix: "JSON" });
-
-async function run() {
-  for (let i = 0; i <= 5; i++) {
-    await new Promise((r) => setTimeout(r, 20));
-    bar.tick();
-  }
-  mb.stop();
-
-  console.log("JSON fallback output:");
-  console.log(out);
-}
-
-run();
-```
-
----
-
-## 🎨 Colored Output (optional)
-
-- Use `chalk` to color prefixes and bar output
-- Auto fallback to plain text if chalk is not installed
-- Example:
-
-```js
-prefix: chalk.green('Build'),
-format: chalk.green('Build [:bar] :percent')
-```
-
----
-
-## 📂 Examples Folder
-
-```bash
-node examples/index.mjs
-```
-
-- Interactive selection of examples:
-
-  - Single Bar
-  - Multi Bar
-  - Group / Stage
-  - JSON Fallback
-
-- Fully compatible with Windows / Linux / macOS
-- All examples use async/await + chalk colored output
-
----
-
-## ⚡️ Testing
-
-```bash
-# Node.js native test
-yarn test:node
-
-# Vitest snapshot test
-yarn test:vitest
-
-# Run all tests
-yarn test
-```
-
-- ✅ Node:test for progress logic
-- ✅ Vitest snapshot for rendering stability
-- ✅ Supports mock TTY / ANSI strip / JSON fallback
-
----
-
-## 💻 Use Cases
-
-- CLI tools
-- Automation scripts
-- GitHub Actions / CI
-- Concurrent task visualization
-- Progress visualization + JSON logging for analytics
+# wukong-progress
+
+🎨 A Node.js / ESM style CLI progress bar library that supports:
+
+- Single / multiple progress bars
+- Group / Stage / prefix
+- Concurrent task API (wrap async functions)
+- Automatic terminal width adaptation
+- Optional colored output (chalk, auto fallback)
+- JSON fallback (for non-TTY environments)
+- Full ESM + Node.js 18+ compatible
+- Works on Windows / Linux / macOS
+
+---
+## English | [简体中文](./README.zh-CN.md)
+---
+## 🚀 Installation
+
+```bash
+yarn add wukong-progress chalk
+# or
+npm install wukong-progress chalk
+```
+
+---
+
+## ⚡️ Basic Usage
+
+### Single Progress Bar
+
+```js
+import chalk from "chalk";
+import { createMultiBar } from "wukong-progress";
+
+const mb = createMultiBar();
+const bar = mb.create(100, {
+  prefix: chalk.cyan("Build"),
+  format: "Build [:bar] :percent :current/:total",
+});
+
+async function run() {
+  for (let i = 0; i <= 100; i++) {
+    await new Promise((r) => setTimeout(r, 20));
+    bar.tick();
+  }
+  mb.stop();
+  console.log(chalk.green("\nDone!\n"));
+}
+
+run();
+```
+
+### Multiple Progress Bars
+
+```js
+import chalk from "chalk";
+import { createMultiBar } from "wukong-progress";
+
+const mb = createMultiBar();
+const build = mb.create(100, {
+  prefix: chalk.blue("Build"),
+  format: "Build [:bar] :percent",
+});
+const test = mb.create(50, {
+  prefix: chalk.magenta("Test"),
+  format: "Test  [:bar] :percent",
+});
+
+async function run() {
+  for (let i = 0; i <= 100; i++) {
+    await new Promise((r) => setTimeout(r, 15));
+    if (i <= 50) test.tick();
+    build.tick();
+  }
+  mb.stop();
+  console.log(chalk.green("\nAll tasks done!\n"));
+}
+
+run();
+```
+
+### Step with Payload
+
+Update progress with a descriptive payload message.
+
+```js
+import chalk from 'chalk'
+import { createMultiBar } from '../src/index.mjs'
+
+const mb = createMultiBar()
+
+const build = mb.create(100, {
+  prefix: chalk.blue('Build'),
+  format: 'Build [:bar] :percent :payload'
+})
+const test = mb.create(50, {
+  prefix: chalk.magenta('Test'),
+  format: 'Test  [:bar] :percent'
+})
+
+async function run() {
+  for (let i = 0; i <= 100; i++) {
+    await new Promise((r) => setTimeout(r, 15))
+    if (i <= 50) test.tick()
+    build.step(5, 'Extracting Git history...')
+    build.step(5, 'Parsing commits...')
+    build.step(5, 'Generating Changelog...')
+    build.step(5, 'Generating Release Info...')
+  }
+  mb.stop()
+  console.log(chalk.green('\nAll tasks done!\n'))
+}
+
+run()
+```
+
+---
+
+### Group / Stage / prefix
+
+```js
+import chalk from "chalk";
+import { createMultiBar } from "wukong-progress";
+
+const mb = createMultiBar();
+const buildGroup = mb.group("Build Group");
+buildGroup.create(50, {
+  prefix: chalk.blue("Compile"),
+  format: "Compile [:bar] :percent",
+});
+buildGroup.create(30, {
+  prefix: chalk.cyan("Bundle"),
+  format: "Bundle  [:bar] :percent",
+});
+
+const testGroup = mb.group("Test Group");
+testGroup.create(20, {
+  prefix: chalk.magenta("Unit"),
+  format: "Unit [:bar] :percent",
+});
+testGroup.create(10, {
+  prefix: chalk.yellow("E2E"),
+  format: "E2E  [:bar] :percent",
+});
+
+async function run() {
+  const allTasks = [...buildGroup.bars, ...testGroup.bars];
+
+  for (let i = 0; i < 50; i++) {
+    await new Promise((r) => setTimeout(r, 20));
+    allTasks.forEach((bar) => {
+      if (!bar.state.complete) bar.tick();
+    });
+  }
+
+  mb.stop();
+  console.log(chalk.green("\nGroups completed!\n"));
+}
+
+run();
+```
+
+---
+
+### JSON Fallback (non-TTY / CI)
+
+```js
+import { Writable } from "node:stream";
+import { createMultiBar } from "wukong-progress";
+
+let out = "";
+const stream = new Writable({
+  write(chunk, _, cb) {
+    out += chunk;
+    cb();
+  },
+});
+
+const mb = createMultiBar({ stream, json: true });
+const bar = mb.create(5, { prefix: "JSON" });
+
+async function run() {
+  for (let i = 0; i <= 5; i++) {
+    await new Promise((r) => setTimeout(r, 20));
+    bar.tick();
+  }
+  mb.stop();
+
+  console.log("JSON fallback output:");
+  console.log(out);
+}
+
+run();
+```
+
+---
+
+## 🎨 Colored Output (optional)
+
+- Use `chalk` to color prefixes and bar output
+- Auto fallback to plain text if chalk is not installed
+- Example:
+
+```js
+prefix: chalk.green('Build'),
+format: chalk.green('Build [:bar] :percent')
+```
+
+---
+
+## 📂 Examples Folder
+
+```bash
+node examples/index.mjs
+```
+
+- Interactive selection of examples:
+
+  - Single Bar
+  - Multi Bar
+  - Group / Stage
+  - JSON Fallback
+
+- Fully compatible with Windows / Linux / macOS
+- All examples use async/await + chalk colored output
+
+---
+
+## ⚡️ Testing
+
+```bash
+# Node.js native test
+yarn test:node
+
+# Vitest snapshot test
+yarn test:vitest
+
+# Run all tests
+yarn test
+```
+
+- ✅ Node:test for progress logic
+- ✅ Vitest snapshot for rendering stability
+- ✅ Supports mock TTY / ANSI strip / JSON fallback
+
+---
+
+## 💻 Use Cases
+
+- CLI tools
+- Automation scripts
+- GitHub Actions / CI
+- Concurrent task visualization
+- Progress visualization + JSON logging for analytics

package/README.zh-CN.md

@@ -11,7 +11,7 @@
 - JSON fallback（非 TTY）
 - 完全 ESM + Node.js 18+ 兼容
 - 可在 Windows / Linux / macOS 使用
-  
+
 ---
 ## 中文 | [English](./README.md)
 ---
@@ -72,6 +72,41 @@ async function run() {
 run()
 ```
 
+### 带文字提示的步骤更新
+
+使用 `step` 方法可以在更新进度的同时附加描述性文字。
+
+```js
+import chalk from 'chalk'
+import { createMultiBar } from '../src/index.mjs'
+
+const mb = createMultiBar()
+
+const build = mb.create(100, {
+  prefix: chalk.blue('Build'),
+  format: 'Build [:bar] :percent :payload'
+})
+const test = mb.create(50, {
+  prefix: chalk.magenta('Test'),
+  format: 'Test  [:bar] :percent'
+})
+
+async function run() {
+  for (let i = 0; i <= 100; i++) {
+    await new Promise((r) => setTimeout(r, 15))
+    if (i <= 50) test.tick()
+    build.step(5, '正在提取 Git 提交记录...')
+    build.step(5, '正在解析提交记录...')
+    build.step(5, '正在生成 Changelog...')
+    build.step(5, '正在生成 Release 信息...')
+  }
+  mb.stop()
+  console.log(chalk.green('\nAll tasks done!\n'))
+}
+
+run()
+```
+
 ---
 
 ### Group / Stage / prefix
@@ -144,11 +179,11 @@ run()
 ## 🎨 彩色渲染（可选）
 
 -   使用 `chalk` 可以给 prefix、bar 和提示上色
-    
+
 -   不依赖彩色也能降级到普通文本
-    
+
 -   示例：
-    
+
 
 ```js
 prefix: chalk.green('Build'),
@@ -164,19 +199,19 @@ node examples/index.mjs
 ```
 
 -   交互式选择运行示例：
-    
+
     -   Single Bar
-        
+
     -   Multi Bar
-        
+
     -   Group / Stage
-        
+
     -   JSON Fallback
-        
+
 -   Windows / Linux / macOS 全平台兼容
-    
+
 -   所有示例都用 async/await + chalk 彩色渲染
-    
+
 
 ---
 
@@ -194,24 +229,24 @@ yarn test
 ```
 
 -   ✅ Node:test 测试进度条逻辑
-    
+
 -   ✅ Vitest snapshot 测试渲染稳定性
-    
+
 -   ✅ 支持 mock TTY / ANSI strip / JSON fallback
-    
+
 
 ---
 
 ## 💻 适用场景
 
 -   CLI 工具
-    
+
 -   自动化脚本
-    
+
 -   GitHub Actions / CI
-    
+
 -   多任务并发显示
-    
+
 -   可视化进度 / JSON 输出结合日志分析
-    
+
 

package/dist/index.mjs

@@ -31,6 +31,7 @@ function createBar(ctx, opts) {
     format: opts.format,
     minWidth: opts.minWidth ?? 10,
     prefix: opts.prefix ?? "",
+    payload: opts.payload ?? "",
     hideOnComplete: opts.hideOnComplete ?? false,
     complete: false
   };
@@ -44,10 +45,14 @@ function createBar(ctx, opts) {
   function tick(n = 1) {
     update(state.current + n);
   }
+  function step(n = 1, payload) {
+    state.payload = payload;
+    tick(n);
+  }
   function render(width) {
     const elapsed = (Date.now() - state.start) / 1e3;
     const percent = state.current / state.total;
-    const staticLen = state.format.replace(":bar", "").replace(":percent", "100%").replace(":current", state.total).replace(":total", state.total).replace(":eta", "00s").length;
+    const staticLen = state.format.replace(":bar", "").replace(":percent", "100%").replace(":current", state.total).replace(":total", state.total).replace(":payload", state.payload).replace(":eta", "00s").length;
     const barWidth = Math.max(
       state.minWidth,
       width - staticLen - state.prefix.length - 4
@@ -56,11 +61,12 @@ function createBar(ctx, opts) {
     const bar = color.bar("\u2588".repeat(filled)) + color.dim("\u2591".repeat(barWidth - filled));
     const rate = state.current / elapsed;
     const eta = rate ? (state.total - state.current) / rate : Infinity;
-    return (state.prefix ? `${state.prefix} ` : "") + state.format.replace(":bar", bar).replace(":percent", color.percent(`${Math.round(percent * 100)}%`)).replace(":current", state.current).replace(":total", state.total).replace(":elapsed", formatTime(elapsed)).replace(":eta", formatTime(eta));
+    return (state.prefix ? `${state.prefix} ` : "") + state.format.replace(":bar", bar).replace(":percent", color.percent(`${Math.round(percent * 100)}%`)).replace(":current", state.current).replace(":total", state.total).replace(":payload", state.payload).replace(":elapsed", formatTime(elapsed)).replace(":eta", formatTime(eta));
   }
   return {
     state,
     tick,
+    step,
     update,
     render
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wukong-progress",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Lightweight ESM CLI progress bar for Node.js with multiple bars, groups, stages and JSON fallback",
   "keywords": [
     "cli",

package/src/bar.mjs

@@ -9,6 +9,7 @@ export function createBar(ctx, opts) {
     format: opts.format,
     minWidth: opts.minWidth ?? 10,
     prefix: opts.prefix ?? '',
+    payload: opts.payload ?? '',
     hideOnComplete: opts.hideOnComplete ?? false,
     complete: false
   }
@@ -23,6 +24,12 @@ export function createBar(ctx, opts) {
     update(state.current + n)
   }
 
+  // eslint-disable-next-line default-param-last
+  function step(n = 1, payload) {
+    state.payload = payload
+    tick(n)
+  }
+
   function render(width) {
     const elapsed = (Date.now() - state.start) / 1000
     const percent = state.current / state.total
@@ -32,6 +39,7 @@ export function createBar(ctx, opts) {
       .replace(':percent', '100%')
       .replace(':current', state.total)
       .replace(':total', state.total)
+      .replace(':payload', state.payload)
       .replace(':eta', '00s').length
 
     const barWidth = Math.max(
@@ -53,6 +61,7 @@ export function createBar(ctx, opts) {
         .replace(':percent', color.percent(`${Math.round(percent * 100)}%`))
         .replace(':current', state.current)
         .replace(':total', state.total)
+        .replace(':payload', state.payload)
         .replace(':elapsed', formatTime(elapsed))
         .replace(':eta', formatTime(eta))
     )
@@ -61,6 +70,7 @@ export function createBar(ctx, opts) {
   return {
     state,
     tick,
+    step,
     update,
     render
   }

package/src/group.mjs

@@ -1,15 +1,15 @@
-export function createGroup(ctx, name) {
-  const bars = []
-
-  function create(total, opts = {}) {
-    const bar = ctx._createBar({
-      ...opts,
-      prefix: opts.prefix ?? name,
-      total,
-    })
-    bars.push(bar)
-    return bar
-  }
-
-  return { create, bars }
-}
+export function createGroup(ctx, name) {
+  const bars = []
+
+  function create(total, opts = {}) {
+    const bar = ctx._createBar({
+      ...opts,
+      prefix: opts.prefix ?? name,
+      total,
+    })
+    bars.push(bar)
+    return bar
+  }
+
+  return { create, bars }
+}

package/src/index.mjs

@@ -1 +1 @@
-export { createMultiBar } from './multibar.mjs'
+export { createMultiBar } from './multibar.mjs'

package/src/json.mjs

@@ -1,16 +1,16 @@
-export function renderJSON(stream, bars) {
-  const payload = {
-    type: 'progress',
-    bars: bars.map(b => ({
-      name: b.state.prefix,
-      current: b.state.current,
-      total: b.state.total,
-      percent: Math.round(
-        (b.state.current / b.state.total) * 100
-      ),
-      complete: b.state.complete,
-    })),
-  }
-
-  stream.write(`${JSON.stringify(payload)  }\n`)
-}
+export function renderJSON(stream, bars) {
+  const payload = {
+    type: 'progress',
+    bars: bars.map(b => ({
+      name: b.state.prefix,
+      current: b.state.current,
+      total: b.state.total,
+      percent: Math.round(
+        (b.state.current / b.state.total) * 100
+      ),
+      complete: b.state.complete,
+    })),
+  }
+
+  stream.write(`${JSON.stringify(payload)  }\n`)
+}

package/src/utils/wait.mjs

@@ -0,0 +1 @@
+export const wait = (time) => new Promise((res) => {setTimeout(res, time)})