JSDoc 是 TypeScript
Source: Hacker News
概述
2023 年 5 月，来自 Svelte 仓库的一个内部重构 PR登上了 Hacker News 的首页。这个（表面上）有争议的 PR 似乎为 TypeScript 持怀疑态度/反对者（当时包括 React 团队的 Dan Abramov）提供了“胜利”。作为表面上拒绝静态类型的 Web 框架宠儿，这件事被视为大事。Rich Harris 在 HN 上（链接）回应，解释从 .ts 文件改为在 .js 文件中使用 JSDoc 注释并不是对反 TypeScript 立场的 vindication（辩护）。
Harris 认为 Svelte 对 TypeScript 的“承诺[…]比以往更强”。这引发了一波“TypeScript vs JSDoc”的帖子，辩称 JSDoc 能够提供“所有 TypeScript 的好处而无需构建步骤”（尽管语法有时更笨拙）。
我不想用这种对立的框架，而是提出一种更微妙的替代说法：JSDoc 就是 TypeScript。
一些背景
TypeScript 是 C# 吗？
（不，但它解释了 TS 早期发展的很多原因）
在 2000 年代后期 / 2010 年代初，JavaScript 常被视为不够严肃。工具缺乏自动补全、重命名符号、类型安全等功能。微软的开发者会编写 C# 代码，然后使用名为 ScriptSharp 的工具生成稍微更安全的 JavaScript。这就是 TypeScript 的起源。1 本质上，它最初是一个构建工具，用来让编写 JS 更不易出错。
TypeScript 是 IntelliSense！
即使你不写 .ts 文件，你很可能已经在使用 TypeScript，因为它为 IntelliSense 引擎提供动力。如果你的编辑器在编写 JavaScript 时提供代码补全、参数信息、快速信息或成员列表，那么它几乎可以肯定地在运行 TypeScript 语言服务。
TypeScript 是 JSDoc :)
同一个 TypeScript 语言服务会解释 JSDoc 注释。这就是为什么 TypeScript CHANGELOG 常常包含关于 JSDoc 功能的说明。2 这也解释了为什么 JSDoc 相关的 IntelliSense 可以受 tsconfig.json 文件的控制，以及为什么你可以对使用 JSDoc 注释的项目运行 tsc。简而言之，你已经在使用 TypeScript 了。
我的亲身经历
我最近重写了一个旧项目的前端，全部使用 JSDoc 注释来进行类型标注。以下是一些收获：
- 除了运行时特性（如 enums）之外，你几乎可以通过 JSDoc 表达 TypeScript 的所有功能。某些特性（例如泛型）写起来更笨拙，需要你为返回值标注类型以推断泛型槽位。有时额外的冗长会促使开发者倾向于类型推断，从而养成更好的实践。
- 对于使用 JSDoc 标注的包，
Ctrl/Cmd‑点击函数会直接跳转到实际实现，而不是跳到单独的声明文件——这是我更喜欢的工作流。 - TypeScript 工具对 JSDoc 项目出奇地好用。这包括那些消费模式（如 OpenAPI 或 GraphQL）并生成 JSDoc 注释而非 TypeScript 代码的类型生成库。
作为一名自认的 TypeScript 发烧友，我可以说：JSDoc 不是反 TypeScript 的立场；它提供了同样强大的静态分析，却不需要额外的构建步骤。
- 枚举之所以被加入语言，遗憾地是因为当时的需求1。
- 一个令人沮丧的旁注：成为 TypeScript 专家意味着要接受文档的一半都藏在 changelog 里。例如，查看关于唯一 Symbol 的条目。2