maoda-commander-tt 0.0.2

package/README.md

@@ -0,0 +1,168 @@
+# template-commander
+
+一个基于 [commander](https://github.com/tj/commander.js) 的通用 CLI 模板项目，采用面向对象架构设计，支持快速扩展子命令。
+
+## 特性
+
+- **面向对象架构** — 所有命令继承 `BaseCommand<TOptions>`，统一生命周期管理
+- **Disposable 体系** — 继承自 bedrock `Disposable` 基类，自动管理资源释放
+- **事件系统** — 基于 bedrock `Emitter` 提供 `onBeforeExecute` / `onAfterExecute` 等生命周期钩子
+- **结构化错误处理** — 使用 `ILvErrorOr<T>` 代替 throw/reject，错误码可追溯
+- **TypeScript 严格模式** — 全量 strict，类型安全
+- **开发热调试** — 基于 tsx 直接运行 TS，支持 `--inspect` 调试
+
+## 目录结构
+
+```
+template-commander/
+├── src/
+│   ├── main.ts                    # 入口文件
+│   ├── core/
+│   │   ├── cli-app.ts             # CliApp 主应用类
+│   │   ├── base-command.ts        # BaseCommand 抽象基类
+│   │   └── command-types.ts       # 命令元信息类型
+│   ├── commands/
+│   │   └── hello-command.ts       # 示例命令
+│   └── bedrock/                   # 基础设施层
+│       ├── dispose/               # Disposable 资源管理
+│       ├── event/                 # 事件发射器
+│       ├── error/                 # 结构化错误 (ILvErrorOr)
+│       └── ...
+├── package.json
+└── tsconfig.json
+```
+
+## 快速开始
+
+```bash
+# 安装依赖
+pnpm install
+
+# 开发运行
+pnpm dev -- --help
+pnpm dev -- hello Alice
+pnpm dev -- hello Alice -u
+
+# 调试模式 (支持 Chrome DevTools / VS Code 断点)
+pnpm dev:debug -- hello Alice
+
+# 构建
+pnpm build
+
+# 运行编译产物
+pnpm start -- --help
+```
+
+## 如何扩展新命令
+
+1. 在 `src/commands/` 下新建文件，创建继承 `BaseCommand<TOptions>` 的类：
+
+```typescript
+import type { Command } from 'commander';
+import { BaseCommand } from '../core/base-command.js';
+import type { ICommandActionContext } from '../core/base-command.js';
+import type { ICommandMeta } from '../core/command-types.js';
+import type { ILvErrorOr } from '../bedrock/error/index.js';
+
+interface IMyOptions {
+  verbose: boolean;
+}
+
+export class MyCommand extends BaseCommand<IMyOptions> {
+  protected _meta(): ICommandMeta {
+    return {
+      name: 'my-cmd',
+      description: '这是我的自定义命令',
+      aliases: ['mc'],
+    };
+  }
+
+  protected _configureArguments(cmd: Command): void {
+    cmd.argument('<target>', '操作目标');
+  }
+
+  protected _configureOptions(cmd: Command): void {
+    cmd.option('--verbose', '详细输出', false);
+  }
+
+  protected async _execute(ctx: ICommandActionContext<IMyOptions>): Promise<ILvErrorOr<void>> {
+    const target = ctx.args[0] as string;
+
+    if (ctx.options.verbose) {
+      console.log(`[verbose] target = ${target}`);
+    }
+
+    // 业务逻辑...
+
+    return this._makeOk();
+    // 或错误: return this._makeError(1001, '发生了某种错误');
+  }
+}
+```
+
+2. 在 `src/main.ts` 中注册：
+
+```typescript
+import { MyCommand } from './commands/my-command.js';
+
+app.registerCommand(new MyCommand());
+```
+
+完成！新命令会自动出现在 `--help` 输出和 `help [command]` 中。
+
+## 架构说明
+
+### BaseCommand
+
+每个子命令需要实现：
+
+| 方法 | 说明 |
+|---|---|
+| `_meta()` | 返回命令名、描述、别名 |
+| `_execute(ctx)` | 命令核心逻辑，返回 `ILvErrorOr<void>` |
+| `_configureOptions(cmd)` | (可选) 配置 commander 选项 |
+| `_configureArguments(cmd)` | (可选) 配置 commander 参数 |
+
+### 生命周期事件
+
+```typescript
+const cmd = new HelloCommand();
+cmd.onBeforeExecute(() => console.log('即将执行'));
+cmd.onAfterExecute((result) => {
+  if (result.ok) console.log('执行成功');
+  else console.log(`执行失败: [${result.code}] ${result.msg}`);
+});
+```
+
+### 错误处理
+
+使用 `ILvErrorOr<T>` 而非 throw：
+
+```typescript
+// 成功
+return this._makeOk();
+
+// 失败 (错误码 + 消息)
+return this._makeError(1001, '文件不存在');
+
+// 也可使用 bedrock 预定义错误
+import { invalidArgumentError } from '../bedrock/error/index.js';
+return invalidArgumentError('参数 name 不能为空');
+```
+
+## Scripts
+
+| 脚本 | 说明 |
+|---|---|
+| `pnpm dev` | 使用 tsx 直接运行（开发用） |
+| `pnpm dev:debug` | 启动 Node inspect 调试 |
+| `pnpm build` | TypeScript 编译 |
+| `pnpm start` | 运行编译后产物 |
+| `pnpm clean` | 清理 dist 目录 |
+
+## 技术栈
+
+- TypeScript 5.x (strict mode)
+- commander 13.x
+- chalk 5.x
+- tsx (开发热运行)

package/dist/bedrock/assert/assert.d.ts

@@ -0,0 +1,5 @@
+export declare function lvAssert(expr: unknown, reason?: string): asserts expr;
+export declare function lvAssertNotHere(reason?: string): never;
+export declare function lvAssertNever(member: never, message?: string): never;
+export declare function lvAssertNotNil<T>(val: T, reason?: string): asserts val is NonNullable<T>;
+//# sourceMappingURL=assert.d.ts.map

package/dist/bedrock/assert/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../../src/bedrock/assert/assert.ts"],"names":[],"mappings":"AAIA,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAIrE;AAED,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAEtD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,SAAmB,GAAG,KAAK,CAG9E;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAIxF"}

package/dist/bedrock/assert/assert.js

@@ -0,0 +1,21 @@
+function abort(reason) {
+    throw new Error(`lvAssert(${reason})`);
+}
+export function lvAssert(expr, reason) {
+    if (!expr) {
+        abort(reason ?? '#expr is false');
+    }
+}
+export function lvAssertNotHere(reason) {
+    abort(reason ?? 'unreachable code flow');
+}
+export function lvAssertNever(member, message = 'Illegal value:') {
+    // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+    abort(`${message}: ${member}`);
+}
+export function lvAssertNotNil(val, reason) {
+    if (val === null || val === undefined) {
+        abort(reason ?? '#val is nil');
+    }
+}
+//# sourceMappingURL=assert.js.map

package/dist/bedrock/assert/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../../src/bedrock/assert/assert.ts"],"names":[],"mappings":"AAAA,SAAS,KAAK,CAAC,MAAc;IAC3B,MAAM,IAAI,KAAK,CAAC,YAAY,MAAM,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAa,EAAE,MAAe;IACrD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,KAAK,CAAC,MAAM,IAAI,gBAAgB,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAe;IAC7C,KAAK,CAAC,MAAM,IAAI,uBAAuB,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAa,EAAE,OAAO,GAAG,gBAAgB;IACrE,4EAA4E;IAC5E,KAAK,CAAC,GAAG,OAAO,KAAK,MAAM,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,cAAc,CAAI,GAAM,EAAE,MAAe;IACvD,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtC,KAAK,CAAC,MAAM,IAAI,aAAa,CAAC,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/bedrock/assert/index.d.ts

@@ -0,0 +1,2 @@
+export { lvAssert, lvAssertNotHere, lvAssertNever, lvAssertNotNil } from './assert';
+//# sourceMappingURL=index.d.ts.map

package/dist/bedrock/assert/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/bedrock/assert/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/bedrock/assert/index.js

@@ -0,0 +1,3 @@
+// 提供断言能力
+export { lvAssert, lvAssertNotHere, lvAssertNever, lvAssertNotNil } from './assert';
+//# sourceMappingURL=index.js.map

package/dist/bedrock/assert/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/bedrock/assert/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}

