toolkit-v1

v1.2.2

Published

10 days ago

零运行时依赖的前端工具库：ValueEnum/Select 字典、object/crypto/worker/browser 等 14 个子路径 ESM+CJS 导出，TypeScript 开箱即用

0High
0Medium
0Low

li19961223

iccp valueEnum select constants enum utils frontend typescript zero-dependencies web-crypto web-worker browser-utils protable ant-design

toolkit-v1

前端常用纯工具库。
零运行时 npm 依赖 — 加解密用 Web Crypto，Worker 用原生 API
14 个子路径导出 — 按需 import，Tree-shaking 友好
ESM + CJS 双格式 — 自带 TypeScript 类型声明
不含 HTTP / request — 网络层由业务仓 axios / Umi request 负责

开发约束（版本路线、API 审批、禁止自研清单）：docs/DEV-CONSTRAINTS.md

仓库与交互 Demo：gitee.com/web1996/toolkit

安装

npm install toolkit-v1
# 或
yarn add toolkit-v1
pnpm add toolkit-v1

环境：浏览器侧 ES2020+；Node ≥ 18 仅用于本仓库开发/构建。

快速开始

字典 / ProTable / Select（最常用）

import { defineValueEnumBundle } from 'toolkit-v1';

const status = defineValueEnumBundle({
  1: { text: '启用', color: 'green' },
  0: { text: '停用', color: 'default' },
});

// status.options   → Ant Design Select 下拉
// status.valueEnum → ProTable 状态列 valueEnum
// status.color     → 颜色切片（可选）

主入口常用工具

import { stripUndefined, parseQuery, uuidV4, deepMerge } from 'toolkit-v1';

stripUndefined({ a: 1, b: undefined });        // { a: 1 }
parseQuery('?page=2&status=1');                // { page: '2', status: '1' }
uuidV4();                                      // RFC4122 v4
deepMerge({ a: { b: 1 } }, { a: { c: 2 } });  // { a: { b: 1, c: 2 } }

主入口 compat + crypto（一行导入）

import { isSubtleCryptoAvailable, sha256 } from 'toolkit-v1';

if (isSubtleCryptoAvailable()) {
  const hash = await sha256('hello');
}

compat 探测函数已从主入口 re-export，与子路径 toolkit-v1/compat 等价。生产大包、整模块引用请用子路径，见 docs/IMPORT-STRATEGY.md。

按需子路径

import { groupBy } from 'toolkit-v1/array';
import { retry, withTimeout } from 'toolkit-v1/async';
import { copyText, downloadJson } from 'toolkit-v1/browser';
// 与主入口等价，子路径更利于 tree-shaking：
import { isSubtleCryptoAvailable } from 'toolkit-v1/compat';
import { sha256 } from 'toolkit-v1/crypto';
import { runInWorker } from 'toolkit-v1/worker';

子路径导入

下表各模块的常用 API 亦可从主入口 import { ... } from 'toolkit-v1' 导入；子路径适合按模块边界引用与体积优化。详见 IMPORT-STRATEGY.md。

| 子路径 | 说明 | |--------|------| | toolkit-v1 | 主入口：constants + 精选 utils 再导出 | | toolkit-v1/constants | ValueEnum / Select 字典转换 | | toolkit-v1/compat | 环境探测（HTTPS、SubtleCrypto、Storage、Worker） | | toolkit-v1/guard | 类型守卫 | | toolkit-v1/object | 对象合并、路径读写、去 undefined | | toolkit-v1/convert | px/rem、文件大小、相对时间、数字/百分比 | | toolkit-v1/crypto | Base64、SHA-256、AES-GCM | | toolkit-v1/worker | Web Worker offload | | toolkit-v1/browser | 剪贴板、下载、Storage、选文件、分享 | | toolkit-v1/string | 截断、安全 JSON、命名转换、HTML 转义 | | toolkit-v1/url | Query 解析与拼接 | | toolkit-v1/array | 去重、分组、分块 | | toolkit-v1/async | sleep、retry（含指数退避）、poll、超时 | | toolkit-v1/id | uuid、随机 id |

模块 API 一览

`toolkit-v1/constants` — 字典与枚举

| API | 说明 | |-----|------| | defineValueEnumBundle(valueEnum, slices?) | 一次生成 options / valueEnum / color 等切片 | | convertArrToOptionsAndMap(list, { labelKey, valueKey }) | 接口数组 → Select options + map | | convertMapToOptions(map) | 简单 map → options | | convertValueEnumToOptions(valueEnum) | ValueEnum → options | | convertOptionsToMap(options) | options → value→label map | | getValueEnum(textMap, extra?) | text map + color 等扩展字段 | | ValueEnumSwitch(valueEnum, field) | 按字段提取切片 |

`toolkit-v1/compat` — 环境探测

也可从主入口导入：import { isSubtleCryptoAvailable, ... } from 'toolkit-v1'。

