sakura-utils

sakura-utils 是一个面向前端场景的 JavaScript / TypeScript 通用工具库，覆盖数据结构处理、URL 与浏览器辅助、本地缓存、异步控制、安全与校验等高频能力。

为什么用

• 覆盖 22 个公开模块，当前自动索引 230 个方法
• 支持根导入与子路径按需导入，适合业务项目按模块拆分使用
• 提供严格的 TypeScript 类型声明，并通过消费者侧类型检查验证
• 运行时测试、类型测试、导出校验、打包 dry-run 全链路覆盖
• README、文档站、AI 元数据复用同一份自动生成数据源

安装

pnpm add sakura-utils

快速开始

import { uniqueArray, parseUrl, createNamespacedStorage } from 'sakura-utils'

const idList = uniqueArray([1, 1, 2, 3])
const urlInfo = parseUrl('https://example.com/path?tab=1')
const userStorage = createNamespacedStorage('user')

userStorage.set('profile', { id: 1, name: 'Sakura' })

console.log(idList)
console.log(urlInfo.query)
console.log(userStorage.get('profile'))

按需导入

// 根入口导入，适合项目快速接入
import { uniqueArray, parseUrl, createNamespacedStorage } from 'sakura-utils'

// 子路径导入，适合按模块拆分和优化引用边界
import { concurrentLimit } from 'sakura-utils/async'
import { listToTree } from 'sakura-utils/tree'
import { isElementInViewport } from 'sakura-utils/browser'

常用场景

列表加工与 URL 解析

适合列表去重、对象列表唯一化、地址解析和查询参数读取。

import { uniqueBy } from 'sakura-utils/array'

const result = uniqueBy(/* array */, /* key */)
console.log(result)

import { parseUrl } from 'sakura-utils/url'

const result = parseUrl(/* url */, /* base */)
console.log(result)

缓存封装与异步调度

适合本地缓存命名空间封装、接口并发控制和请求治理。

import { createNamespacedStorage } from 'sakura-utils/storage'

const result = createNamespacedStorage(/* namespace */, /* storage */)
console.log(result)

import { concurrentLimit } from 'sakura-utils/async'

const result = concurrentLimit(/* tasks */, /* limit */)
console.log(result)

树结构与浏览器交互

适合菜单树处理、节点路径查找、滚动定位与视口判断。

import { listToTree } from 'sakura-utils/tree'

const result = listToTree(/* list */, /* options */)
console.log(result)

import { isElementInViewport } from 'sakura-utils/browser'

const result = isElementInViewport(/* target */, /* fullyVisible */)
console.log(result)

推荐先看这些模块

• array：数组处理，适合 列表加工 / 表格数据处理 / 选项集整理
• url：URL 处理，适合 URL 拼接 / 路径规范化 / 地址解析
• storage：本地存储，适合 缓存读写 / 命名空间缓存 / 过期控制
• async：异步控制，适合 请求去重 / 并发调度 / 任务中断
• tree：树结构处理，适合 树形列表转换 / 节点过滤 / 路径查找
• browser：浏览器环境，适合 滚动定位 / 视口判断 / 剪贴板操作

模块总览