package/dist/bedrock/async/barrier.d.ts

@@ -0,0 +1,20 @@
+export interface IBarrier {
+    isOpen: () => boolean;
+    open: () => void;
+    wait: () => Promise<boolean>;
+}
+/**
+ * A barrier that is initially closed and then becomes opened permanently after a certain period of
+ * time or when open is called explicitly
+ */
+export declare class Barrier {
+    private _isOpen;
+    private readonly _promise;
+    private _completePromise;
+    constructor();
+    isOpen(): boolean;
+    open(): void;
+    wait(): Promise<boolean>;
+}
+export declare function makeBarrierByPromise(promise: Promise<any>, openWhenReject?: boolean): Barrier;
+//# sourceMappingURL=barrier.d.ts.map

package/dist/bedrock/async/barrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"barrier.d.ts","sourceRoot":"","sources":["../../../src/bedrock/async/barrier.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,OAAO,CAAC;IACtB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C,OAAO,CAAC,gBAAgB,CAAwB;;IAShD,MAAM,IAAI,OAAO;IAIjB,IAAI,IAAI,IAAI;IAKZ,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAGzB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,cAAc,GAAE,OAAe,WAU1F"}

package/dist/bedrock/async/barrier.js

@@ -0,0 +1,37 @@
+/**
+ * A barrier that is initially closed and then becomes opened permanently after a certain period of
+ * time or when open is called explicitly
+ */
+export class Barrier {
+    _isOpen;
+    _promise;
+    _completePromise;
+    constructor() {
+        this._isOpen = false;
+        this._promise = new Promise((c, e) => {
+            this._completePromise = c;
+        });
+    }
+    isOpen() {
+        return this._isOpen;
+    }
+    open() {
+        this._isOpen = true;
+        this._completePromise(true);
+    }
+    wait() {
+        return this._promise;
+    }
+}
+export function makeBarrierByPromise(promise, openWhenReject = false) {
+    const barrier = new Barrier();
+    promise.then(() => barrier.open());
+    if (openWhenReject) {
+        promise.catch((err) => {
+            barrier.open();
+            throw err;
+        });
+    }
+    return barrier;
+}
+//# sourceMappingURL=barrier.js.map