| API | 说明 | |-----|------| | isSecureContext() | 是否 HTTPS / localhost | | isSubtleCryptoAvailable() | sha256 / AES 是否可用 | | isStorageAvailable() | localStorage 是否可用 | | isSessionStorageAvailable() | sessionStorage 是否可用 | | isIntlAvailable() | Intl 数字格式化是否可用 | | isWorkerSupported(options?) | Worker / Blob 内联是否可用 | | isClipboardReadAvailable() / isClipboardWriteAvailable() / isShareAvailable() | 剪贴板 / 分享（1.1） | | isFilePickerAvailable() | DOM file input（仅子路径） |

`toolkit-v1/guard` — 类型守卫

isPlainObject · isEmpty · assertDefined · isNil · isString · isNumber · isArray · isBoolean · isFunction · inRange

`toolkit-v1/object` — 对象

| API | 说明 | |-----|------| | deepMerge(target, source) | 深度合并；数组整体替换（非 lodash concat） | | pick / omit | 按 key 保留/排除 | | clonePlain | plain 对象浅递归克隆 | | stripUndefined | 递归删除 undefined 键 | | getPath(obj, 'a.b.c') | 点路径安全读取 |

1.2.0 当前 API 面： setPath · unsetPath · isEqualPlain（plain object/array 递归相等）

`toolkit-v1/convert` — 格式化

pxToRem · remToPx · formatBytes · parseBytes（有损往返，见下） · formatDuration · clamp · formatNumber · formatPercent · formatRelativeMs

formatBytes 默认按 1024 换算，显示 MB/KB/GB（非 MiB）；1000 换算传 { binary: false }。
parseBytes：parseBytes(formatBytes(n)) 可能 ≠ n（小数位四舍五入）。精确字节请保留原始 number。

`toolkit-v1/url` — Query

parseQuery · stringifyQuery · appendQuery · getQueryParam · removeQuery · mergeQuery · buildUrl · isAbsoluteUrl

`toolkit-v1/crypto` — 加解密

| API | 环境 | |-----|------| | base64Encode / base64Decode | HTTP / HTTPS 均可 | | sha256(text) | 需 secure context | | aesGcmEncrypt / aesGcmDecrypt | 需 secure context | | importAesGcmKey | 导入 AES 密钥 | | CryptoUnavailableError | SubtleCrypto 不可用时的 typed 错误 |

`toolkit-v1/worker` — 后台线程

| API | 说明 | |-----|------| | runInWorker({ fn, args, timeoutMs?, signal?, workerUrl?, payload? }) | 单次 Worker 任务 | | createWorkerRunner() | 复用单 Worker，run() + dispose() | | mapInWorker(items, mapper, { useRunner?, poolSize? }) | 批量映射；1.1 poolSize runner 池 | | WorkerRunError | 含 TIMEOUT / ABORT 等 code |

Worker 内函数通过序列化注入，不能访问外部闭包变量；参数请走 args。

`toolkit-v1/browser` — 浏览器能力

| API | 说明 | |-----|------| | copyText / readClipboardText / copyJson（1.1） | 剪贴板 | | downloadBlob / downloadText / downloadJson / downloadCsv | 触发文件下载 | | createStorage / createSessionStorage | Web Storage + TTL；不可用时 no-op | | readFileAsText / readFileAsDataUrl / readFileAsJson | FileReader 读文件 | | pickFiles({ accept?, multiple? }) | 唤起文件选择 | | openUrl / shareContent | 打开链接 / 系统分享 | | isOnline / getPreferredColorScheme | 网络与主题 |

`toolkit-v1/string` · `url` · `array` · `async` · `id`

// string — trim, padStart, padEnd, template
truncate · safeParseJson · camelToSnake · snakeToCamel · escapeHtml

// url — buildUrl, isAbsoluteUrl
parseQuery · stringifyQuery · appendQuery · getQueryParam · removeQuery

// array — flatten
unique · compact · chunk · groupBy

// async — defer, runWithConcurrency
sleep(ms) · retry(fn, { times, delayMs? }) · withTimeout(promise, ms)

// id
uuidV4() · randomId(prefix?)

典型场景示例

接口数组 → Select + 表格字典

import { convertArrToOptionsAndMap } from 'toolkit-v1/constants';

const { options, map } = convertArrToOptionsAndMap(
  [{ name: '启用', id: 1 }, { name: '停用', id: 0 }],
  { labelKey: 'name', valueKey: 'id' },
);

HTTP 页安全使用 crypto

import { isSubtleCryptoAvailable, sha256 } from 'toolkit-v1';
// 等价子路径：from 'toolkit-v1/compat' + from 'toolkit-v1/crypto'

if (isSubtleCryptoAvailable()) {
  const hash = await sha256(password);
} else {
  // 纯 HTTP 生产环境：改走服务端哈希
}

导出 JSON / 读配置文件

import { downloadJson, pickFiles, readFileAsJson } from 'toolkit-v1/browser';

downloadJson(rows, 'export.json');

const [file] = await pickFiles({ accept: '.json' });
const config = file ? await readFileAsJson(file, {}) : {};

列表 URL 同步筛选