| 模块 | 描述 | 方法数 | 运行环境 | 典型场景 | |------|------|--------|----------|----------| | array | 数组处理 | 23 | browser, node, ssr, worker | 列表加工 / 表格数据处理 / 选项集整理 | | async | 异步控制 | 5 | browser, node, ssr, worker | 请求去重 / 并发调度 / 任务中断 | | browser | 浏览器环境 | 12 | browser | 滚动定位 / 视口判断 / 剪贴板操作 | | color | 颜色处理 | 7 | browser, node, ssr, worker | 主题色转换 / 颜色格式互转 / 透明度处理 | | date | 日期时间 | 23 | browser, node, ssr, worker | 时间格式化 / 时间范围计算 / 相对时间展示 | | file | 文件处理 | 31 | browser, node | 文件上传前处理 / base64 转换 / 下载辅助 | | function | 函数工具 | 8 | browser, node, ssr, worker | 防抖节流 / 重试封装 / 超时控制 | | number | 数字处理 | 10 | browser, node, ssr, worker | 精度处理 / 范围限制 / 金额展示 | | object | 对象处理 | 21 | browser, node, ssr, worker | 对象取值 / 深度合并 / 字段裁剪 | | params | 查询参数处理 | 7 | browser, node, ssr, worker | 查询串读写 / URL 参数合并 / 路由参数处理 | | performance | 性能测量 | 3 | browser, node, ssr, worker | 性能打点 / 耗时记录 / 同步异步测量 | | random | 随机生成 | 4 | browser, node, ssr, worker | 随机 ID / 随机数据 / 随机区间值 | | security | 安全辅助 | 8 | browser, node, ssr, worker | 敏感信息脱敏 / JSON 安全解析 / 短 ID 生成 | | storage | 本地存储 | 8 | browser | 缓存读写 / 命名空间缓存 / 过期控制 | | string | 字符串处理 | 6 | browser, node, ssr, worker | 命名格式转换 / 字符串截断 / 文本脱敏 | | text | 文本处理 | 2 | browser, node, ssr, worker | 文本宽度计算 / 字符长度估算 | | tree | 树结构处理 | 8 | browser, node, ssr, worker | 树形列表转换 / 节点过滤 / 路径查找 | | type | 类型判断 | 19 | browser, node, ssr, worker | 类型守卫 / 空值判断 / 运行时分支 | | unit | 单位转换 | 1 | browser, node, ssr, worker | 尺寸补单位 / 样式值处理 | | url | URL 处理 | 7 | browser, node, ssr, worker | URL 拼接 / 路径规范化 / 地址解析 | | utils | 通用工具 | 9 | browser, node, ssr, worker | 剪贴板兼容 / 睡眠等待 / 杂项工具兼容 | | validate | 校验工具 | 8 | browser, node, ssr, worker | 表单校验 / 账号规则校验 / 格式判断 |

热门方法

array

• uniqueArray - 数组去重
• uniqueDeepArray - 数组深层去重(二维数组, 三维数组....)
• flatArray - 扁平化数组
• uniqueFlatArray - 数组扁平化去重
• totalSum - 计算总和
• randomSortArray - 随机排序数组

url

• parseUrl - 解析 URL，并输出结构化字段和查询参数对象。
• joinUrl - 按路径片段拼接 URL。
• normalizeUrl - 规范化 URL，去除重复斜杠并保留查询参数与 hash。
• resolveRelativeUrl - 基于基础地址解析相对路径。
• isAbsoluteUrl - 判断地址是否为绝对 URL。
• isHttpUrl - 判断地址是否为 HTTP 或 HTTPS URL。

storage

• getStorage - 读取缓存值。
• setStorage - 写入缓存值。
• removeStorage - 删除指定缓存值。
• clearStorage - 清空缓存。
• setStorageWithExpire - 写入带过期时间的缓存值。
• getStorageWithExpire - 读取带过期时间的缓存值，过期后自动删除。

async

• concurrentLimit - 按并发上限执行异步任务队列，并保持结果顺序稳定。
• queueAsyncTasks - 按顺序串行执行异步任务列表。
• parallelSettled - 并行执行异步任务并返回 settled 结果。
• abortablePromise - 为异步任务创建可中断 Promise 包装。
• dedupeRequest - 为异步请求建立按参数去重的调用包装。

tree

• listToTree - 将列表结构转换为树结构。
• treeToList - 将树结构拍平成列表。
• findTreeNode - 在树结构中查找首个命中的节点。
• getTreePath - 获取树节点路径，结果包含从根到当前节点的所有节点。
• walkTree - 遍历整棵树，并对每个节点执行回调。
• filterTree - 过滤树节点，若子节点命中则保留祖先节点并裁剪其子树。

browser

• copyText - 复制文本到剪贴板。
• readClipboardText - 读取剪贴板中的文本内容。
• openInNewTab - 在新标签页打开链接。
• scrollToTop - 滚动到页面顶部。
• scrollToElement - 滚动到指定元素位置。
• getViewportSize - 获取当前视口尺寸。

文档与元数据

• README 由 pnpm run build:readme 自动生成
• 文档站构建命令：pnpm run build:docs
• AI 元数据文件：docs/metadata/ai-metadata.json
• 自动生成脚本：scripts/generate-docs-metadata.mjs、scripts/generate-readme.mjs

开发校验

pnpm run test
pnpm run test:typecheck
pnpm run build:release
pnpm run release:check

License

MIT