跳到主要内容

utils

Aiao 项目通用工具库,提供常用的工具函数。

功能特性

  • 类型工具: TypeScript 类型增强
  • 字符串处理: 字符串常用操作
  • 时间处理: 日期时间相关工具
  • RxJS 工具: RxJS 辅助函数

安装

npm install @aiao/utils
# 或
pnpm add @aiao/utils

使用

import { deepClone, debounce, formatTime } from '@aiao/utils';

Fileoverview

Aiao 工具函数库 提供常用的工具函数,包括数组、异步、日期、加密、对象、字符串等

Classes

ClassDescription
AsyncQueueExecutor-
EventDispatcher类型安全的同步事件调度器。
IdleTimer浏览器空闲检测
LeaderElection基于 Web Locks API 的 Leader Election 实现(带 BroadcastChannel 降级) 用于在多个浏览器 tab/window 之间选举唯一的 leader
OpfsRouteSync-

Interfaces

InterfaceDescription
BroadcastTopic-
CronParts-
CronPartsDescription-
ErrorResult错误结果。
EventMap事件名称到事件数据的默认映射。
IEventDispatcher-
QueryMethodRepository 查询方法类型 接受任意选项参数,返回 Observable
SuccessResult成功结果。

Type Aliases

Type AliasDescription
AnyFunction可表示任意参数签名的通用函数约束。
DeepPartial创建一个类型的深度部分类型 所有属性(包括嵌套对象和数组元素的属性)都变为可选
EventListener事件监听器。
MSTime-
OpfsEntryKind-
Result成功数据与错误数据互斥的结果类型。

Variables

VariableDescription
BASE_62_DIGITS分数索引(Fractional Indexing)实现 基于 https://github.com/rocicorp/fractional-indexing
IMAGE_MIN_BASE64_BLACK最小的黑色图片Base64编码 1x1像素的黑色GIF图片,用于占位符或默认图片
IMAGE_MIN_BASE64_TRANSPARENT最小的透明图片Base64编码 1x1像素的透明GIF图片,用于占位符或默认图片
IS_BROWSER检测当前运行环境是否为浏览器环境 通过检查全局 window 对象是否存在来判断
isArray检查值是否为数组 这是对JavaScript内置Array.isArray函数的重导出
pool-
STORAGE_LABELS-
STORAGE_TESTID-

Functions

