工具函数

@zealous-admin/utils 是 monorepo 内部工具包：不发布 npm，仅在本仓库内通过 workspace 源码直连导入（package.json 已标记 private: true，无独立构建链路，由根应用构建与根 typecheck 直接消费 TS 源码）。分为 data / env / file / json / parse / time / tree 七大模块，零外部依赖、纯函数定位（不引入 React Hook）。

使用

monorepo 内直接导入（无需安装步骤）：

import { deepClone, filterTree, safeJsonParse } from '@zealous-admin/utils'

推荐能力：tree（filterTree / flattenTree / mapTree / findTreeNode）、json（safeJsonParse）、deepClone、sortBy、downloadBlob。

模块总览

模块	说明	文档链接
data	数据操作工具：深拷贝、分组、排序、去重、扁平化等	查看详情
env	⚠️ 仅维护存量：环境检测工具	查看详情
file	文件处理工具：下载触发、大小格式化、Base64 转换、类型判断等	查看详情
json	安全 JSON 解析：判别联合替代 try/catch 与 null 哨兵	查看详情
parse	⚠️ 仅维护存量：身份证验证和信息提取	查看详情
time	⚠️ 仅维护存量：日期时间工具	查看详情
tree	树结构操作：展平、自底向上映射、搜索过滤、深度优先查找	查看详情

能力治理约定（2026-10）：env / time / parse 三个模块已标记 @deprecated，仅维护存量调用，不推荐新代码使用；新代码请按场景选用原生 API、dayjs 或 ahooks。推荐能力为 tree / json / deepClone / sortBy / downloadBlob；其余低频 API（groupBy / merge / unique / fileToBase64 / formatFileSize / isImage 等）保留但不主动推荐。

快速示例

tree 模块

import { filterTree, flattenTree, mapTree } from '@zealous-admin/utils'

const visible = filterTree(items, item => item.name.includes(keyword))
const allIds = flattenTree(items).map(item => item.id)
const treeData = mapTree(depts, (node, children) => ({ key: node.id, title: node.name, ...(children.length ? { children } : {}) }))

json 模块

import { safeJsonParse } from '@zealous-admin/utils'

const parsed = safeJsonParse<Record<string, unknown>>(raw)
if (parsed.ok)
  use(parsed.value)

data 模块（deepClone / sortBy）

import { deepClone, sortBy } from '@zealous-admin/utils'

const copy = deepClone(original)
const sorted = sortBy(items, 'createdAt', 'desc')

file 模块（downloadBlob）

import { downloadBlob } from '@zealous-admin/utils'

downloadBlob(new Blob([csv], { type: 'text/csv;charset=utf-8' }), 'export.csv')