package/dist/bedrock/async/barrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"barrier.js","sourceRoot":"","sources":["../../../src/bedrock/async/barrier.ts"],"names":[],"mappings":"AAMA;;;GAGG;AACH,MAAM,OAAO,OAAO;IACV,OAAO,CAAU;IACR,QAAQ,CAAmB;IACpC,gBAAgB,CAAwB;IAEhD;QACE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,IAAI,OAAO,CAAU,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC5C,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAqB,EAAE,iBAA0B,KAAK;IACzF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACnC,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACpB,OAAO,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/bedrock/async/cancellation.d.ts

@@ -0,0 +1,28 @@
+import { type IDisposable } from '../dispose';
+export interface ICancellationToken {
+    readonly isCancellationRequested: boolean;
+    readonly reason?: string;
+    readonly onCancellationRequested: (listener: () => any, thisArgs?: any, disposables?: IDisposable[]) => IDisposable;
+}
+export declare class CancellationToken {
+    static None: Readonly<ICancellationToken>;
+    static Cancelled: Readonly<ICancellationToken>;
+    static Make: (reason: string) => Readonly<ICancellationToken>;
+}
+export declare class CancellationTokenSource implements IDisposable {
+    private _token?;
+    private readonly _parentListener?;
+    private _abortController?;
+    constructor(parent?: ICancellationToken);
+    /**
+     * 传统的cancellation用法
+     */
+    get token(): ICancellationToken;
+    /**
+     * 对齐浏览器提供的abortSignal，支持给fetch、axios等传参使用
+     */
+    get signal(): AbortSignal;
+    cancel(reason?: string): void;
+    dispose(cancel?: boolean): void;
+}
+//# sourceMappingURL=cancellation.d.ts.map