FunctionDescription
aesDecryptAES 解密
aesEncryptAES 加密
base64Decodebase64 解码
base64Encode将 UTF-8 文本或字节数据编码为 Base64。
camelCase转换为驼峰命名
canBeDate判断值能否表示有效日期。
canBeNumber检查值是否为有限数字或完整的十进制数字字符串。
capitalize首字母大写
capitalizeFirst-
checkOPFSAvailable异步检测 OPFS 是否真正可用
chunk将数组分割成指定大小的数组块 当数组长度不能被分割大小整除时,最后一个块将包含剩余的元素
cloneDeep深拷贝值
compressToBase64Url压缩字符串到 URL 安全的 Base64
createBroadcastTopic创建一个 BroadcastChannel 主题
dateStringToDateUTC 时间转换
dateStringWithTimezoneUTC 时间转换
debounce创建一个防抖函数,确保函数在最后一次调用后延迟指定时间才执行 连续调用会重置计时器,适用于处理频繁触发的事件(如滚动、输入框输入)
decodeJWTPayload解码 JWT token 的信息
decompressFromBase64Url从 URL 安全的 Base64 解压字符串
deepFreeze深度冻结对象及其所有嵌套属性,使其不可修改 递归遍历对象的所有属性,对每个对象和函数属性调用 Object.freeze()
describeCron解析并描述 Cron 表达式
describeCronParts解析并描述 Cron 表达式
difference计算两个数组的差异,返回仅存在于第一个数组中且不在第二个数组中的元素 元素比较使用严格相等运算符 (===),因此对象仅在引用相同时被视为相等 结果数组保留元素在原数组中的出现顺序
emptyFunction空函数,不执行任何操作 常用作默认回调函数或占位符函数
flatten将嵌套一层的数组扁平化为一维数组 仅处理数组中的直接嵌套数组元素,不进行深度扁平化
flattenDeep将任意深度的嵌套数组完全扁平化为一维数组
flattenPathObjectToPlainObject将扁平路径对象转换为嵌套普通对象
formatCountdown倒计时
formatDate-
formatFileSize格式化文件大小
formatPassTime格式化流逝时间(如"3小时前")
generateKeyBetween在两个排序键之间生成一个新的排序键 用于在有序列表中插入新项目,支持任意位置插入
generateKeysBetween在两个排序键之间生成n个排序键 用于批量插入多个项目到有序列表中
get安全读取点号、方括号或逗号分隔的嵌套路径
getFileCategory-
getFileExtension-
getRepositoryMethod从 EntityType 中安全地获取查询方法
has检查对象是否包含指定的嵌套自有属性。
hasRepositoryMethod检查对象是否具有指定的查询方法
intersection计算多个数组的交集,返回所有输入数组中都存在的元素 使用严格相等运算符 (===) 进行元素比较,结果数组保留第一个数组中的元素顺序 如果输入单个数组,则返回该数组的去重版本
isArrayBuffer检查值是否为ArrayBuffer类型 使用instanceof运算符进行判断
isBoolean检查值是否为布尔原始值或布尔包装对象
isDate检查值是否为Date对象 使用instanceof和Object.prototype.toString.call()两种方式进行判断
isEmpty按工具库契约判断值是否为空
isEqual深度比较两个值是否相等
isEqualDate-
isEqualUint8Array-
isFloat是否是浮点数
isFunction检查值是否为可调用函数,并保留已有函数签名。
isImageType-
isInt-
isIntArray-
isISODateString判断字符串是否为带时区的完整 ISO 日期时间。
isMSTime检查是否是毫秒时间戳
isNil检查值是否为null或undefined 使用严格相等(===)进行比较
isNumber检查值是否为非 NaN 的 number 原始值。
isNumberArray-
isObject检查值是否为纯对象(通过Object构造函数创建的对象) 排除数组、null、日期、正则表达式等特殊对象
isObjectLike-
isOPFSSupported检测当前环境是否暴露 OPFS API
isPlainObject检查值是否为纯对象(通过Object构造函数创建的普通对象) 排除数组、日期、正则表达式、Map、Set等特殊对象
isPreviewableType-
isPrimitive是否是原始类型(string、number、boolean、symbol、bigint、null、undefined)
isPromise检查值是否包含可调用的 then 方法。
isRegExp是否是正则表达式
isString检查值是否为字符串类型 使用typeof运算符进行判断,返回布尔值
isStringArray-
isSymbol-
isUint8Array检查值是否为Uint8Array类型 使用instanceof运算符进行判断
kebabCase转换为 kebab-case
logError以表格形式打印错误信息
msTimeToMillisecondsms 时间转换为毫秒 value https://github.com/vercel/ms
needArray将任意值标准化为数组格式
nextMacroTask在下一个宏任务中执行函数 使用 setTimeout(fn, 0) 将函数推迟到当前执行栈清空后执行
nextMicroTask将函数推迟到下一个微任务队列执行
numberStep将数值向上取整到最接近的步长倍数 常用于表单控件、网格布局等需要按固定间隔取值的场景
numberStepScreenSize根据设备像素比调整数值后,按步长取整 主要用于处理不同DPI屏幕下的尺寸计算,确保在高分辨率屏幕上保持合适的步长
numberStrip去除数字的无用小数位,解决浮点数精度问题 通过限制有效数字位数来消除JavaScript浮点数运算产生的微小误差 例如:0.1 + 0.2 通常得到 0.30000000000000004,使用本函数可得到 0.3
omit从对象浅拷贝中删除指定自有属性
omitBy创建排除满足断言属性后的新对象
once单次执行函数
orderBy根据指定属性和排序方向对数组进行多字段排序
parseChineseNumber解析中文数字
parseCron解析并描述 Cron 表达式
parseTime计算两个日期之间的时间差,并分解为年、月、日、时、分、秒
performChunk分片执行任务 只能在浏览器环境中执行 把一个大任务分片执行,每次执行一小部分任务,然后让出主线程,等待下一次执行
pick从对象中选取指定的属性,创建并返回一个新对象 只包含指定的自有属性,忽略继承属性和不存在的属性 当输入对象为null/undefined时,返回空对象
pickBy创建仅保留满足断言属性的新对象
plainObjectToFlattenPathObject将普通对象扁平化为路径键值对象
queryParse解析查询字符串,重复键聚合为字符串数组
queryStringify序列化为 URL 查询参数
randomArrayItem从数组中随机选择一个元素。
randomFloat生成指定范围内的随机浮点数 使用 Math.random() 生成 0 到 1 之间的随机数,然后映射到指定范围
randomInt生成随机整数
randomString使用 Web Crypto 和 rejection sampling 生成无偏随机字符串。
randomUintByLength生成指定位数的随机正整数 通过生成随机数字字符串然后转换为数字实现
randomUintString生成指定长度的数字字符串,非空结果的第一位不为 0。
renameOpfsEntrySafely renames one OPFS entry without overwriting an existing target.
requestIdleCallbackPolyfill-
rmbUppercase转换人民币大写
rsaDecryptRSA 解密
rsaEncryptRSA 加密
rsaGenerateKey生成 RSA 密钥对
set设置对象中指定路径的属性值,自动创建不存在的嵌套路径。 路径中的数字索引会创建数组;危险的原型链路径会抛出 TypeError。
setBase-
setWith使用自定义容器工厂设置嵌套路径。
similarity计算字符串相似度
sleep等待指定的毫秒数
snakeCase将字符串转换为蛇形格式
sortBy创建按直接属性自然升序排列的比较函数
startCase-
stringSingleline将多行文本转换为单行文本,移除多余的空白字符 去除首尾空白,并将连续的空白字符替换为单个空格
stringTemplate使用对象路径替换模板中的 ${path} 占位符
stringTime将时间数值格式化为带单位的字符串
stringToArrayBuffer字符串转 ArrayBuffer
throttle创建一个节流函数,确保函数在指定时间间隔内最多执行一次 与防抖不同,节流会定期执行函数,而非等待最后一次调用后执行,适用于限制高频事件(如滚动、调整大小)的触发频率
toInt将值转换为整数,使用向下取整(正数)和向上取整(负数)的策略
toPlainObject将值转换为只包含自有可枚举属性的普通对象
traverseObjectKeys深度优先遍历普通对象中的所有自有键
tryToNumber安全地将值转换为数字,只在能转换为有效数字时才转换 如果无法转换为有效数字(NaN、无穷大等),则返回原值不变
uint8ArrayToString将Uint8Array转换为UTF-8字符串 使用TextDecoder API进行解码,确保正确处理多字节字符
uncapitalize首字母小写
uncapitalizeFirst-
unionBy根据指定的键函数对数组进行去重,返回唯一元素的新数组 使用键函数提取每个元素的唯一标识符,保留第一次出现的元素
unixTimestamp获取当前 Unix 时间戳(秒)
urlJoin拼接 URL
utf8StringToArrayBufferUTF-8 字符串转 ArrayBuffer
zipObject创建一个对象,将键数组和值数组/函数配对组合 支持多种值来源:固定值、值数组或值生成函数

References

noop

Renames and re-exports emptyFunction