# @benzinga/safe-await 中文文档

规范地址：https://npmcn.com/package/%40benzinga/safe-await/

版本：1\.0\.6
npm 元数据更新时间：2025-04-28T17:56:47.804Z
中文译文更新时间：2026-11-07T22:48:29.944Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40benzinga/safe-await
原文对照：https://npmcn.com/package/%40benzinga/safe-await/?lang=original
项目主页：https://github.com/Benzinga/js-tools

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

- 包体积（解压后）：18.6 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2023-02-10T00:28:32.602Z
- 最新版本发布：2025-04-11T05:49:29.251Z
- 近 30 天下载量：2879（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

这个项目之所以可能,是因为

## 安装

```sh
npm install @benzinga/safe-await
```

也可以使用：`pnpm add @benzinga/safe-await`、`yarn add @benzinga/safe-await`、`bun add @benzinga/safe-await`

## README

# 安全等待时

这个项目之所以可能,是因为

[![Benzinga Logo](https://import.cdn.thinkific.com/222214/D3r5EJy9SZaNsaY7dQsj_Benzinga-logo-navy.svg)](https://npmcn.com/package/%40benzinga/safe-await/www.benzinga.com)

[![ZSoft Logo](https://raw.githubusercontent.com/ZNackasha/CDN/refs/heads/main/zsoft-no-size.svg)](https://github.com/znackasha)

Safe Await是一个简单的方法 确保我们的错误得到处理.

## 安全保证

我最不喜欢的JavaScript async/await语法就是它投出错误. 这总是给我带来问题,因为人们总是忘记尝试抓住这些等待的发言。 我的另一个问题是,当你尝试捕捉时 所创造的新范围, 它只是使代码看起来糟糕 因为你必须开始思考变量的范围.

### 缓存

我们不需要创建安全功能,我们可以简单地将功能调用转换为安全调用,例如:

```ts
const stuff = await safeAwait(fetch('benzinga.com/things/and/stuff'));
if (stuff.err) {
  console.log(stuff.err);
}
else {
  console.log(stuff.ok);
}
```

如你所见,我们在这里所做的是 包装取回与 `safeAwait` 具有下列功能:

```ts
export type SafePromise<T> = Promise<{ err: Error; ok: undefined } | { err: undefined; ok: T}>

export const safeAwait = async <T>(promise: Promise<T>): SafePromise<T> => {
  try {
    return { ok: await promise };
  } catch (err: any) {
    return { err };
  }
};
```

两者都值得注意的一件事是 `safeAwait` 返回安全保证。 这是用来表示你不必尝试抓住"承诺",以及它表明这是在上游某个地方检查的. 因为你真正需要尝试抓取的时间是使用API函数时. 在那之后,承诺是安全的,除非你 自己提出例外.

### 安全等待功能

解决这个问题的另一种方法是将功能包起来,使 `safeFunction`。那么,怎样 `safeFunction` 是吗? 它只需要一个函数作为参数,然后返回一个函数。 内在它只是尝试抓住你 并拖动结果.

```ts
const stuff = await safeFetch('benzinga.com/things/and/stuff');
if (stuff.err) {
  console.log(stuff.err);
} else {
  console.log(stuff.ok);
}
```

创建安全功能很容易. 仅此而已 `safeAwaitFunction` 作为参数的async函数.

```ts
const safeFetch = safeAwaitFunction(fetch);
```

现在我们有植入 `fetch` 总是返回 a `SafePromise`。 。 。 .

这是我们人类的核心概念 `safe-await` 软件包。 以下是简单的辅助函数和工具,它们只是使用 `safe-await` 图书馆.

## 帮助函数

### 安全磁盘

类似 `Promise.Race` 但为安全保证.

```ts
safeRace = <T>(promises: SafePromise<T>[]): SafePromise<T>
```

### 安全地图

类似“ 映射” 的函数用于数组, 但用于安全等待

实例

```ts
const quotesExist = (symbol) => {
  safeMap(fetchQuote(symbol), quote => quote.doesExist)
};
```

### 安全的话

一个类似于 `Promise.then` 它允许您在承诺完成后添加运行的函数.

实例

```ts
const quotesExist = (symbol) => {
  safeThen(fetchQuote(symbol), quote => { ok: quote.doesExist })
};
```

### 安全等待( A)

类似 `Promise.all` 不过,它返回a `SafePromiseMultiError` 允许:

```ts
safeAwaitAll = async <U, T extends readonly SafePromise<U>[]>(promise: T & SafePromise<U>[]): SafePromiseMultiError<U[]>
```

## 常见问题

### @benzinga/safe-await 是什么？

这个项目之所以可能,是因为

### 如何安装 @benzinga/safe-await？

在项目目录运行 npm install @benzinga/safe-await，或使用 pnpm add / yarn add / bun add。

### @benzinga/safe-await 支持 TypeScript 吗？

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

### @benzinga/safe-await 支持 ESM 还是 CommonJS？

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

### @benzinga/safe-await 可以商用吗？

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

### @benzinga/safe-await 的下载量有多少？

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

### @benzinga/safe-await 还在维护吗？

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