# @faybl/utils 中文文档

规范地址：https://npmcn.com/package/%40faybl/utils/

版本：2\.5\.2
npm 元数据更新时间：2026-11-13T08:37:55.144Z
中文译文更新时间：2026-11-14T12:05:23.834Z
软件包许可：TBD

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

原始 npm 页面：https://www.npmjs.com/package/%40faybl/utils
原文对照：https://npmcn.com/package/%40faybl/utils/?lang=original
项目主页：https://gitlab.com/arcturitech/faybl/utils/utils-js#readme
源码仓库：https://gitlab.com/arcturitech/faybl/utils/utils-js

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

- 包体积（解压后）：20.1 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：2 个
- 首次发布：2026-10-22T01:39:42.890Z
- 最新版本发布：2026-11-13T08:37:54.879Z
- 近 30 天下载量：3702（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

Faybl 服务和网络应用程序通用 JavaScript

## 安装

```sh
npm install @faybl/utils
```

也可以使用：`pnpm add @faybl/utils`、`yarn add @faybl/utils`、`bun add @faybl/utils`

## README

# @ faybl/ utils (英语)

Faybl服务和网络应用通用JavaScript.

```
npm install @faybl/utils
```

## 历史

`fetchHistory` 通过 faybl 客户端读取一个频道的历史为数组 上升时间,每点 `ts` 财务报告和审定财务报表 `pl`,这是图画.

```js
import { fetchHistory, fetchHistoryLast } from '@faybl/utils';

const { data } = await fetchHistory({ client, rid, from, to });
const newest = await fetchHistoryLast({ client, rid });
```

决定 `ascending` 财务报告和审定财务报表 `reverse` 数据历史:

| 请求 | 回返 |
| --- | --- |
| `from`,有或无 `to` | 范围,从开始 |
| `limit` 财务报告和审定财务报表 `from` | 首个 `limit` 从点 `from` |
| `limit` 无 `from` | 最新的 `limit` 点前 `to` 当给定时 |
| 无 | 从最古老的地方 |

`samplingInterval`, (中文(简体) ), `downsamplingMethod` 财务报告和审定财务报表 `timeZone` 被传递。 空 数值被忽略,没有其他数据历史.

`fetchHistoryLast` 是最新的一点,之前 `to` 提供时,或 `undefined`。 。 。 .

## 等待时

`waitFor` 调用一个功能,直到它的承诺解决 数值。 这是服务如何在开始时等待 一个依赖它的 自己,记录每个尝试而不是退出.

```js
import { waitFor } from '@faybl/utils';

const storage = await waitFor(connectToDatabase, {
  onRetry: (error, attempt) => logger.warn(`Database not reachable, attempt ${attempt}:`, error),
});
```

| 选项 | 默认 | 它会做什么 |
| --- | --- | --- |
| `interval` | 5000块 | 尝试之间的毫秒 |
| `retryIf` | 永远是真的 | 被拒绝; 假传去而不是再试一次 |
| `onRetry` | 无所作为 | 由于拒绝和尝试的号码, 在等待之前 |

对尝试没有限制.

`delay(milliseconds, signal?)` 在时间之后解决。 中止 `signal` 清除计时器并拒绝信号的理由.

```js
await delay(1000);
await delay(1000, AbortSignal.timeout(500)); // rejects after 500 ms
```

## 路径和选择

`pathStr('pl.temp')(data)` 读取一个点分隔的路径,例如一个用户类型; 数组索引是路径中的数字(`'list.0'`) (中文(简体) ). 一条缺失的路径和一条 `null` (或 `NaN`() 两者的数值 `undefined`。 。 。 .

`pickRandom(items)` 是随机项目,或 `undefined` 没有。 这需要它 随机性作为测试的第二个参数: `pickRandom(items, () => 0)`。 。 。 .

## 剪贴板

`copyText(text)` 写入系统剪贴板并解析为结果 : `Ok`, (中文(简体) ), 或者说 `Err({ kind: 'ClipboardWriteFailed', cause })` 当没有剪贴板时, 权限被拒绝或页面没有焦点。 从点击处理器调用 在任何时间之前 `await`,或浏览器拒绝写入.

```js
match(({ cause }) => console.warn('Copy by hand:', cause))(() => setCopied(true))(
  await copyText(url),
);
```

## 结果

预期失败作为值: 简单、可序列的数据, `Ok(value)` =: `{ ok: true, value }` 或者说 `Err(error)` =: `{ ok: false, error }`组合 `map` 编号 : `chain` 编号 : `mapErr` 从此软件包( 从不) `R.map` 编号 : `R.chain`: 拉姆达 地图 a 结果的字段为平面对象, 收集列表 `all` (第一届) `Err` 和在边缘解开 `match(onErr)(onOk)`。 。 。 .

```js
import * as R from 'ramda';
import { Err, Ok, chain, fromNil, match, tryCatchAsync } from '@faybl/utils';

const fetchJson = tryCatchAsync(async (url) => Ok(await (await fetch(url)).json()))((cause, url) =>
  Err({ kind: 'FetchFailed', url, cause }),
);
const getPort = R.pipe(R.path(['server', 'port']), fromNil({ kind: 'MissingPort' }));

const port = chain(getPort)(await fetchJson(url));
match(({ kind }) => console.error(kind))(console.log)(port);
```

在边界上环绕外方抛出者 `R.tryCatch` (同步)或 `tryCatchAsync` (同声. 当打包的电话也可以发出错误时 非预期失败, 使用 `catchWhen(isExpected)(toErr)` 作为捕捉者: 将错误匹配到一个 `Err` 并重新扔任何东西 没有改变,所以 缺陷仍在崩溃.

```js
const readText = tryCatchAsync(async (path) => Ok(await readFile(path, 'utf8')))(
  catchWhen((e) => e?.code === 'ENOENT')((cause, path) =>
    Err({ kind: 'FileNotFound', path, cause }),
  ),
);
```

## 频道

`channelsOfParent(parent)(records)` 保存频道记录资产或东西 清单 `channels` (名称) 清除,每个与 `nameFromParent`; 缺少 ưμ㼯a. `recordsToSelectOptions` 将频道记录转换为 `{ id: rid, label }` 选项.

## 名称和模拟数据

`haiku()` 是一个随机的双字标题, 如 `Misty creek`。 。 。 . `mockHistory()` 实值 过去10秒的10分 形状像数据历史反应 没有后端的应用程序运行; `mockHistoryEmpty()` 没有。 都带上 随机性(和 `mockHistory` 联合国 `now`作为测试的论据.

## 常见问题

### @faybl/utils 是什么？

Faybl 服务和网络应用程序通用 JavaScript

### 如何安装 @faybl/utils？

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

### @faybl/utils 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/faybl\_\_utils 是否存在。

### @faybl/utils 支持 ESM 还是 CommonJS？

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

### @faybl/utils 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @faybl/utils 可以商用吗？

@faybl/utils 使用 TBD 许可。声明的许可为 TBD，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @faybl/utils 的下载量有多少？

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

### @faybl/utils 还在维护吗？

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