# @beweco/utils-js 中文文档

规范地址：https://npmcn.com/package/%40beweco/utils-js/

版本：0\.0\.23
npm 元数据更新时间：2026-10-06T20:27:55.155Z
中文译文更新时间：2026-11-08T00:38:32.359Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40beweco/utils-js
原文对照：https://npmcn.com/package/%40beweco/utils-js/?lang=original

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

- 包体积（解压后）：231 kB，84 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：4 个
- peer 依赖：typescript \>=4\.5\.0
- 首次发布：2025-06-30T23:40:22.957Z
- 最新版本发布：2026-10-06T20:27:54.977Z
- 近 30 天下载量：2663（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 14 个）

## 中文简介

贝韦有效联盟

## 安装

```sh
npm install @beweco/utils-js
```

也可以使用：`pnpm add @beweco/utils-js`、`yarn add @beweco/utils-js`、`bun add @beweco/utils-js`

## README

# @beweco/ utils (英语)

用于电话号码验证和Tolgee本地化管理的用户库.

## 安装

```bash
npm install @beweco/utils-js
```

## 使用量

### 电话验证

```typescript
import { validatePhone } from '@beweco/utils-js';

// Validate a Chilean mobile number
const { isValid, formattedNumber, error } = validatePhone('912345678');
if (isValid) {
  console.log(formattedNumber); // '+56912345678'
} else {
  console.log(error);
}

// Validate with different country code
const result = validatePhone('912345678', '+1');
```

### 托尔吉本地化

```typescript
import { 
  getAllKeysTolgee, 
  downloadTranslations, 
  uploadOnlyNewKeysToTolgee, 
  uploadToTolgee,
  getAvailableLanguages 
} from '@beweco/utils-js';

// Configuration
const config = {
  apiKey: 'your-tolgee-api-key',
  projectId: 'your-project-id',
  baseUrl: 'https://app.tolgee.io' // optional, defaults to this value
};

// Get all available languages
const languages = await getAvailableLanguages(config);

// Get all keys from project
const keys = await getAllKeysTolgee(config);

// Download all translations
const translations = await downloadTranslations(config);

// Upload new keys only
const uploadResult = await uploadOnlyNewKeysToTolgee({
  ...config,
  language: 'es-AR',
  namespace: 'common',
  data: {
    'welcome': 'Bienvenido',
    'hello': 'Hola'
  }
});

// Upload all keys (including duplicates)
const uploadAllResult = await uploadToTolgee({
  ...config,
  language: 'es-AR',
  namespace: 'common',
  data: {
    'welcome': 'Bienvenido',
    'hello': 'Hola'
  }
});
```

## API 参考

### 电话验证

#### 验证 Phone( 电话: 字符串, countryCode? : 字符串): PhoneValidation Result

验证和格式化一个电话号码.

**参数:**

-   `phone` - 需要验证的电话号码
-   `countryCode` - 可选国家代码(智利默认为“+56”)

**回返情况:** 电话校正结果

```typescript
interface PhoneValidationResult {
  isValid: boolean;
  formattedNumber?: string;
  error?: string;
}
```

**审定规则:**

-   必须是手机号码(从9开始)
-   必须是9位数长 (不包括国家代码)
-   有无国家代码可提供
-   自动格式化为国际格式(例如“ +56912345678”)

### 托尔吉本地化

#### 类型

```typescript
interface TolgeeConfig {
  apiKey: string;
  projectId: string;
  baseUrl?: string;
}

interface Language {
  tag: string;
  name: string;
  originalName: string;
}

interface TranslationData {
  [key: string]: string;
}

interface DownloadTranslationsResult {
  languages: Language[];
  translations: {
    [language: string]: {
      [namespace: string]: {
        [key: string]: string;
      };
    };
  };
}

interface UploadResult {
  uploaded?: number;
  [key: string]: unknown;
}
```

#### 职能

##### 获得AvailableLanguages(配置:TolgeeConfig):承诺<语言>

在Tolgee项目中获取所有可用的语言.

##### 获取 AllKeysTolgee( 配置: TolgeeConfig ): 保证 < string >

从 Tolgee 工程中获取所有密钥, 并带有 pagination 支持 .

##### 下载翻译( 配置: TolgeeConfig & {namespace? : string} ): 保证

下载按语言和命名空间排列的所有翻译.

**参数:**

-   `config` - 托尔吉配置
-   `namespace` - 可选命名空间过滤器

##### 仅上传NewKeys ToTolgee( 配置: tolgee Config & { 语言: 字符串; 命名空间: 字符串; 数据: 翻译数据 } : 答应

上传项目中不存在的新密钥 .

**参数:**

-   `config` - 托尔吉配置
-   `language` - 目标语言(例如“s-AR”)
-   `namespace` - 命名空间(例如“ 普通” )
-   `data` - 翻译数据对象

##### 上传到 Tolgee( 配置: TolgeeConfig & { 语言: 字符串; 命名空间: 字符串; 数据: 翻译数据 } : 答应

上传所有密钥而不检查重复.

**参数:**

