把旧工具库迁到 es-toolkit:一次 sheng-tool 现代化改造(2):用 JSDoc 生成测试与公共文档
把旧工具库迁到 es-toolkit:一次 sheng-tool 现代化改造
- 依赖、API 与发布边界的迁移
- 用 JSDoc 生成测试与公共文档(当前)
sheng-tool 原来的 @example 同时服务读者、测试与文档,这次迁移继续保留这个设计,但改用 TypeScript compiler API 读取 JSDoc。依赖、公开 API 和发布入口的调整见第一篇;这里集中说明示例怎样生成用例,未解析内容怎样报告,以及 TSDoc、手写测试和 TypeDoc 文档各自承担什么。API 行为仍以最终发布的 0.1.1 为准。
注释还是测试,但生成器换一套
新版继续保留 @example 作为测试来源,但不再依赖 TypeDoc 的旧内部结构,而是用 TypeScript compiler API 读取源码前导 JSDoc。
生成器现在支持三种输入:
表达式 // 期望值或表达式 // => 期望值:转成expect(表达式).toEqual(期望值)。表达式 // throws ErrorName:转成expect(() => 表达式).toThrow(ErrorName),适合说明不合理参数会报错。- 直接包含
expect(...)的代码块:保留成兜底能力,用于少数确实需要放进文档的异常或复杂 setup。
源码里的 @example 默认仍然保持普通示例。如果异常是公开行为,就用 // throws RangeError 这种读者能直接理解的写法;类型推导、循环引用这类测试细节继续放在 tests/ 里。
核心解析大概是这样:
export function parseAssertionLine(line: string): ExampleAssertion | undefined {
const normalizedLine = line.replace(/^\s*\*\s?/, '');
const matched = /^(?<expression>.+?)\s{2,}\/\/(?:\s*=>)?\s*(?<expected>.+?)\s*$/.exec(normalizedLine);
if (!matched?.groups) {
return undefined;
}
const expression = matched.groups.expression.trim().replace(/;$/, '');
const expected = matched.groups.expected.trim();
const throwAssertion = parseThrowAssertion(expression, expected);
if (throwAssertion) {
return throwAssertion;
}
if (!expression || !isExpectedExpression(expected)) {
return undefined;
}
return {
kind: 'equal',
expression,
expected,
};
}
无法解析的 @example 不会被悄悄忽略,而是写进 tests/generated/examples.report.json 并让生成命令失败。浏览器模块依然跳过自动生成,因为 DOM、剪贴板和视口判断更适合放在 tests/browser 的 happy-dom 用例里;但跳过原因也会写进 report。
当前 report 大概长这样:
{
"generated": {
"cases": 92,
"assertions": 225,
"executableBlocks": 0
},
"unparsed": []
}
生成结果放在 tests/generated/examples.test.ts,并加了提示:
// @ts-nocheck
// 这个文件由 scripts/generate-example-tests.ts 生成,不要手写修改。
这里选择 @ts-nocheck 是有意的。注释里的例子首先用于说明并验证运行行为,类型边界另写类型测试。若要求每个文档示例同时承担类型测试,就可能为了构造非法输入、标记预期错误而打断原本的用法说明。
生成测试之外,运行环境、类型推导和循环引用等边界仍需手写用例;修复要保持函数原有的边界语义。完整内容见生成测试之外的手写用例弹窗。
注释也要写成公共契约
把 @example 接进测试以后,注释就不再只是 README 的素材了。它至少有三层身份:
- 给人看的 API 文档。
- 给 TypeDoc 生成站点的结构化输入。
- 给
generate-example-tests提取运行时示例的测试来源。
这也意味着注释不能只写「函数做什么」。迁移后我又补了一轮 TSDoc,把已经由测试固定下来的边界写进公开文档。
第一类是导出的类型。PositiveInteger、ValidationMode、CamelCaseObject 这些类型会出现在 TypeDoc 里,读者会把它们当成公开 API 阅读。比如 PositiveInteger 需要明确说明它只能拦住数字字面量:
/**
* 正整数字面量类型。
*
* 常见数字字面量中的 `0`、负数和带小数点的值会被收窄为 `never`;普通 `number` 仍然会保留为 `number`,
* 因为 TypeScript 无法在静态阶段证明运行时数字一定是正整数。
*/
export type PositiveInteger<N extends number> = number extends N
? N
: `${N}` extends '0' | `-${string}` | `${string}.${string}`
? never
: N;
这样读者不会误以为有了类型就能删掉运行时边界。everyNth 自己也要写清楚:类型只能拦住数字字面量,动态非法值会返回空数组;这属于公开行为,不是测试里的偶然细节。
第二类是模式参数。ValidationMode 如果只在每个函数里零散解释,读者很难知道这是不是统一设计。现在它在类型定义上先给总口径:loose 是默认模式,偏向业务表单里的实用形态判断;strict 才在形态之外增加更强约束,例如 URL parser、银行卡 Luhn、身份证校验码和 Base64 payload。
第三类是对象转换和浏览器 API 的运行时边界:
camelCaseObject这类 key 转换函数只递归普通对象和数组,Date、RegExp、Map、Set、函数等内建对象保持原引用。replaceValueFromObject会克隆普通对象 / 数组、保留循环引用关系,不修改输入对象。copyHTML依赖navigator.clipboard.write和ClipboardItem,不支持时会 reject,而且不能像纯文本复制那样用 textarea 兜底。
凡是会影响调用方接入、失败处理、类型使用、输入对象是否被修改或运行环境兼容性的行为,都应该进入 TSDoc。单测负责证明这些行为没有退化,注释负责让读者在写代码前就知道这些行为存在。
这类注释会进入声明文件,也会让 npm tarball 稍微变大。这里我选择接受这点体积增长,因为 sheng-tool 本来就是给人直接 import 的工具库;调用方在编辑器里 hover 到 API 时能看到边界,比少几 KB 更重要。
TypeDoc 继续生成文档,GitHub Pages 负责分发;生成的 docs 与测试文件不作为源码或 npm 包内容提交。完整内容见文档部署与路径配置弹窗。
TypeScript 没有追最新
这次把 TypeScript 锁到 ~6.0.3。当时安装的 TypeDoc 版本声明支持 5.x || 6.0.x,没有覆盖 TS 7;这是这轮迁移的版本组合,不是长期升级上限。
版本选择要受整条工具链的兼容范围约束。这里按 TypeDoc 等依赖的支持范围选择能共同工作的最高版本,再用 pnpm peers check 确认没有 peer dependency 问题,将这组版本固定下来。
pnpm-workspace.yaml 里还记录了 pnpm 对构建脚本的允许项:
allowBuilds:
esbuild: true
这是因为开发脚本里的 tsx 会用到 esbuild,pnpm 新版会对 install scripts 更谨慎。为了避免每台机器安装时弹交互,最好在仓库里明确记录。
总结
原有「注释即测试」的设计得以保留,生成器改用 TypeScript compiler API,无法解析的示例会报告并失败;手写测试补充类型、浏览器环境、循环引用和边界语义。公开注释说明默认模式、非法输入、输入对象是否被修改及运行环境要求,TypeDoc 将这些契约生成文档,再由 GitHub Pages 分发。示例测试与类型测试分别承担自己的验证职责,读者看到的用法和边界也有了对应的检查依据。
上一篇:依赖、API 与发布边界的迁移。
生成测试之外的手写用例
手写测试补生成器管不到的地方
生成测试现在能覆盖大多数短示例,但运行时环境、类型推导和复杂对象引用关系仍然更适合手写测试。改造时我又补了几组用例:
replaceValueFromObject:确保替换不会把不匹配的 primitive 误删,也能按 predicate 转换嵌套值。replaceEmptyValueFromObject:确认只有存在默认值的 key 才会替换空值。camelCaseObject:确认循环引用不会爆栈,并且转换后的引用关系仍然闭合。camelCaseObject/pascalCaseObject/snakeCaseObject:用expectTypeOf和@ts-expect-error确认 key 转换类型是真的。everyNth:确认数字字面量里的0和小数会被类型拦住,动态传入的0、负数、小数、NaN、Infinity和非数字值都会返回空数组。format-validation:覆盖宽松 / 严格模式下 URL、Base64、MAC、身份证、银行卡等差异。generate-example-tests:确认简单断言、可执行expect代码块、显式跳过和无法解析的 report 都能工作。toFiniteNumber:确认千分位字符串、空字符串、Infinity和 fallback 行为。date/string/extra:补getWeeksInMonth的日历行数分支、SQL 模板转义分支、URL pattern 分支和中文数字递归补零。- 浏览器函数:用
happy-dom跑getQueryString、getFullUrl、动态 script 注入、滚动锁定、复制、等待、轮询和 viewport 判断。 - 浏览器类型判断:通过替换 UA 覆盖微信、小程序、移动端、桌面端、QQ 浏览器、爬虫、iOS 和 Android。
这次迁移里,测试确实暴露了旧实现的小问题。比如 replaceValueFromObject 原本递归到 primitive 时,如果没有命中替换条件,可能返回 undefined。这个在示例测试和手写测试一起跑时很容易看出来。
修完后还顺手加上了循环引用保护。核心结构是:先判断当前值是否需要替换,再用 WeakMap 记录已经克隆过的对象 / 数组,遇到回环时复用克隆对象。
export const replaceValueFromObject = (obj: any, from: any, to: any, autoExecuteFunction = true): any => {
const shouldReplace = (value: any) => (autoExecuteFunction && isFunction(from) ? from(value) : isEqual(value, from));
const getReplacement = (value: any) => (autoExecuteFunction && isFunction(to) ? to(value) : to);
const visit = (value: any, seen: WeakMap<object, any>): any => {
if (shouldReplace(value)) {
return getReplacement(value);
}
if (Array.isArray(value)) {
if (seen.has(value)) {
return seen.get(value);
}
const result: any[] = [];
seen.set(value, result);
for (const item of value) {
result.push(visit(item, seen));
}
return result;
}
if (!isPlainObject(value)) {
return value;
}
if (seen.has(value)) {
return seen.get(value);
}
const result: Record<string, unknown> = {};
seen.set(value, result);
for (const [key, nestedValue] of Object.entries(value)) {
result[key] = visit(nestedValue, seen);
}
return result;
};
return visit(obj, new WeakMap());
};文档部署与路径配置
文档改到 GitHub Pages
TypeDoc 继续生成 HTML 文档,GitHub Pages 负责分发,docs/ 不再随 npm 包发布。
配置也收敛成普通 typedoc.json:
{
"$schema": "https://typedoc.org/schema.json",
"entryPoints": ["src/index.ts"],
"out": "docs",
"readme": "readme.md",
"excludeInternal": true,
"excludePrivate": true,
"navigationLinks": {
"GitHub": "https://github.com/dev-itsheng/sheng-tool"
}
}
CI 里分两条线:
CI:安装依赖、类型检查、测试、构建、package smoke、publint、npm pack --dry-run。Docs:安装依赖、pnpm run docs:build、上传 Pages artifact、部署 GitHub Pages。
本地 .gitignore 加了 docs/ 和 tests/generated/。这两个目录都应该可再生成,不应该让人 review HTML、搜索索引和生成测试文件。
迁移中 TypeDoc 还帮忙抓了一个小拼写:src/string.ts 里有一处写成了 @params str,新版会提示 unknown block tag。这个错误不影响运行时,但会污染文档结构;既然文档也进 CI,就顺手修掉。