# @effectionx/converge 中文文档

规范地址：https://npmcn.com/package/%40effectionx/converge/

版本：0\.1\.4
npm 元数据更新时间：2026-09-30T21:08:15.582Z
中文译文更新时间：2026-11-13T08:28:19.160Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：197 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：effection ^3 \|\| ^4
- 首次发布：2026-01-18T19:46:34.849Z
- 最新版本发布：2026-03-22T21:41:45.920Z
- 近 30 天下载量：47224（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

自动重试和超时

## 安装

```sh
npm install @effectionx/converge
```

也可以使用：`pnpm add @effectionx/converge`、`yarn add @effectionx/converge`、`bun add @effectionx/converge`

## README

# @ effectionx/ converg

承认理想状态,并在该状态实现后同步.

> 此软件包为 [@ bigtest/汇合](https://github.com/bigtestjs/convergence) 适应 [效果](https://frontside.com/effection) 结构货币.

* * *

## 何以相会?

假设你想写一个断言来验证一个简单的原因 效果: 当单击某个按钮时, 对话框会显示包含 一些从网络中加载的文本 .

为了做到这一点,你必须保证你的主张 _之后_ 你测试的效果已经实现.

![Image of assertion after an effect](https://raw.githubusercontent.com/thefrontside/effectionx/main/converge/images/assertion-after.png)

如果不是的话,那么你可能会变成假阴性,或者"阴性测试" 因为你的断言太早了 如果你只是等待一点点 再长一点,你的测试就会通过 真遗憾!

![Image of false negative test](https://raw.githubusercontent.com/thefrontside/effectionx/main/converge/images/false-negative.png)

事实上,测试片是大多数人逃避的原因 首先用 JavaScript 编写大测试 。 看来差不多了 无法写出强健的测试,但不能在 运行时间的内部,以便手动同步 比如渲染和数据加载 不幸的是,这些可能是 移动目标,更糟糕的是, 他们与你结合到你的框架.

但是,如果不是试图 运行我们的说法在正确的 时间,我们运行它们 _数量_ 直到他们通过 或者我们决定 放弃?

![Image of convergent assertion](https://raw.githubusercontent.com/thefrontside/effectionx/main/converge/images/convergent-assertion.png)

这就是什么的本质 `@effectionx/converge` 规定: 重复测试一个条件,然后允许代码运行 条件已经满足了.

这不仅仅是为了断言。 因为那是个将军 在任何观测到的状态上同步的机制,可用于 适当的时间测试 设置和撕裂也.

* * *

## 安装

```bash
npm install @effectionx/converge
```

* * *

## 使用量

### `when(assertion, options?)`

主张通过时的汇合 _在内部_ 暂停期。 这个 重复运行(默认情况下每10 ms)并被考虑 当它不抛出或返回的时候 `false`如果它从未通过 在超时时,操作会随最后一个出错而抛出.

```typescript
import { when } from "@effectionx/converge";

// Wait for a condition to become true
let { value } = yield* when(function* () {
  if (total !== 100) throw new Error("not ready");
  return total;
});

// With custom timeout
yield* when(
  function* () {
    if (!element.isVisible) throw new Error("not visible");
  },
  { timeout: 5000 },
);
```

### `always(assertion, options?)`

主张通过时的汇合 _整个_ 暂停期. 喜欢 `when()`但必须经过 整个期间始终如一。 如果在任何时刻失败 操作立即投出.

```typescript
import { always } from "@effectionx/converge";

// Verify a condition remains true
yield* always(function* () {
  if (counter >= 100) throw new Error("counter exceeded limit");
});

// With custom timeout
yield* always(
  function* () {
    if (!connection.isAlive) throw new Error("connection lost");
  },
  { timeout: 5000 },
);
```

* * *

## 选项

两者 `when` 财务报告和审定财务报表 `always` 接受选项对象 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `timeout` | `number` | `2000` (何时)/ `200` (总是) | 最多等待时间( 毫秒) |
| `interval` | `number` | `10` | 以毫秒表示的断言重试间隔时间 |

* * *

## Stats 对象

两个函数返回 a `ConvergeStats` 有时间和执行信息的对象:

```typescript
interface ConvergeStats<T> {
  start: number; // Timestamp when convergence started
  end: number; // Timestamp when convergence ended
  elapsed: number; // Milliseconds the convergence took
  runs: number; // Number of times the assertion was executed
  timeout: number; // The timeout that was configured
  interval: number; // The interval that was configured
  value: T; // The return value from the assertion
}
```

示例

```typescript
let stats = yield* when(
  function* () {
    return yield* fetchData();
  },
  { timeout: 5000 },
);

console.log(`Converged in ${stats.elapsed}ms after ${stats.runs} attempts`);
console.log(stats.value); // the fetched data
```

* * *

## 实例

### 等待元素出现

```typescript
yield* when(function* () {
  let element = document.querySelector('[data-test-id="dialog"]');
  if (!element) throw new Error("dialog not found");
  return element;
});
```

### 验证一个值保持稳定

```typescript
yield* always(
  function* () {
    if (connection.status !== "connected") {
      throw new Error("connection dropped");
    }
  },
  { timeout: 1000 },
);
```

### 使用文件系统操作

```typescript
import { when } from "@effectionx/converge";
import { access } from "node:fs/promises";
import { until } from "effection";

// Wait for a file to exist
yield* when(
  function* () {
    let exists = yield* until(
      access(filePath).then(
        () => true,
        () => false,
      ),
    );
    if (!exists) throw new Error("file not found");
    return true;
  },
  { timeout: 10000 },
);
```

## 常见问题

### @effectionx/converge 是什么？

自动重试和超时

### 如何安装 @effectionx/converge？

在项目目录运行 npm install @effectionx/converge，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effection（^3 \|\| ^4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @effectionx/converge 支持 TypeScript 吗？

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

### @effectionx/converge 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @effectionx/converge 可以商用吗？

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

### @effectionx/converge 的下载量有多少？

根据 npm 官方下载统计，@effectionx/converge 在 2026/10/13 – 2026/11/11 这 30 天内被下载 47,224 次，日均约 1,574 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @effectionx/converge 还在维护吗？

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