package/dist/bedrock/async/cancellation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../../../src/bedrock/async/cancellation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAS5D,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAG1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAMzB,QAAQ,CAAC,uBAAuB,EAAE,CAChC,QAAQ,EAAE,MAAM,GAAG,EACnB,QAAQ,CAAC,EAAE,GAAG,EACd,WAAW,CAAC,EAAE,WAAW,EAAE,KACxB,WAAW,CAAC;CAClB;AAqED,qBAAa,iBAAiB;IAC5B,MAAM,CAAC,IAAI,+BAGR;IAEH,MAAM,CAAC,SAAS,+BAGb;IAEH,MAAM,CAAC,IAAI,GAAI,QAAQ,MAAM,kCAM3B;CACH;AAmBD,qBAAa,uBAAwB,YAAW,WAAW;IAEzD,OAAO,CAAC,MAAM,CAAC,CAAiC;IAEhD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAA0B;IAE3D,OAAO,CAAC,gBAAgB,CAAC,CAA8B;gBAE3C,MAAM,CAAC,EAAE,kBAAkB;IAMvC;;OAEG;IACH,IAAW,KAAK,IAAI,kBAAkB,CAKrC;IAED;;OAEG;IACH,IAAW,MAAM,IAAI,WAAW,CAS/B;IAEM,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAa7B,OAAO,CAAC,MAAM,UAAQ,GAAG,IAAI;CAWrC"}

package/dist/bedrock/async/cancellation.js

@@ -0,0 +1,156 @@
+import { EmptyDispose } from '../dispose';
+import { Emitter } from '../event';
+//
+// 编译时常量，一个快捷的事件响应
+// 用于当外界监听令牌取消时，直接触发回调
+//
+const shortcutEvent = Object.freeze(function (callback, context) {
+    const handle = setTimeout(callback.bind(context), 0);
+    return {
+        dispose() {
+            clearTimeout(handle);
+        },
+    };
+});
+//
+// 可取消异步调用的令牌实现
+// 默认是未取消状态，可以调用cancel进行取消
+//
+class MutableToken {
+    // 是否已经取消该异步调用
+    _isCancelled = false;
+    _emitter = null;
+    _reason;
+    get reason() {
+        return this._reason;
+    }
+    // 获取当前是否已经取消该异步调用
+    get isCancellationRequested() {
+        return this._isCancelled;
+    }
+    // 外界可以监听异步取消发起
+    get onCancellationRequested() {
+        if (this._isCancelled) {
+            return shortcutEvent;
+        }
+        if (!this._emitter) {
+            this._emitter = new Emitter();
+        }
+        return this._emitter.event;
+    }
+    cancel(reason) {
+        if (!this._isCancelled) {
+            this._reason = reason;
+            this._isCancelled = true;
+            if (this._emitter) {
+                this._emitter.fire();
+                this.dispose();
+            }
+        }
+    }
+    dispose() {
+        if (this._emitter) {
+            this._emitter.dispose();
+            this._emitter = null;
+        }
+    }
+}
+//
+// 编译期提供的一些常量Token
+// 不可修改
+//
+export class CancellationToken {
+    static None = Object.freeze({
+        isCancellationRequested: false,
+        onCancellationRequested: () => EmptyDispose,
+    });
+    static Cancelled = Object.freeze({
+        isCancellationRequested: true,
+        onCancellationRequested: shortcutEvent,
+    });
+    static Make = (reason) => {
+        return Object.freeze({
+            isCancellationRequested: true,
+            onCancellationRequested: shortcutEvent,
+            reason,
+        });
+    };
+}
+//
+// 任何可取消的异步调用 的控制类
+// 参考ICancellationToken，我们通过在异步调用的回调中添加token参数来判断异步调用的状态
+// token来源于CancellationTokenSource
+// CancellationTokenSource也会暴露cancel的接口
+//
+// 使用方式
+// const tokenSource = new CancellationTokenSource();
+//
+// asyncCall(() => {
+//   if (token.isCancellationRequested) { return; }  // 如果cancelled
+//   doSomething();
+// });
+//
+// tokenSource.cancel();  // 因为某些情况，可能会cancel
+// tokenSource.dispose();  // dispose时一定会cancel
+//
+export class CancellationTokenSource {
+    // 真正的token
+    _token = undefined;
+    // 可能存在父级CancellationTokenSource
+    _parentListener = undefined;
+    // 为了支持signal场景，所以在需要时会初始化浏览器提供的abortController原生结构
+    _abortController = undefined;
+    constructor(parent) {
+        // 如果存在父级，当父对象cancel时，子对象也必须cancel
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        this._parentListener = parent?.onCancellationRequested(this.cancel, this);
+    }
+    /**
+     * 传统的cancellation用法
+     */
+    get token() {
+        if (!this._token) {
+            this._token = new MutableToken();
+        }
+        return this._token;
+    }
+    /**
+     * 对齐浏览器提供的abortSignal，支持给fetch、axios等传参使用
+     */
+    get signal() {
+        if (this._abortController) {
+            return this._abortController.signal;
+        }
+        this._abortController = new AbortController();
+        if (this._token?.isCancellationRequested) {
+            this._abortController.abort();
+        }
+        return this._abortController.signal;
+    }
+    cancel(reason) {
+        if (!this._token) {
+            // 如果没有使用过token就直接cancel，那么就返回一个常量即可
+            this._token =
+                reason === undefined ? CancellationToken.Cancelled : CancellationToken.Make(reason);
+        }
+        else if (this._token instanceof MutableToken) {
+            this._token.cancel(reason);
+        }
+        if (this._abortController) {
+            this._abortController.abort(reason);
+        }
+    }
+    dispose(cancel = false) {
+        if (cancel) {
+            this.cancel();
+        }
+        this._parentListener?.dispose();
+        if (!this._token) {
+            this._token = CancellationToken.None;
+        }
+        else if (this._token instanceof MutableToken) {
+            this._token.dispose();
+        }
+    }
+}
+//# sourceMappingURL=cancellation.js.map

