@bettergi/utils 0.1.12 → 0.1.13

package/README.md

@@ -77,28 +77,24 @@ const t4 = findTextInDirection("师傅", "east", { contains: true, ignoreCase: t
 > 对脚本开发过程中常见工作流的抽象，例如: 等待/断言 操作/元素/区域 完成/出现/消失。
 
 ```ts
-// 等待直到找不到 [关闭按钮] ，重试5次，每隔1秒重试一次，期间按 Esc 键
+// 等待直到找不到 [关闭按钮] ，重试5次，每隔1秒重试一次（默认参数），期间按 Esc 键
 const done = await waitForAction(
   () => findImageInDirection("assets/关闭.png", "north-east") === undefined,
-  () => keyPress("ESCAPE"),
-  { maxAttempts: 5, retryInterval: 1000 }
+  () => keyPress("ESCAPE")
 );
 if (!done) throw new Error("关闭页面超时");
 
-// 断言 "生日" 文字区域即将出现，重试5次，每隔1秒重试一次，期间按 Esc 键
+// 断言 "生日" 文字区域即将出现，重试10次，每隔1秒重试一次，期间按 Esc 键
 await assertRegionAppearing(
   () => findTextInDirection("生日", "north-west"),
   "打开派蒙菜单超时",
   () => keyPress("ESCAPE"),
-  { maxAttempts: 5, retryInterval: 1000 }
+  { maxAttempts: 10, retryInterval: 1000 }
 );
 
-// 断言 "购买" 区域不存在，否则抛出异常，重试5次，每隔1秒重试一次，期间如果存在 "购买" 按钮则点击
+// 断言 "购买" 文字区域即将消失，重试5次，每隔1秒重试一次（默认参数），期间如果存在 "购买" 按钮则点击
 const findButton = () => findTextWithinBounds("购买", 500, 740, 900, 110);
-await assertRegionDisappearing(findButton, "点击购买按钮超时", () => findButton()?.click(), {
-  maxAttempts: 5,
-  retryInterval: 1000
-});
+await assertRegionDisappearing(findButton, "点击购买按钮超时", () => findButton()?.click());
 ```
 
 ### 鼠标操作
@@ -127,25 +123,52 @@ await mouseScrollDownLines(1, 115);
 
 ### 状态管理和持久化
 
-> 对象数据持久化，通过 Proxy 实现自动存储。从而可以无感知地读取/更新数据，而无需考虑如何持久化。
+> 基于深度 Proxy 实现的对象数据持久化，能够在数据被修改时自动同步至文件。使开发其能够像操作普通对象一样进行数据读写，而无需关心底层的持久化细节。
 
 ```ts
 // 创建/读取存储对象，保存到存储文件 store/my-data.json 中
-const state = useStore<{ lastUsedTime?: number; count: number }>("my-data");
+const store = useStore<{ lastUsedTime?: number; count: number }>("my-data");
 // 默认值版本
 // const state = useStoreWithDefaults("my-data", { lastUsedTime: 0, count: 0 });
 
-if (state?.lastUsedTime) {
-  log.info(`欢迎回来！上次使用时间: ${state.lastUsedTime}，计数器已累计至: ${state.count}`);
+if (store?.lastUsedTime) {
+  log.info(`欢迎回来！上次使用时间: ${store.lastUsedTime}，计数器已累计至: ${store.count}`);
 }
 try {
   // 模拟脚本运行期间状态的变化
   for (let i = 0; i < Math.floor(Math.random() * 100); i++) {
-    state.count = (state.count || 0) + 1; // 自动同步保存到文件
+    store.count = (store.count || 0) + 1; // 自动保存到文件
   }
 } finally {
-  state.lastUsedTime = Date.now(); // 自动同步保存到文件
+  store.lastUsedTime = Date.now(); // 自动保存到文件
+}
+```
+
+### 进度追踪
+
+> 创建进度追踪器并设置总进度，通过递进函数增加进度，开发者可以获取当前进度、当前耗时、平均耗时、预估剩余时间等数据。
+
+```ts
+const total = 100;
+// 创建进度追踪器，使用默认日志记录器（可配置），打印间隔最小3秒
+const tracker = new ProgressTracker(total, { interval: 3000 });
+for (let i = 0; i < total; i++) {
+  await sleep(Math.round(Math.random() * 200));
+  // 递进并尝试打印进度和消息
+  tracker.tick({ message: "等待任务完成..." });
+
+  // 也可以主动追踪，使用传递的进度信息自主控制打印时机和内容
+  // tracker.track((progress, shouldPrint, printed) => {
+  //   if (!shouldPrint()) return;
+  //   log.info(
+  //     "[进度: {pct} 预计剩余时间: {eta}]: 等待任务完成...",
+  //     progress.formatted.percentage,
+  //     progress.formatted.remaining
+  //   );
+  //   printed();
+  // });
 }
+tracker.complete(`执行完成`);
 ```
 
 ### 网络请求

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export * from "./misc";
 export * from "./mouse";
 /** 图像识别 */
 export * from "./ocr";
+/** 进度追踪 */
+export * from "./progress";
 /** 数据存储 */
 export * from "./store";
 /** 日期时间 */

package/dist/index.js

@@ -14,6 +14,8 @@ export * from "./misc";
 export * from "./mouse";
 /** 图像识别 */
 export * from "./ocr";
+/** 进度追踪 */
+export * from "./progress";
 /** 数据存储 */
 export * from "./store";
 /** 日期时间 */

package/dist/progress.d.ts

@@ -0,0 +1,56 @@
+/** 进度信息 */
+export type Progress = {
+    /** 当前进度 */
+    current: number;
+    /** 总进度 */
+    total: number;
+    /** 完成百分比 */
+    percentage: number;
+    /** 已用时间（毫秒） */
+    elapsed: number;
+    /** 平均每单位时间（毫秒） */
+    average: number;
+    /** 预计剩余时间（毫秒） */
+    remaining: number;
+    /** 格式化后的进度信息 */
+    formatted: {
+        percentage: string;
+        elapsed: string;
+        average: string;
+        remaining: string;
+    };
+};
+/** 进度日志记录器 */
+export type ProgressLogger = (message: string, progress: Progress) => void;
+export type ProgressTrackerConfig = {
+    /** 日志记录器 */
+    logger?: ProgressLogger;
+    /** 节流间隔（毫秒），默认3000 */
+    interval?: number;
+};
+/** 进度递进选项 */
+export type ProgressTickOptions = {
+    /** 递进后打印消息 */
+    message?: string;
+    /** 递进的幅度 */
+    increment?: number;
+};
+/** 进度追踪器 */
+export declare class ProgressTracker {
+    private total;
+    private current;
+    private startTime;
+    private readonly logger;
+    private readonly interval;
+    private lastPrintTime;
+    constructor(total: number, config?: ProgressTrackerConfig);
+    private readonly defaultLogger;
+    tick(options?: ProgressTickOptions): void;
+    track(callback: (progress: Progress, shouldPrint: () => boolean, printed: () => void) => void): void;
+    complete(message: string): void;
+    reset(): void;
+    private print;
+    private shouldPrint;
+    private printed;
+    getProgress(): Progress;
+}

package/dist/progress.js

@@ -0,0 +1,73 @@
+import { formatDurationAsClock, formatDurationAsReadable } from "./time";
+/** 进度追踪器 */
+export class ProgressTracker {
+    total = 0;
+    current = 0;
+    startTime = Date.now();
+    logger;
+    interval;
+    lastPrintTime = 0;
+    constructor(total, config) {
+        const { logger, interval: throttleInterval = 3000 } = config || {};
+        this.total = total;
+        this.logger = logger || this.defaultLogger;
+        this.interval = throttleInterval;
+    }
+    defaultLogger = (message, progress) => {
+        log.info("[🚧 {pct} ⏳ {eta}]: {msg}", progress.formatted.percentage.padStart(6), progress.current > 0 && progress.elapsed > 0 ? progress.formatted.remaining : "--:--:--", message);
+    };
+    tick(options) {
+        const { message, increment = 1 } = options || {};
+        this.current = Math.min(this.current + increment, this.total);
+        if (message)
+            this.print(message);
+    }
+    track(callback) {
+        const progress = this.getProgress();
+        const shouldPrint = this.shouldPrint.bind(this);
+        const printed = this.printed.bind(this);
+        callback(progress, shouldPrint, printed);
+    }
+    complete(message) {
+        this.current = this.total;
+        if (message)
+            this.print(message, true);
+    }
+    reset() {
+        this.current = 0;
+        this.startTime = Date.now();
+        this.lastPrintTime = 0;
+    }
+    print(message, force = false) {
+        if (force || this.shouldPrint()) {
+            this.logger(message, this.getProgress());
+            this.printed();
+        }
+    }
+    shouldPrint() {
+        return Date.now() - this.lastPrintTime >= this.interval;
+    }
+    printed() {
+        this.lastPrintTime = Date.now();
+    }
+    getProgress() {
+        const percentage = this.current / this.total;
+        const elapsed = Date.now() - this.startTime;
+        const average = this.current > 0 ? elapsed / this.current : 0;
+        const remaining = (this.total - this.current) * average;
+        return {
+            current: this.current,
+            total: this.total,
+            percentage,
+            elapsed,
+            average,
+            remaining,
+            formatted: {
+                percentage: `${(percentage * 100).toFixed(1)}%`,
+                elapsed: formatDurationAsReadable(elapsed),
+                average: formatDurationAsReadable(average),
+                remaining: formatDurationAsClock(remaining)
+            }
+        };
+    }
+}

package/dist/time.d.ts

@@ -6,3 +6,23 @@ export declare const getNextDay4AM: () => Date;
  * 获取下一个（含当日）周一凌晨4点的时间
  */
 export declare const getNextMonday4AM: () => Date;
+/**
+ * 解析时长
+ * @param duration 时长（毫秒）
+ */
+export declare const parseDuration: (duration: number) => {
+    h: number;
+    m: number;
+    s: number;
+    ms: number;
+};
+/**
+ * 将时长转换为时钟字符串
+ * @param duration 时长（毫秒）
+ */
+export declare const formatDurationAsClock: (duration: number) => string;
+/**
+ * 将时长转换为可读格式
+ * @param duration 时长（毫秒）
+ */
+export declare const formatDurationAsReadable: (duration: number) => string;

package/dist/time.js

@@ -23,3 +23,35 @@ export const getNextMonday4AM = () => {
     result.setDate(now.getDate() + daysUntilNextMonday);
     return result;
 };
+/**
+ * 解析时长
+ * @param duration 时长（毫秒）
+ */
+export const parseDuration = (duration) => {
+    return {
+        h: Math.floor(duration / 3600000),
+        m: Math.floor((duration % 3600000) / 60000),
+        s: Math.floor((duration % 60000) / 1000),
+        ms: Math.floor(duration % 1000)
+    };
+};
+/**
+ * 将时长转换为时钟字符串
+ * @param duration 时长（毫秒）
+ */
+export const formatDurationAsClock = (duration) => {
+    return Object.values(parseDuration(duration))
+        .slice(0, 3)
+        .map(num => String(num).padStart(2, "0"))
+        .join(":");
+};
+/**
+ * 将时长转换为可读格式
+ * @param duration 时长（毫秒）
+ */
+export const formatDurationAsReadable = (duration) => {
+    return Object.entries(parseDuration(duration))
+        .filter(([, value]) => value > 0)
+        .map(([unit, value]) => `${value}${unit}`)
+        .join(" ");
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "开发 BetterGI 脚本常用工具集",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@bettergi/types": "^0.1.3",
-    "rimraf": "^6.0.1",
+    "rimraf": "^6.1.0",
     "typescript": "^5.9.3"
   }
 }