-   `config` - 托尔吉配置
-   `language` - 目标语言(例如“s-AR”)
-   `namespace` - 命名空间(例如“ 普通” )
-   `data` - 翻译数据对象

#### 常数

```typescript
const DEFAULT_BASE_URL = 'https://app.tolgee.io';
const DEFAULT_PAGE_SIZE = 1000;
```

### HTTP 客户端

`createHttpClient(baseURL, options)` 返回一个未切换的轴实例 `response.data`。失败的请求不拒绝:它们解决 `error.response.data` (网关错误信封,或 `undefined` 当没有收到任何答复时,例如网络出错或超时).

401 处理:

-   A 类 `401` 触发符号刷新对 `refreshPath` 并用新的访问符重写原始请求。 同时 `401`s 共享一个刷新.
-   A 类 `401` 他的信封里装着 `error.code` (或顶级) `message`等于 `access_denied` 是一个账户访问拒绝(例如过期的自由试验),而不是过期的符号:它被作为原样返回,没有刷新和重试.
-   `onAuthError` 只有在刷新端点拒绝证书(任何4xx)时才使用。 在网络出错,超时和5xx 反应刷新重试一次并保持会话.

### 语音录音核心`@beweco/utils-js/voice`(中文(简体) )

用于批量语音录制的框架不可知性( 无反应, 无 UI 框架) 核心 `MediaRecorder`它是一种单独的子路径导出,目的——只需记录音频的消费者不应拉入轴线、饼干或地产处理.

```typescript
import { createVoiceRecorder, toTranscriptionFormData } from '@beweco/utils-js/voice';

const recorder = createVoiceRecorder();
const unsubscribe = recorder.subscribe(() => {
  // re-read recorder.state / recorder.stream (e.g. from useSyncExternalStore)
});

const result = await recorder.start(); // "ok" | "denied" | "unavailable" | "unsupported" | "busy"
// ... later
const blob = await recorder.stop(); // Blob | null
if (blob) {
  const formData = toTranscriptionFormData(blob); // File "audio.<ext>" under field "audio"
}

recorder.dispose(); // release the microphone for good (e.g. on unmount)
```

此模块只拥有录制原始: 它不转录、 上传、 解跳点击或失效 stale 起始于多个呼叫 `start()` 在屏幕上。 React switch,记录按钮和向一个抄录服务说话的HTTP适配器,每个消耗性应用中都会直播.

装饰波形的平面表 (Web Audio; 返回 0 没有它):

```typescript
import { createAudioLevelMeter } from '@beweco/utils-js/voice';

const meter = createAudioLevelMeter(recorder.stream!); // after start() === "ok"
const level = meter.getLevel(); // RMS 0..1, read it from your own rAF loop
meter.dispose(); // disconnects and closes the AudioContext; idempotent
```

> **说明:** 页:1 `exports` 输入 `package.json` 限制进口到 `@beweco/utils-js` 财务报告和审定财务报表 `@beweco/utils-js/voice` - 深道一样 `@beweco/utils-js/dist/...` 不再有决心了 目前没有消费者使用它们.

## 发展

### 先决条件

-   节点.js 24
-   无

**重要内容:** 这个项目需要Node.js版本24或更晚. 你用得着 `.nvmrc` 文件为 :

```bash
nvm use
```

### 可用的脚本

-   `npm run clean` - 删除 Dist 目录
-   `npm run build` - 编译类型脚本代码
-   `npm test` - 进行测试
-   `npm run lint` - 运行 ESLint
-   `npm run dev` - 在监视模式下运行 TypeScript 编译器

## 出版

这个软件包通过GitHub Actions向国家预防机制自动发布.

### 手动发布

1.  转到 `Actions` → `Publish NPM` 以 GitHub 为单位
2.  点击 `Run workflow`
3.  选择版本凸起类型 :
    -   **补丁**: Bug 修正 (0.011 ~ 0.0.12)
    -   **小声**: 新的特性(0.0.11 ~ 0.1.0)
    -   **主要**: 打破变化(0.011 ~ 1.0.0)

工作流程将自动:

-   运行测试并构建
-   套件中的 Bump 版本. json
-   创建 git 标签并执行
-   向国家预防机制公布
-   将更改推回仓库

### 第一次设置

仓库管理员需要用 NPU TOKEN 配置“生产”环境。 见 [`.github/DEPLOYMENT.md`](https://npmcn.com/package/%40beweco/utils-js/.github/DEPLOYMENT.md) 详细指示.

## 捐款

1.  从 `main`
2.  做你的改变
3.  必要时进行书面/更新测试
4.  运行嵌入和测试 : `npm run lint && npm test`
5.  创建拉动请求
6.  合并后使用 GitHub 动作发布新版本

## 许可证

麻省理工学院

## 常见问题

### @beweco/utils-js 是什么？

贝韦有效联盟

### 如何安装 @beweco/utils-js？

在项目目录运行 npm install @beweco/utils-js，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（\>=4\.5\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @beweco/utils-js 支持 TypeScript 吗？

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

### @beweco/utils-js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

### @beweco/utils-js 可以商用吗？

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

### @beweco/utils-js 的下载量有多少？

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

### @beweco/utils-js 还在维护吗？

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