package/dist/bedrock/async/cancellation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancellation.js","sourceRoot":"","sources":["../../../src/bedrock/async/cancellation.ts"],"names":[],"mappings":"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"}

package/dist/bedrock/async/idle.d.ts

@@ -0,0 +1,9 @@
+import type { IDisposable } from '../dispose';
+export interface IIdleDeadline {
+    readonly didTimeout: boolean;
+    timeRemaining: () => number;
+}
+export interface IRunWhenIdle {
+    (callback: (idle?: IIdleDeadline) => void, timeout?: number): IDisposable;
+}
+//# sourceMappingURL=idle.d.ts.map

package/dist/bedrock/async/idle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle.d.ts","sourceRoot":"","sources":["../../../src/bedrock/async/idle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,aAAa,EAAE,MAAM,MAAM,CAAC;CAC7B;AAMD,MAAM,WAAW,YAAY;IAC3B,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,aAAa,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;CAC3E"}

package/dist/bedrock/async/idle.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=idle.js.map

package/dist/bedrock/async/idle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle.js","sourceRoot":"","sources":["../../../src/bedrock/async/idle.ts"],"names":[],"mappings":""}

package/dist/bedrock/async/index.d.ts

@@ -0,0 +1,7 @@
+export * from './cancellation';
+export * from './idle';
+export * from './promise';
+export { wait } from './wait';
+export * from './barrier';
+export * from './serial-async-task';
+//# sourceMappingURL=index.d.ts.map

package/dist/bedrock/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/bedrock/async/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAC;AAG/B,cAAc,QAAQ,CAAC;AAGvB,cAAc,WAAW,CAAC;AAG1B,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAG9B,cAAc,WAAW,CAAC;AAG1B,cAAc,qBAAqB,CAAC"}

package/dist/bedrock/async/index.js

@@ -0,0 +1,13 @@
+// 异步任务可取消的token
+export * from './cancellation';
+// 闲时接口声明
+export * from './idle';
+// 包装后可dispose的promise能力
+export * from './promise';
+// 通用的wait函数，提供异步等待能力
+export { wait } from './wait';
+// 提供调用 open 后 resolve promise 的能力
+export * from './barrier';
+// 提供串行执行异步读写任务的能力
+export * from './serial-async-task';
+//# sourceMappingURL=index.js.map

