# @deepkit/bench 中文文档

规范地址：https://npmcn.com/package/%40deepkit/bench/

版本：1\.1\.0
npm 元数据更新时间：2026-10-31T21:43:10.479Z
中文译文更新时间：2026-10-31T23:52:55.908Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepkit/bench
原文对照：https://npmcn.com/package/%40deepkit/bench/?lang=original
项目主页：https://github.com/deepkit/deepkit-framework#readme
源码仓库：https://github.com/deepkit/deepkit-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：162 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-04-02T21:11:39.655Z
- 最新版本发布：2026-10-31T21:43:10.354Z
- 已发布版本数：5（近 12 个月 1 个）

## 中文简介

Deepkit板凳

## 安装

```sh
npm install @deepkit/bench
```

也可以使用：`pnpm add @deepkit/bench`、`yarn add @deepkit/bench`、`bun add @deepkit/bench`

## README

# @deepkit /板凳

具有可视化和统计分析的零依赖基准实用程序。

## 功能

-   自动同步/异步检测
-   自适应迭代选择（1x到10M迭代）
-   GC事件跟踪(当 `--expose-gc` 使用)
-   堆增量测量
-   统计分析（RME，方差）
-   彩色编码输出与块栏可视化
-   简单的API和基于类的 `BenchSuite` API

## 安装

```bash
npm install @deepkit/bench
```

## 简单的API

对于快速的一次性基准测试：

```typescript
import { benchmark, run } from '@deepkit/bench';

let counter = 0;

benchmark('increment', () => {
  counter += 10;
});

benchmark('multiply', () => {
  counter *= 2;
});

await run(1); // Run each benchmark for 1 second
```

运行:

```bash
node --import @deepkit/run benchmarks/test.ts
```

## BenchSuite API

对于有组织的基准套件进行比较：

```typescript
import { BenchSuite } from '@deepkit/bench';

const suite = new BenchSuite('serialization', 1, true); // name, maxTime, showSummary

suite.add('serialize', () => {
  serialize<User>(user);
});

suite.add('deserialize', () => {
  deserialize<User>(data);
});

await suite.runAsync();
```

### 输出

```
━━━ serialization ━━━

  ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅▆   32,456,789.12 ops/sec    30.821 ns/op   ±1.23%  serialize
  ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅▆   28,123,456.78 ops/sec    35.557 ns/op   ±0.98%  deserialize

  Summary:
  ███████████████   32.46M ops/sec fastest  serialize
  █████████████░░   28.12M ops/sec   x1.15  deserialize
```

## 格式化工具

```typescript
import { formatBytes, formatHz, formatHzFull, formatMean, formatRme } from '@deepkit/bench';

formatHz(1_000_000); // "1.00M"
formatHzFull(1_000_000); // "1,000,000.00"
formatMean(0.000001); // "1.000 ns"
formatMean(0.001); // "1.000 µs"
formatMean(1); // "1.000 ms"
formatRme(1.5); // "±1.50%"
formatBytes(1024); // "1.00 KB"
```

## 可视化工具

```typescript
import { getBlockBar, getBrailleBar } from '@deepkit/bench';

// Block bar (uses █▇▆▅▄▃▂▁ characters with HSV color gradient)
getBlockBar(samples, 20);

// Braille bar (more compact, uses Braille characters)
getBrailleBar(samples);
```

## 内存和GC实用程序

```typescript
import { forceGC, getHeapUsage, warmup, warmupAsync } from '@deepkit/bench';

// Force garbage collection (requires --expose-gc)
forceGC();

// Get current heap usage in bytes
const heap = getHeapUsage();

// Warmup a function for V8 optimization
warmup(myFunction, 100);

// Warmup an async function
await warmupAsync(myAsyncFunction, 50);
```

## API参考

### 类型

```typescript
interface BenchResult {
  hz: number; // Operations per second
  elapsed: number; // Total elapsed time in seconds
  rme: number; // Relative margin of error (percentage)
  mean: number; // Mean time per operation in milliseconds
  variance: number; // Variance of samples
  iterations: number; // Number of iterations run
  samples: number[]; // Sample timings (up to 50)
  heapDiff: number; // Heap memory difference in bytes
  async: boolean; // Whether this is an async benchmark
  gcEvents: number[]; // GC events during benchmark (pause times in ms)
}

type BenchSuiteResult = { [name: string]: BenchResult };

interface BenchmarkOptions {
  maxTime?: number; // Maximum time to run in seconds (default: 1)
}
```

### BenchSuite

```typescript
class BenchSuite {
  static onComplete?: (name: string, result: BenchSuiteResult) => void;

  constructor(
    name: string,
    defaultMaxTime?: number, // Default: 1
    showSummary?: boolean, // Default: false
  );

  add(name: string, fn: () => void | Promise<void>, options?: BenchmarkOptions): this;
  run(options?: { verbose?: boolean }): void;
  runAsync(options?: { verbose?: boolean }): Promise<BenchSuiteResult>;
  getResults(): BenchSuiteResult;
}
```

## 准确的基准测试技巧

1.  **使用 `--expose-gc`** 用于GC跟踪： `node --expose-gc script.ts`
2.  **预热功能** 在基准测试之前确保V8优化
3.  **避免副作用** 在基准测试函数中，可能会扭曲结果
4.  **多次运行** 考虑系统差异
5.  **使用更长的持续时间** （2-5秒）更稳定的结果

## 常见问题

### @deepkit/bench 是什么？

Deepkit板凳

### 如何安装 @deepkit/bench？

在项目目录运行 npm install @deepkit/bench，或使用 pnpm add / yarn add / bun add。

### @deepkit/bench 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deepkit/bench 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @deepkit/bench 可以商用吗？

@deepkit/bench 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deepkit/bench 还在维护吗？

最新版本 1\.1\.0 发布于 2026/11/01（2 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 1 个；首次发布于 2025/04/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。