@happyvertical/utils

中文文档
0.113.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 5.7万

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

中文使用文档
文档目录12 节
  1. 安装
  2. 使用量
  3. ID 生成
  4. 字符串和 URL 工具
  5. 日期公用事业
  6. 错误分类
  7. 代码提取和沙盒
  8. CLI 参数分析
  9. 环境配置
  10. 日志
  11. API 参考
  12. 许可证

@ happyvertical/ utils (欢快的垂直)

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

安装

pnpm add @happyvertical/utils

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

使用量

ID 生成

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 工具

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

日期公用事业

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()数字 :

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

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

代码提取和沙盒

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

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 参数分析

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' } }

环境配置

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' }
});

日志

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 共发布 131 个版本,首次发布于 2026/06/23;过去 12 个月发布了 131 个版本。

版本发布日期距今
0.113.1latest2026/11/17今天
0.113.02026/11/152 天前
0.112.32026/11/134 天前
0.112.22026/11/125 天前
0.112.02026/11/125 天前
0.112.12026/11/125 天前

关于 @happyvertical/utils 的常见问题

@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 和提交记录判断。