package/dist/bedrock/async/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/bedrock/async/index.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,cAAc,gBAAgB,CAAC;AAE/B,SAAS;AACT,cAAc,QAAQ,CAAC;AAEvB,wBAAwB;AACxB,cAAc,WAAW,CAAC;AAE1B,qBAAqB;AACrB,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B,kCAAkC;AAClC,cAAc,WAAW,CAAC;AAE1B,kBAAkB;AAClB,cAAc,qBAAqB,CAAC"}

package/dist/bedrock/async/promise.d.ts

@@ -0,0 +1,59 @@
+import { type ILvErrorOr, type ILvErrorRef } from '../error';
+import type { ICancellationToken } from './cancellation';
+/**
+ * 一般来说Promise常用的场景有：
+ * 1. 单次异步调用（new Promise）
+ * 2. 批量promise调用（Promise.all）
+ * 3. promise竞速调用（Promise.race）
+ *
+ * 但是原生能力有如下的缺陷
+ * 1. 不支持取消某一次promise调用
+ * 2. 不支持错误语义，promise.catch的重视程度比try catch还低
+ * 3. 超时行为需要基于race封装
+ *
+ * 针对这三点，基建侧提供了高阶的promise能力
+ * 1. makeCancelablePromise 返回一个可取消的promise
+ * const promise = makeCancelablePromise(() => { ... });
+ * promise.then((res) => {
+ *   // res是一个ILvErrorRef对象
+ * });
+ * // 可以直接取消promise
+ * promise.cancel();
+ *
+ * 2. parallelPromise 并发执行promise，会自动观测ILvErrorRef语义
+ * 当单个promise出现错误返回时，promise执行失败，尽可能调用所有cancelablePromise
+ * 当单个promise出现reject时，promise执行失败，尽可能调用所有cancelablePromise，并且将reject继续上抛
+ *
+ * 3. makePromiseWithTimeout 让promise支持超时，可以提供默认值
+ *
+ * ——————————————————
+ * Promise.allSettled和Promise.any在实际使用中场景较少，暂不提供错误语义包装
+ */
+export interface CancelablePromise<T> extends Promise<T> {
+    cancel: () => void;
+}
+/**
+ * 快速生成一个CancelablePromise对象
+ */
+export declare function makeCancelablePromise<T>(callback: (token: ICancellationToken) => Promise<T | ILvErrorOr<T>>): CancelablePromise<ILvErrorOr<T>>;
+/**
+ * 并行执行promise，当某一个失败，本次调用失败
+ * 本质上和Promise.all差不多，相比较之下
+ * 1. 包装了错误语义判断
+ * 2. 当失败时，会尽可能尝试cancel其他promise
+ *
+ * 注意：某一个promise失败时，会尽可能尝试调用其他promise的cancel，但不保证一定有效
+ * （有可能promiseA已经成功，但是primiseB在之后失败了）
+ */
+export declare function parallelPromise(promiseList: Promise<any>[]): Promise<ILvErrorRef>;
+/**
+ * 包装一个promise，提供超时能力
+ */
+export declare function makePromiseWithTimeout<T>(callback: (token: ICancellationToken) => Promise<T | ILvErrorOr<T>>, timeout: number, defaultValue?: T): Promise<ILvErrorOr<T>>;
+export interface Deferred<T> {
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason: unknown) => void;
+    promise: Promise<T>;
+}
+export declare function defer<T = void>(): Deferred<T>;
+//# sourceMappingURL=promise.d.ts.map

package/dist/bedrock/async/promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promise.d.ts","sourceRoot":"","sources":["../../../src/bedrock/async/promise.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,UAAU,EAIf,KAAK,WAAW,EAGjB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IACtD,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,GAClE,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CA6ClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAkCjF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,EACnE,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,GACf,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAuBxB;AAID,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7C,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CACrB;AAED,wBAAgB,KAAK,CAAC,CAAC,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAQ7C"}