@jhongxu/utils

通用工具函数库。

安装

pnpm add @jhongxu/utils

使用

支持 根路径（antd 风格）与 子路径 两种写法，tree-shake 效果等价；请使用静态具名导入：

// 根路径（推荐，简洁）
import { createLogger, toArray, deepMerge, debounce, constate } from "@jhongxu/utils";

// 子路径（语义更明确，与子模块一一对应）
import { createLogger } from "@jhongxu/utils/logging";
import { toArray } from "@jhongxu/utils/array";
import { debounce } from "@jhongxu/utils/vendor";

根入口 @jhongxu/utils 通过显式 named re-export 聚合全部子模块，不使用 export *。

Logging 配置

生产环境默认只输出 warn / error，开发环境默认输出 debug 及以上。可通过以下键覆盖（localStorage 与 process.env 同名，优先级高于环境默认）：

| 键 | 说明 | | ---------------------- | ---------------------------------------------------------------- | | JHONGXU_LOGGER_LEVEL | silent | warn | info | debug（或 consola 数字 level） | | JHONGXU_LOGGER_TAGS | 逗号分隔的 tag 列表；未设置时不过滤 |

import { createLogger, refreshLoggerConfig } from "@jhongxu/utils";
// 或 import { createLogger, refreshLoggerConfig } from "@jhongxu/utils/logging";

const logger = createLogger().withTag("dialog");
logger.debug("only in dev or when level allows");

浏览器控制台临时调试：

localStorage.setItem("JHONGXU_LOGGER_LEVEL", "debug");
localStorage.setItem("JHONGXU_LOGGER_TAGS", "dialog");
location.reload(); // 或调用 refreshLoggerConfig()

根入口与子路径均可 tree-shake；实现仍按领域拆文件，重依赖（p、vendor）在独立模块中。

通用工具（源自 @antfu/utils）

子路径按领域暴露，便于按需引用：

| 子路径 | 内容 | 运行时依赖 | | ------------------------ | --------------------------------------------------- | ------------------- | | @jhongxu/utils/array | toArray、partition、uniq、range… | 无 | | @jhongxu/utils/object | objectMap、deepMerge、objectPick… | 无 | | @jhongxu/utils/string | template、slash、randomStr… | 无 | | @jhongxu/utils/promise | sleep、createPromiseLock… | 无 | | @jhongxu/utils/math | clamp、lerp、sum… | 无 | | @jhongxu/utils/p | 异步链 p(items).map().filter() | p-limit | | @jhongxu/utils/vendor | debounce、throttle | throttle-debounce | | @jhongxu/utils/types | Arrayable、Nullable 等类型 | 无（仅类型） | | 其他 | base、equal、function、guards、is、time | 无 |

归属说明见 ANTFU_UTILS.md。

目录结构

src/
├── index.ts
├── logging/
├── form/
├── react/
├── array/
├── object/
├── string/
├── promise/
├── math/
├── p/
├── vendor/
├── types/
└── …（base、equal、function、guards、is、time）

开发

vp install
vp test
vp pack

Tree-shaking 约定

本包已配置 unbundle 多入口构建与 sideEffects: false。开发新模块时请遵守：

1. 按领域分目录：每个子路径对应 src/<domain>/index.ts；vite.config.ts 使用 src/index.ts 与 src/*/index.ts 扫描。
2. 避免 barrel 顶层副作用：不要在 index.ts 顶层执行逻辑（如初始化单例、改全局状态、import "./styles.css"）。
3. 避免 export * from：优先显式 export { x } from "./x.js"，或在入口文件直接 export function x。
4. 重依赖独立子路径：p（p-limit）、vendor（throttle-debounce）与纯函数模块分开。
5. 新增子路径后：更新根 src/index.ts 的显式 re-export，并执行 vp pack。
6. 消费方写法：import { toArray } from "@jhongxu/utils" 或 import { toArray } from "@jhongxu/utils/array"；避免 import * as。