@1-/bar 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+[English](#en) | [中文](#zh)
+
+---
+
+<a id="en"></a>
+# @1-/bar : TTY-aware command-line progress bar and status display
+
+- [@1-/bar : TTY-aware command-line progress bar and status display](#1-bar-tty-aware-command-line-progress-bar-and-status-display)
+  - [Functionality](#functionality)
+  - [Usage demonstration](#usage-demonstration)
+  - [Design rationale](#design-rationale)
+  - [Technology stack](#technology-stack)
+  - [Code structure](#code-structure)
+  - [Historical background](#historical-background)
+  - [About](#about)
+
+## Functionality
+TTY-aware command-line progress bar and status display utility for Node.js applications. Provides spinner animation, task tracking, ETA estimation, and safe logging that doesn't disrupt the display.
+
+## Usage demonstration
+```bash
+npm install @1-/bar
+```
+
+```javascript
+import bar from '@1-/bar';
+
+const [start, stop, incr, log] = bar();
+
+// Start progress bar with total tasks
+start(100);
+
+// Log subtasks
+log.start('Processing files');
+
+// Increment progress
+for (let i = 0; i < 100; i++) {
+  incr();
+  // Simulate work
+  await new Promise(resolve => setTimeout(resolve, 10));
+}
+
+log.end('Processing files');
+stop();
+```
+
+## Design rationale
+The implementation uses terminal escape sequences for efficient rendering without disrupting the display. It maintains state for progress tracking, task management, and timing calculations for ETA estimation.
+
+![](https://fastly.jsdelivr.net/gh/webc-fs/-@2C/CVgwpu5Bvif7s62m-qAw.svg)
+
+## Technology stack
+- Node.js runtime
+- Standard JavaScript modules
+- Terminal escape sequences for TTY control
+- Set data structure for task tracking
+
+## Code structure
+```
+src/
+├── _.js          # Main module exporting progress utilities
+```
+
+## Historical background
+The Mulan Public Software License (MulanPSL) is an open-source license developed in China, designed to be compatible with international open-source practices while addressing local legal requirements. Version 2.0, released in 2020, improved compatibility with other licenses and clarified terms for patent grants and trademark usage.
+
+## About
+
+This library is developed by [WebC.site](https://webc.site).
+
+[WebC.site](https://webc.site): A new paradigm of web development for AI
+
+
+---
+
+<a id="zh"></a>
+# @1-/bar : TTY 感知的命令行进度条及状态显示
+
+- [@1-/bar : TTY 感知的命令行进度条及状态显示](#1-bar-tty-感知的命令行进度条及状态显示)
+  - [功能介绍](#功能介绍)
+  - [使用演示](#使用演示)
+  - [设计思路](#设计思路)
+  - [技术栈](#技术栈)
+  - [代码结构](#代码结构)
+  - [历史故事](#历史故事)
+  - [关于](#关于)
+
+## 功能介绍
+TTY 感知的命令行进度条及状态显示工具，适用于 Node.js 应用程序。提供旋转动画、任务跟踪、ETA 预估及安全日志输出功能，确保日志不会破坏进度条显示。
+
+## 使用演示
+```bash
+npm install @1-/bar
+```
+
+```javascript
+import bar from '@1-/bar';
+
+const [start, stop, incr, log] = bar();
+
+// 启动进度条并设置总任务数
+start(100);
+
+// 记录子任务
+log.start('处理文件');
+
+// 增加已完成任务数
+for (let i = 0; i < 100; i++) {
+  incr();
+  // 模拟工作
+  await new Promise(resolve => setTimeout(resolve, 10));
+}
+
+log.end('处理文件');
+stop();
+```
+
+## 设计思路
+实现采用终端转义序列进行高效渲染，避免显示中断。维护进度跟踪、任务管理及时间计算状态，支持 ETA（预估完成时间）估算。
+
+![](https://fastly.jsdelivr.net/gh/webc-fs/-@HQ/cbaDLo0WM3BrA4innS6Q.svg)
+
+## 技术栈
+- Node.js 运行时
+- 标准 JavaScript 模块
+- 终端转义序列实现 TTY 控制
+- Set 数据结构进行任务跟踪
+
+## 代码结构
+```
+src/
+├── _.js          # 主模块，导出进度工具函数
+```
+
+## 历史故事
+木兰公共许可证（MulanPSL）是中国开发的开源许可证，旨在兼容国际开源实践同时满足本地法律要求。2.0 版本于 2020 年发布，提升了与其他许可证的兼容性，并明确了专利授权和商标使用条款。
+
+## 关于
+
+本库由 [WebC.site](https://webc.site) 开发。
+
+[WebC.site](https://webc.site) : 面向人工智能的网站开发新范式
+

package/_.js

@@ -0,0 +1,111 @@
+/*
+命令行任务进度及状态显示器
+返回值: [start, stop, incr, log]
+  start: (total) => void 开始进度条，设置总任务数
+  stop: () => void 停止进度条
+  incr: () => void 增加已完成任务数
+  log: (...args) => void 安全输出日志，不破坏进度条
+    log.start: (task) => void 开始子任务
+    log.end: (task) => void 结束子任务
+*/
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  { stdout } = process,
+  IS_TTY = stdout.isTTY,
+  clear = IS_TTY
+    ? (n) => {
+        if (n > 0) {
+          stdout.write("\r\x1b[" + n + "A\x1b[J");
+        }
+        return 0;
+      }
+    : () => 0;
+
+export default () => {
+  const running = new Set();
+  let done = 0,
+    total = 0,
+    last_n = 0,
+    start_at = 0,
+    spin_idx = 0,
+    timer = null;
+
+  const format = (secs) => {
+      if (secs < 0 || !isFinite(secs)) {
+        return;
+      }
+      const m = Math.floor(secs / 60),
+        s = secs % 60;
+      return (m < 10 ? "0" : "") + m + ":" + (s < 10 ? "0" : "") + s;
+    },
+    render = () => {
+      if (!IS_TTY) {
+        return;
+      }
+      last_n = clear(last_n);
+      const lines = [];
+      if (total > 0) {
+        const pct = Math.round((done / total) * 100);
+        let eta;
+        if (done > 0) {
+          const elapsed = Date.now() - start_at,
+            avg = elapsed / done;
+          eta = format(Math.round(((total - done) * avg) / 1000));
+        }
+        lines.push(done + "/" + total + " (" + pct + "%) " + (eta ? "ETA " + eta : ""));
+      }
+      for (const task of running) {
+        lines.push(SPINNER[spin_idx] + " " + task);
+      }
+      if (lines.length > 0) {
+        lines.unshift("");
+        stdout.write("\r" + lines.join("\n") + "\n");
+        last_n = lines.length;
+      } else {
+        last_n = 0;
+      }
+    },
+    log = (...args) => {
+      last_n = clear(last_n);
+      console.log(...args);
+      render();
+    },
+    start = (val) => {
+      total = val;
+      done = 0;
+      start_at = Date.now();
+      if (IS_TTY) {
+        timer = setInterval(() => {
+          spin_idx = (spin_idx + 1) % SPINNER.length;
+          render();
+        }, 80);
+      }
+      render();
+    },
+    stop = () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      last_n = clear(last_n);
+      if (!IS_TTY && total > 0) {
+        console.log(done + "/" + total);
+      }
+    },
+    incr = () => {
+      ++done;
+      render();
+    };
+
+  log.start = (task) => {
+    running.add(task);
+    render();
+  };
+
+  log.end = (task) => {
+    running.delete(task);
+    render();
+  };
+
+  return [start, stop, incr, log];
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@1-/bar",
+  "version": "0.1.0",
+  "description": "TTY-aware command-line progress bar and status display utility",
+  "description_zh": "TTY 感知的命令行进度条及状态显示工具",
+  "keywords": [
+    "progress",
+    "bar",
+    "cli",
+    "tty",
+    "spinner"
+  ],
+  "homepage": "https://github.com/webc-site/npm/tree/main/bar",
+  "license": "MulanPSL-2.0",
+  "author": "x-at-01@googlegroups.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webc-site/npm.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./_.js",
+    "./*": "./*"
+  }
+}