@cclr/utils

utils

常用业务工具集合（数据处理、URL、定时器、拦截器、颜色与数字工具）。

Usage

npm i @cclr/utils

import {
  deepClone,
  deepMergeObj,
  jsonParseSafe,
  jsonStringifySafe,
  randomInt,
  debounce,
  uriParseUrl,
  Color,
  Num,
} from '@cclr/utils';

const copy = deepClone({ a: 1 });
const merged = deepMergeObj({ a: 1 }, { b: 2 });
const n = randomInt(1, 10);

const json = jsonStringifySafe({ a: 1 });
const data = jsonParseSafe(json, {});

const run = debounce(() => console.log('run'), { wait: 300 });
run();

const url = uriParseUrl('https://a.com/user?id=1#info');
const hex = Color.randomHex();
const fixed = Num.toFixed(1.236, 2);

API 说明

数据处理

• deepClone(obj)：使用 JSON 方式深拷贝对象/数组。
• deepCompareJson(a, b)：使用 JSON 序列化比较两个值是否相等。
• enumMapToList(enumValue, map)：把枚举值和文案映射转为 [{ value, label }]。
• deepFilterNil(object)：递归移除对象和数组中的 null/undefined。
• enumToArray(e)：将枚举（对象）转换为 key 数组结构。
• listToMap(list, key)：将数组按指定字段转换为映射对象。
• deepMergeObj(orange, target)：深度合并对象，返回新对象。
• numInRange(num, [min, max])：判断数字是否落在闭区间内。
• uuid(length?)：生成指定长度 UUID 风格字符串（默认 36）。
• jsonStringifySafe(data, defaultValue?, options?)：安全序列化 JSON，失败时返回默认值。
• jsonParseSafe(text, defaultValue?)：安全解析 JSON 字符串，失败时返回默认值。

流程控制

• Interceptor<T>：拦截器类，支持 use/eject/clear/forEach/run。
• compose(...funcs)：将多个函数从右到左组合成一个函数。
• getOnionFun(ctx, funs)：按上下文组装并返回洋葱执行函数。

数字工具

• randomInt(start?, end?)：生成 start~end 的随机整数（含边界）。
• toFixed(num, fix?)：数字保留指定小数位并返回 number。
• Num.randomInt(start?, end?)：同 randomInt，数字工具命名空间调用方式。
• Num.toFixed(num, fix?)：同 toFixed，数字工具命名空间调用方式。

定时器

• debounce(cb, options?)：防抖函数，返回值附带 cancel/flush/fun。
• throttle(cb, options?)：节流函数，返回值附带 cancel/flush/fun。
• sleep(time?)：延迟指定毫秒后 resolve 的 Promise。

URL 与路径

• uri：URL 工具对象（含 parseUrl/getPathArr/getQuery/... 方法，已废弃，推荐使用下方独立导出）。
• parseUrl(url)：解析 URL 为结构化对象。
• getPathArr(url)：获取 URL 路径数组。
• getPathStr(url)：获取 URL 路径字符串。
• getQuery(url)：获取 URL 查询字符串（不含 ?）。
• getQueryObj(url)：获取 URL 查询参数对象。
• toQueryString(params)：对象转换为查询字符串。
• addQuery(url, queryObj)：为 URL 追加/覆盖查询参数。
• combine(urlObj)：将 URL 结构对象重新拼接为字符串。
• pathJoin(...paths)：按 URL 规则拼接路径片段。
• update(url, urlObj)：按配置更新 URL（包含 query 更新）。
• uriParseUrl(url)：parseUrl 的别名导出。
• uriGetPathArr(url)：getPathArr 的别名导出。
• uriGetPathStr(url)：getPathStr 的别名导出。
• uriGetQuery(url)：getQuery 的别名导出。
• uriGetQueryObj(url)：getQueryObj 的别名导出。
• uriToQueryString(params)：toQueryString 的别名导出。
• uriAddQuery(url, queryObj)：addQuery 的别名导出。
• uriCombine(urlObj)：combine 的别名导出。
• uriPathJoin(...paths)：pathJoin 的别名导出。
• uriChange(url, urlObj)：update 的别名导出。
• uriGetQueryParams(name, url?)：从 URL 中读取指定 query 参数值。
• uriHasHost(url)：判断 URL 是否包含 host 部分。

正则常量

• URL_REGEX：URL 解析正则。
• QUERY_REGEX：查询字符串提取正则。
• HASH_REGEX：哈希片段提取正则。
• PATHNAME_REGEX：路径部分提取正则。

颜色工具

• Color.hexToHsl(hex)：#hex 转 HSL 数组。
• Color.hexToRgb(hex)：#hex 转 RGB 数组。
• Color.hslToRgb(h, s, l)：HSL 转 RGB 数组。
• Color.hslToRgbString(h, s, l)：HSL 转 rgb(r,g,b) 字符串。
• Color.randomHex()：生成随机十六进制颜色。
• Color.randomHSL(params?)：生成随机 HSL 数值。
• Color.randomHSLString(params?)：生成随机 hsl(...) 字符串。

类型

• IUrl：URL 结构化对象类型定义。