import { parseQuery, appendQuery } from 'toolkit-v1/url';

const { page } = parseQuery(location.search);
const nextUrl = appendQuery('/list', { page: 2, status: 1 });

Worker offload 计算

import { runInWorker } from 'toolkit-v1/worker';

const sum = await runInWorker({
  fn: (a, b) => (a as number) + (b as number),
  args: [1, 2],
});

不稳定请求重试（配合业务 fetch）

import { retry } from 'toolkit-v1/async';

await retry(() => fetch('/api/x').then(r => r.json()), {
  times: 3,
  delayMs: 300,
});

浏览器与 HTTPS 兼容

官方基线：Chrome 90+ · Firefox 90+ · Safari 15+ · Edge 90+ · ES2020+
不支持 IE11。

| 能力 | 纯 HTTP | HTTPS / localhost | |------|:-------:|:-----------------:| | constants / guard / string / url / array | ✅ | ✅ | | base64Encode / base64Decode | ✅ | ✅ | | copyText / downloadJson / pickFiles | ✅ | ✅ | | createStorage（不可用则 no-op） | ✅ | ✅ | | sha256 / AES-GCM | ❌ | ✅ | | readClipboardText | ❌ | ✅ | | runInWorker | 视浏览器 | ✅ |

发布前可用 compat 探测：

import {
  isSecureContext,
  isSubtleCryptoAvailable,
  isStorageAvailable,
} from 'toolkit-v1';
// 或 from 'toolkit-v1/compat'（等价）

更完整矩阵见 BROWSER-SUPPORT.md；导入选型见 IMPORT-STRATEGY.md。

刻意不包含

| 类别 | 建议替代 | |------|----------| | HTTP / axios / Umi request | 业务仓 request 层 | | debounce / throttle | ahooks / lodash | | dayjs / moment | 项目已有日期库 | | lodash 全量 / cloneDeep 循环引用 | lodash / structuredClone | | qs 深度嵌套 query | qs 库 |

能力边界详表：UTILS-DEDUP-MATRIX.md · DEV-CONSTRAINTS.md
HTTP 模块移除说明：MIGRATION-REMOVE-REQUEST.md

完整文档与 Demo

npm 包内仅含 dist + README + LICENSE + CHANGELOG。以下资源在 Gitee 仓库：

| 资源 | 链接 | |------|------| | 交互 Demo（12 模块 + Guard 面板） | Clone 后 yarn demo | | 全局开发约束 | docs/DEV-CONSTRAINTS.md | | 浏览器支持矩阵 | docs/BROWSER-SUPPORT.md | | 能力地图 | docs/CAPABILITY-MAP.md | | API 参数参考（Options 对象） | docs/API-PARAM-REFERENCE.md | | API 去重边界 | docs/UTILS-DEDUP-MATRIX.md | | Worker 选型 | docs/WORKER-GAP-AUDIT.md | | 质量审计 | docs/QUALITY-GAP-AUDIT.md | | 示例代码 | examples/ |

git clone https://gitee.com/web1996/toolkit.git
cd toolkit && yarn && yarn demo
# 浏览器打开终端提示的 localhost 地址

开发与发布

贡献者 / 维护者（普通使用方可跳过）：

yarn typecheck && yarn test && yarn build   # 本地验证
yarn demo                                    # 交互文档
yarn release:check                           # 发布前全量验收
yarn publish:npm                             # 发布（需 npm login）

变更记录

见 CHANGELOG.md（npm 包内同文件）。

1.0.0 — 首次公开发布，合并字典工具 + 14 个子路径 utils。

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

toolkit-v1

目录

安装

快速开始

字典 / ProTable / Select（最常用）

主入口常用工具

主入口 compat + crypto（一行导入）

按需子路径

子路径导入

模块 API 一览

toolkit-v1/constants — 字典与枚举

toolkit-v1/compat — 环境探测

toolkit-v1/guard — 类型守卫

toolkit-v1/object — 对象

toolkit-v1/convert — 格式化

toolkit-v1/url — Query

toolkit-v1/crypto — 加解密

toolkit-v1/worker — 后台线程

toolkit-v1/browser — 浏览器能力

toolkit-v1/string · url · array · async · id

典型场景示例

接口数组 → Select + 表格字典

HTTP 页安全使用 crypto

导出 JSON / 读配置文件

列表 URL 同步筛选

Worker offload 计算

不稳定请求重试（配合业务 fetch）

浏览器与 HTTPS 兼容

刻意不包含

完整文档与 Demo

开发与发布

变更记录

License

`toolkit-v1/constants` — 字典与枚举

`toolkit-v1/compat` — 环境探测

`toolkit-v1/guard` — 类型守卫

`toolkit-v1/object` — 对象

`toolkit-v1/convert` — 格式化

`toolkit-v1/url` — Query

`toolkit-v1/crypto` — 加解密

`toolkit-v1/worker` — 后台线程

`toolkit-v1/browser` — 浏览器能力

`toolkit-v1/string` · `url` · `array` · `async` · `id`