TypeScript 的 JS 检查能力 + JSDoc 可实现 JavaScript 异步代码类型安全与自文档化：启用 allowJs 和 checkJs，用 @returns {Promise} 等标注异步签名，结合 .d.ts 定义运行时结构，并通过 TypeDoc/Fumadocs 自动生成同步更新的活文档。

不用改后缀、不换构建流程，就能让 JavaScript 异步代码既类型安全又自带文档——关键在于用好 TypeScript 的 JS 检查能力 + JSDoc 类型标注，尤其针对 Promise、await、回调链等场景。

开启 TS 对 JS 的异步类型检查

TS 编译器原生支持分析 .js 文件中的异步逻辑，但需明确启用：

Json Repair Kit

使用 Node.js 评估修复格式错误的 JSON，自动纠正尾随逗号、单引号、未加引号的键等常见问题，实现文件规范化。

下载

• tsconfig.json 中必须设置："allowJs": true（允许读取 JS）、"checkJs": true（执行类型检查）
• 推荐加 "strict": true 或至少 "noImplicitAny": true 和 "strictNullChecks": true，避免 Promise@#@#@#@#@#@#@#@#@#@0 扫描带 JSDoc 的 JS 文件，输出 HTML/Markdown 文档站点，@param 和 @returns 自动转成参数表
• CI 中加入 npx typedoc --out docs，每次 PR 合并都刷新文档，确保线上文档与最新代码一致
• 搭配 Fumadocs 的 组件，可在 MDX 文档中内联渲染接口字段说明，支持 @default、@remarks 等 JSDoc 标签