跳到主要内容

utils

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

功能特性​

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

安装​

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

使用​

// UTL-031:此前示例里的 deepClone / formatTime 在包里并不存在,照抄会直接编译失败
import { cloneDeep, debounce, formatPassTime } from '@aiao/utils';

const copy = cloneDeep({ nested: { value: 1 } });
const onInput = debounce((text: string) => console.log(text), 300);
const elapsed = formatPassTime(startedAt, new Date());

Fileoverview​

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

Classes​

ClassDescription
AsyncQueueExecutor有并发上限的异步任务队列。
EventDispatcher类型安全的同步事件调度器。
IdleTimer浏览器空闲检测。
LeaderElection基于 Web Locks API 的 Leader Election 实现(带 BroadcastChannel 降级) 用于在多个浏览器 tab/window 之间选举唯一的 leader
LifecycleScope一段代码的存活期:把「取得某种所有权」与「如何放弃它」成对登记, 到期时逆序、串行地全部撤销。
LifecycleScopeDisposedError在已释放(disposed)或正在释放(disposing)的作用域上登记时抛出。
OpfsRouteSync把路由路径同步到 OPFS 浏览器视图,串行化并发请求。
PersistedStateRegistry按 namespace / name 两级复用的持久化状态注册表。

Interfaces​

InterfaceDescription
BroadcastTopic-
CronParts-
CronPartsDescription-
ErrorResult错误结果。
EventMap事件名称到事件数据的默认映射。
ExecutorStatusAsyncQueueExecutor.getStatus 的返回值。
IdleTimerOptionsIdleTimer 的构造参数。
IEventDispatcher-
OpfsRouteActionsOpfsRouteSync.sync 需要的两个副作用回调。
PerformChunkHandleperformChunk 的控制句柄。
PersistedStateEntry一个 namespace + name 的持久化状态入口。
PersistedStateRegistryOptionsPersistedStateRegistry 的构造选项。
QueryMethodRepository 查询方法类型 接受任意选项参数,返回 Observable
ScopeEntryLifecycleScope.getEntries 返回的快照节点。
SuccessResult成功结果。

Type Aliases​

Type AliasDescription
AcquireResultLifecycleScope.acquire 的 setup 返回值:交出撤销方式, 或返回 undefined 表示这次副作用无需释放。
AnyFunction可表示任意参数签名的通用函数约束。
BooleanObject持有 [[BooleanData]] 内部槽的包装对象。
DeepPartial创建一个类型的深度部分类型 所有属性(包括嵌套对象和数组元素的属性)都变为可选
EventListener事件监听器。
MSTime-
OpfsEntryKind-
Result成功数据与错误数据互斥的结果类型。
ScopeDisposer撤销一次登记的句柄。
TaskId任务去重标识。相同 id 的任务在前一次未结算前会复用同一个 Promise。

Variables​

VariableDescription
BASE_52_DIGITSbase-52 字母表:A-Z + a-z
BASE_62_DIGITSbase-62 数字字母表:0-9 + A-Z + a-z
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 主题。
createQueryOptionsKey计算查询选项的内容 key,并把游标实体投影成确定的数据快照。
createStableKey把任意可序列化的值转成稳定字符串 key,用于「内容是否变化」的判定。
dateStringToDateUTC 时间转换
dateStringWithTimezoneUTC 时间转换
debounce创建一个防抖函数,确保函数在最后一次调用后延迟指定时间才执行 连续调用会重置计时器,适用于处理频繁触发的事件(如滚动、输入框输入)
decodeJWTPayload解码 JWT token 的 payload 段
decompressFromBase64Url从 URL 安全的 Base64 解压字符串
deepFreeze深度冻结对象及其所有嵌套属性,使其不可修改 递归遍历对象的所有属性,对每个对象和函数属性调用 Object.freeze()
describeCron解析并描述 Cron 表达式
describeCronParts解析并描述 Cron 表达式
difference计算两个数组的差异,返回仅存在于第一个数组中且不在第二个数组中的元素 元素比较使用严格相等运算符 (===),因此对象仅在引用相同时被视为相等 结果数组保留元素在原数组中的出现顺序
emptyFunction空函数,不执行任何操作 常用作默认回调函数或占位符函数
flatten将嵌套一层的数组扁平化为一维数组 仅处理数组中的直接嵌套数组元素,不进行深度扁平化
flattenDeep将任意深度的嵌套数组完全扁平化为一维数组
flattenPathObjectToPlainObject将扁平路径对象转换为嵌套普通对象
formatCountdown倒计时
formatDate把时间戳格式化成 zh-CN 的「年-月-日 时:分」。
formatFileSize把字节数格式化成带单位的可读字符串。
formatPassTime格式化流逝时间(如"3小时前")
generateKeyBetween在两个排序键之间生成一个新的排序键 用于在有序列表中插入新项目,支持任意位置插入
generateKeysBetween在两个排序键之间生成 n 个排序键 用于批量插入多个项目到有序列表中
get安全读取点号、方括号或逗号分隔的嵌套路径
getFileCategory按扩展名归类文件。
getFileExtension取文件名的扩展名,小写、不含点。
getRepositoryMethod从 EntityType 中安全地获取查询方法
has检查对象是否包含指定的嵌套自有属性。
hasRepositoryMethod检查对象是否具有指定的查询方法
intersection计算多个数组的交集,返回所有输入数组中都存在的元素 使用严格相等运算符 (===) 进行元素比较,结果数组保留第一个数组中的元素顺序 如果输入单个数组,则返回该数组的去重版本
isActiveTimeWindow时间窗是否需要真正挂入管道。
isArrayBuffer检查值是否为ArrayBuffer类型 使用instanceof运算符进行判断
isBoolean检查值是否为布尔原始值。
isBooleanLike检查值是否为布尔原始值或 Boolean 包装对象。
isDate检查值是否为Date对象 使用instanceof和Object.prototype.toString.call()两种方式进行判断
isEmpty按工具库契约判断值是否为空
isEqual深度比较两个值是否相等
isEqualDate-
isEqualUint8Array-
isFloat判断是否为浮点数(有限且带小数部分)。
isFunction检查值是否为可调用函数,并保留已有函数签名。
isImageType判断文件是否为图片。
isInt-
isIntArray-
isISODateString判断字符串是否为带时区的完整 ISO 日期时间。
isMilliseconds检查是否是毫秒数
isMSTime检查是否是 ms 时间字符串
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 时间转换为毫秒
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。
renameOpfsEntry校验 OPFS 重命名请求;在平台提供原子且不覆盖目标的移动操作前直接拒绝。
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
withTimeWindows按窗口配置给一条流挂上防抖 / 采样。
zipObject创建一个对象,将键数组和值数组/函数配对组合 支持多种值来源:固定值、值数组或值生成函数

References​

noop​

Renames and re-exports emptyFunction