TypeScript 的 JS 检查能力 + JSDoc 可实现 JavaScript 异步代码类型安全与自文档化：启用 allowJs 和 checkJs，用 @returns {Promise} 等标注异步签名，结合 .d.ts 定义运行时结构，并通过 TypeDoc/Fumadocs 自动生成同步更新的活文档。
不用改后缀、不换构建流程，就能让 JavaScript 异步代码既类型安全又自带文档——关键在于用好 TypeScript 的 JS 检查能力 + JSDoc 类型标注，尤其针对 Promise、await、回调链等场景。
开启 TS 对 JS 的异步类型检查
TS 编译器原生支持分析 .js 文件中的异步逻辑，但需明确启用：
-
tsconfig.json 中必须设置：
"allowJs": true（允许读取 JS）、"checkJs": true（执行类型检查） - 推荐加
"strict": true或至少"noImplicitAny": true和"strictNullChecks": true，避免Promise<any></any>或undefined漏检 - 无需安装额外插件或修改 Webpack/Vite 配置，tsc 或 VS Code 内置 TS 服务即可生效
用 JSDoc 精确描述异步签名
异步函数的类型信息最容易丢失。JSDoc 要写清 @param、@returns，尤其注意返回值是 Promise 包裹的类型：
-
/** @param {string} id @returns {Promise<user>} */</user>—— VS Code 悬停时显示完整返回结构，await getUser(id)后能直接访问.name、.email -
/** @returns {Promise<array>>} */</array>—— 支持数组方法自动补全，.map(p => p.price)不报错 - 对回调式 API（如 Node.js
fs.readFile），用@param {function(null, Buffer): void} callback标注形参类型，防止误传箭头函数导致this错乱
为动态响应结构补全运行时类型
API 返回数据、数据库查询结果这类“运行时才确定结构”的对象，光靠 JSDoc 不够。需要结合 .d.ts 定义和显式导入：
- 在
types/api.d.ts中定义：export interface OrderResponse { id: string; items: Array; } - 在 JS 文件中写：
/** @type {import('./types/api').OrderResponse} */ const data = await fetchOrder(); - 这样
data.items[0].sku有提示，data.items[0].price直接报错，且 TypeDoc 或 Fumadocs 可据此生成字段文档
自动生成“活文档”并同步维护
类型即文档，只要结构稳定，文档就天然准确：
- 用 TypeDoc 扫描带 JSDoc 的 JS 文件，输出 HTML/Markdown 文档站点，
@param和@returns自动转成参数表 - CI 中加入
npx typedoc --out docs，每次 PR 合并都刷新文档，确保线上文档与最新代码一致 - 搭配 Fumadocs 的
<autotypetable></autotypetable>组件，可在 MDX 文档中内联渲染接口字段说明，支持@default、@remarks等 JSDoc 标签
