# @happyvertical/utils 中文文档

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

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:02:56.747Z
中文译文更新时间：2026-11-17T09:29:07.302Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/utils
原文对照：https://npmcn.com/package/%40happyvertical/utils/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/utils#readme
源码仓库：https://github.com/happyvertical/sdk

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

- 包体积（解压后）：677 kB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-06-23T08:14:21.768Z
- 最新版本发布：2026-11-17T00:02:56.551Z
- 近 30 天下载量：56776（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

用于 ID 生成、日期解析、 URL 处理、 字符串转换、 错误处理和记录的基础工具

## 安装

```sh
npm install @happyvertical/utils
```

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

## README

# @ happyvertical/ utils (欢快的垂直)

Hare SDK的基础公用设备:ID生成,日期解析,URL处理,字符串转换,出错分类,日志,代码提取/验证/发包,CLI参数解析,以及环境配置加载.

## 安装

```bash
pnpm add @happyvertical/utils
```

可在 `@happyvertical/utils/browser` (不包括Node.js特定代码,例如: `node:vm` 沙盒和 `node:crypto` 散开.

## 使用量

### ID 生成

```typescript
import { makeId, createId, isCuid } from '@happyvertical/utils';

const id = makeId();         // CUID2 (default)
const uuid = makeId('uuid'); // UUID via crypto.randomUUID()
const cuid = createId();     // CUID2 directly
isCuid(id);                  // true
```

### 字符串和 URL 工具

```typescript
import { camelCase, snakeCase, keysToCamel, keysToSnake, makeSlug, urlFilename, isUrl } from '@happyvertical/utils';

camelCase('hello-world');      // "helloWorld"
snakeCase('helloWorld');       // "hello_world"
keysToCamel({ user_name: 'j' }); // { userName: 'j' } (recursive)
makeSlug('My Title & Co.');   // "my-title-38-co"
urlFilename('https://example.com/path/file.pdf'); // "file.pdf"
isUrl('https://example.com'); // true
```

### 日期公用事业

```typescript
import { dateInString, formatDate, parseDate, parseAmazonDateString, addInterval } from '@happyvertical/utils';

dateInString('Report_January_15_2023.pdf'); // Date(2023, 0, 15)
formatDate(new Date(), 'yyyy-MM-dd');       // "2023-01-15"
parseDate('2023-01-15');                    // Date object (ISO)
parseDate('01/15/2023', 'MM/dd/yyyy');      // Date object (custom format)
parseAmazonDateString('20220223T215409Z');   // Date object
addInterval(new Date(), { days: 7 });       // Date 7 days from now
```

### 错误分类

全部扩展 `BaseError` 与 `code`, (中文(简体) ), `context`,以及 `timestamp` 字段,加 `toJSON()`数字 :

```typescript
import { ValidationError, ApiError, NetworkError, TimeoutError, ParsingError, FileError, DatabaseError } from '@happyvertical/utils';

throw new ValidationError('Invalid email', { field: 'email', value: input });
```

### 代码提取和沙盒

从 markdown/ AI 回复中提取代码块, 验证, 并在孤立中执行 `node:vm` 语境 :

```typescript
import { extractCodeBlock, extractJSON, validateCode, executeInSandbox } from '@happyvertical/utils';

const code = extractCodeBlock(markdownText, 'javascript');
const data = extractJSON<{ name: string }>(aiResponse);

const result = validateCode(code, { maxLength: 10000 });
if (result.valid) {
  const output = executeInSandbox(code, { globals: { data }, timeout: 5000 });
}
```

### CLI 参数分析

```typescript
import { parseCliArgs } from '@happyvertical/utils';

const parsed = parseCliArgs(process.argv, [
  { name: 'build', description: 'Build project', options: { output: { type: 'string', description: 'Output dir' } } }
]);
// { command: 'build', args: [], options: { output: './dist' } }
```

### 环境配置

```typescript
import { loadEnvConfig } from '@happyvertical/utils';

// Loads HAVE_AI_* env vars, merged with user options (user options take precedence)
const config = loadEnvConfig({ provider: 'openai' }, {
  packageName: 'ai',
  schema: { provider: 'string', model: 'string', timeout: 'number' }
});
```

### 日志

```typescript
import { getLogger, setLogger, disableLogging } from '@happyvertical/utils';

const logger = getLogger();
logger.info('Started', { userId: 123 });
disableLogging(); // Switch to no-op logger
```

## API 参考

**身份证** —— 说 `makeId(type?)`, (中文(简体) ), `createId()`, (中文(简体) ), `isCuid(id)`

**字符串** —— 说 `camelCase(str)`, (中文(简体) ), `snakeCase(str)`, (中文(简体) ), `keysToCamel(obj)`, (中文(简体) ), `keysToSnake(obj)`, (中文(简体) ), `domainToCamel(str)`, (中文(简体) ), `makeSlug(str)`

**URL( URL)** —— 说 `urlFilename(url)`, (中文(简体) ), `urlPath(url)`, (中文(简体) ), `isUrl(str)`, (中文(简体) ), `normalizeUrl(url)`, (中文(简体) ), `generateScopeFromUrl(url)`, (中文(简体) ), `hashPageContent(html)`

**日期** —— 说 `dateInString(str)`, (中文(简体) ), `prettyDate(str)`, (中文(简体) ), `parseAmazonDateString(str)`, (中文(简体) ), `formatDate(date, format?)`, (中文(简体) ), `parseDate(str, format?)`, (中文(简体) ), `isValidDate(date)`, (中文(简体) ), `addInterval(date, duration)`

**多元化** —— 说 `pluralizeWord(word)`, (中文(简体) ), `singularize(word)`, (中文(简体) ), `isPlural(word)`, (中文(简体) ), `isSingular(word)`

**类型警卫** —— 说 `isArray(obj)`, (中文(简体) ), `isPlainObject(obj)`

**自动同步** —— 说 `waitFor(fn, options?)`, (中文(简体) ), `sleep(ms)`

**代码** —— 说 `extractCodeBlock(text, lang?)`, (中文(简体) ), `extractAllCodeBlocks(text, lang?)`, (中文(简体) ), `extractJSON<T>(text)`, (中文(简体) ), `extractFunctionDefinition(code, name)`, (中文(简体) ), `validateCode(code, options?)`, (中文(简体) ), `isSafeCode(code)`, (中文(简体) ), `createSandbox(options?)`, (中文(简体) ), `executeCode(code, sandbox, options?)`, (中文(简体) ), `executeCodeAsync(code, sandbox, options?)`, (中文(简体) ), `executeInSandbox(code, options?)`, (中文(简体) ), `executeInSandboxAsync(code, options?)`

**国 际** —— 说 `parseCliArgs(argv, commands, builtInCommands?)`

**配置** —— 说 `loadEnvConfig<T>(userOptions?, options?)`, (中文(简体) ), `toCamelCase(str)`, (中文(简体) ), `toScreamingSnakeCase(str)`, (中文(简体) ), `convertType(value, type)`

**日志** —— 说 `getLogger()`, (中文(简体) ), `setLogger(logger)`, (中文(简体) ), `disableLogging()`, (中文(简体) ), `enableLogging()`

**杂项** —— 说 `logTicker(tick, options?)`, (中文(简体) ), `getTempDirectory(subfolder?)`

**错误分类** —— 说 `BaseError`, (中文(简体) ), `ValidationError`, (中文(简体) ), `ApiError`, (中文(简体) ), `FileError`, (中文(简体) ), `NetworkError`, (中文(简体) ), `DatabaseError`, (中文(简体) ), `ParsingError`, (中文(简体) ), `TimeoutError`

**类型** —— 说 `Logger`, (中文(简体) ), `ErrorCode`, (中文(简体) ), `Command`, (中文(简体) ), `OptionConfig`, (中文(简体) ), `ParsedArgs`, (中文(简体) ), `ConfigOptions<T>`, (中文(简体) ), `ValidationOptions`, (中文(简体) ), `ValidationResult`, (中文(简体) ), `SandboxOptions`, (中文(简体) ), `ExecuteOptions`

## 许可证

麻省理工学院

## 常见问题

### @happyvertical/utils 是什么？

用于 ID 生成、日期解析、 URL 处理、 字符串转换、 错误处理和记录的基础工具

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

在项目目录运行 npm install @happyvertical/utils，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 have-utils-context，可以用 npx have-utils-context 直接运行。

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

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

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

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

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

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

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

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

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

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

