概述

平台无关工具函数集合，提供日期、存储、加密、ID 生成、数组、对象、路径与 query 工具，附带 path / web 子路径

概述

@skyroc/utils 是项目的通用工具包，分为三个入口：

入口	导入路径	适用环境
主入口	`@skyroc/utils`	平台无关（Node.js / 浏览器 / SSR 均可）
Path 子路径	`@skyroc/utils/path`	路径工具的独立子路径；常规使用可直接从主入口导入
Web 子路径	`@skyroc/utils/web`	仅浏览器环境

模块一览

模块	主要导出	说明
`cn`	`cn`	Tailwind class 合并
`Crypto`	`Crypto`	AES 对称加密
`nanoid`	`nanoid`	唯一 ID 生成
`klona`	`jsonClone`	JSON 安全深拷贝
`storage`	`createStorage`, `createLocalforage`	类型安全存储封装
`date`	`formatDate`, `addDate` 等 20+ 函数	分层日期工具
`array`	`toArray`, `arraysEqual`	数组工具
`reg`	`REG_USER_NAME` 等 7 个正则	常用校验正则
`object`	`shallowEqual`, `diffObject` 等	对象比较与 diff
`utils`	`isNil`, `isMacOs` 等	基础类型判断与环境检测
`path`	`deepGet`, `deepSet`, `deepUnset`, `unflatten` 等	深层路径读写与字段路径工具
`query`	`parseQuery`, `stringifyQuery`	URL query 字符串解析与序列化
`radash`	全部 radash 导出	函数式工具（re-export）→ radash 文档

以下模块有独立文档页，本页仅覆盖 cn、nanoid、jsonClone、object 和 radash 这几个相对轻量的模块。

cn — Tailwind class 合并

import { cn } from '@skyroc/utils';

组合 clsx 和 tailwind-merge：先用 clsx 处理条件 class，再用 twMerge 解决 Tailwind 工具类冲突。

cn('px-4 py-2', 'px-6');
// 'py-2 px-6'（px-4 被 px-6 覆盖）

cn('text-red-500', { 'font-bold': true, 'text-blue-500': false });
// 'text-red-500 font-bold'

cn('base-class', condition && 'extra-class', ['array-class']);
// 同 clsx 的所有参数形式均支持

nanoid — 唯一 ID 生成

import { nanoid } from '@skyroc/utils';

直接 re-export 自 nanoid，生成 URL 安全的随机唯一字符串，默认 21 位。

nanoid();      // 'V1StGXR8_Z5jdHi6B-myT'
nanoid(10);    // 'IRFa-VaY2b'（指定长度）

jsonClone — JSON 安全深拷贝

import { jsonClone } from '@skyroc/utils';

来自 klona/json 的快速深拷贝，基于 JSON 序列化实现。

限制： 仅支持 JSON 可序列化的类型，Date、Map、Set、Function、undefined 等会丢失或变形。

const original = { a: 1, b: { c: [2, 3] } };
const clone = jsonClone(original);

clone.b.c.push(4);
console.log(original.b.c); // [2, 3]（不受影响）

object — 对象工具

import { shallowEqual, diffObject, isObjectType, isEventObject } from '@skyroc/utils';

`shallowEqual(a, b)` → `boolean`

浅比较两个对象：先用 Object.is 判断引用，再逐键用 Object.is 比较一级属性值。

shallowEqual({ a: 1, b: 2 }, { a: 1, b: 2 }); // true
shallowEqual({ a: 1, b: { c: 3 } }, { a: 1, b: { c: 3 } }); // false（嵌套对象引用不同）

`diffObject<T>(obj1, obj2)` → `Partial<T>`

递归计算两个对象的差异，返回 obj2 中与 obj1 不同的部分。命名为 diffObject 以与 radash 的数组 diff 区分。

diffObject({ name: 'Alice', age: 30 }, { name: 'Alice', age: 31 });
// { age: 31 }

`isObjectType(value)` → `value is object`

判断值的 typeof 是否为 'object'（含 null）。

`isEventObject(event)` → `event is Event`

判断值是否为 Event 对象（非数组、非 null、非 Date 的普通对象）。

radash — 函数式工具集

import { group, unique, omit, pick, diff, ... } from '@skyroc/utils';

@skyroc/utils 完整 re-export radash 的所有导出，可直接从 @skyroc/utils 导入，无需单独安装 radash。

注意：radash 的 diff 是数组差集工具（返回第一个数组中不在第二个数组里的元素），本包的对象递归比较函数已重命名为 diffObject 以避免歧义。

常用函数（节选）：

函数	说明
`diff(array1, array2)`	数组差集，返回 array1 中不在 array2 里的元素
`group(list, fn)`	按 fn 结果分组，返回 `Record<key, T[]>`
`unique(list, fn?)`	数组去重，支持自定义 key
`omit(obj, keys)`	从对象中排除指定 key
`pick(obj, keys)`	从对象中选取指定 key
`alphabetical(list, fn)`	按字母顺序排序
`cluster(list, size)`	将数组分割为指定大小的分组
`sleep(ms)`	Promise 版 setTimeout
`retry(fn, options)`	带重试的异步函数执行

完整 API 列表见 radash 官方文档 →。

概述

On this page