JSDoc is TypeScript

Japanese Translation:

この文章は、JavaScript で JSDoc ベースの型付けを「TypeScript」と同様に扱えると主張しています。理由として、TypeScript の言語サービスがこれらのコメントを解釈し、プレーンな

.js

ファイルでも VS Code の IntelliSense を動かすためです。この議論は、2023 年 5 月に Hacker News に投稿された Svelte のリファクタリングに遡ります。Rich Harris は、型宣言を JSDoc に移すことは「TypeScript に反対する」立場ではなく、単なる別のアプローチだと説明しています。その後、多くのブログ記事が続き、JSDoc がビルドステップなしで TypeScript の全メリットを提供すると主張しました。

著者は古いフロントエンドを JSDoc だけで書き直すことでこの手法を実証しています。ほとんどの TS 機能は表現可能ですが、ランタイム列挙型は除外され、ジェネリクスは冗長になるものの推論が向上することに注意しています。JSDoc 型付きパッケージでは、CTRL/CMD クリックで別の

.d.ts

ファイルではなくソースコードへジャンプできます。TypeScript ツール（例：OpenAPI/GraphQL タイプジェネレーター）は、

.ts

ファイルではなく JSDoc コメントとして型を出力するように設定可能です。また記事は Microsoft の初期 ScriptSharp 作業や TS における列挙型の歴史にも触れ、TypeScript の学習曲線が膨大な変更ログドキュメントから来ていることを指摘しています。将来的には、JSDoc だけで型付けする採用が広がれば、ツールチェーンはコメントベースの型を優先し、別途

.ts

ファイルの必要性が減り、JavaScript チームにとってツールコストが低下すると著者は予測しています。

2025年11月29日

2023年5月、Svelte のリポジトリからの内部リファクタリング pull‑request が Hacker News のフロントページに載りました。表面上は議論を呼んだ PR ですが、実際には TypeScript に懐疑的な人々やラッド・イット派（React チームの Dan Abramov など）を擁護するもので、トップクラスの Web フレームワークが静的型付けなしで繁栄できると示唆していたように見えました。リッチ・ハリスは HN に投稿し、「

.ts

ファイルから

.js

ファイル内の JSDoc コメントへ型宣言を移すことは、TypeScript への反対姿勢ではない」と説明しました。そして「Svelte の TypeScript への取り組みは以前よりも強化されている」と主張しました。

この出来事は「TypeScript vs JSDoc」というタイトルのブログ記事やフォーラムスレッドを呼び込み、JSDoc が「ビルドステップなしで TypeScript のすべてのメリットを提供する」（ただし構文がやや重い）と主張しました。私はその議論には興味がありません。むしろ、もっと大きく、より誤解されやすい点に焦点を当てたい ― JSDoc は実際には TypeScript です。

背景

TypeScript は C#？
そうではありませんが、その初期開発は C# の影響を強く受けています。2000 年代後半〜2010 年代前半、JavaScript はまだ真剣に扱われていない言語と見なされていました。ツールチェーンにはオートコンプリートやシンボルのリネーム、型安全性などが欠けており、Microsoft の開発者は C# を書き、ScriptSharp で「少しだけ型安全な」 JavaScript を生成していたのです。

このような背景から TypeScript（ビルドツール）が誕生しました。
- TypeScript は IntelliSense だ！
```
.ts
```
  ファイルを書いていなくても、ほとんどのエディタでコード補完やパラメータ情報、クイック情報、メンバーリストを利用できるのは、言語サービスが TypeScript に依存しているからです。
- TypeScript は JSDoc だ！ 同じ言語サービスが JSDoc コメントも解釈するため、TypeScript の変更ログには JSDoc 関連の項目が頻繁に登場します。また、
```
tsconfig.json
```
  が JSDoc ベースの IntelliSense を制御できる理由や、JSDoc だけを使うプロジェクトでも
```
tsc
```
  を実行できる理由もここにあります。

「あなたはすでに TypeScript を使用しています。」

私自身の経験

最近、古いプロジェクトのフロントエンドを完全に JSDoc コメントで書き直しました。得た教訓は次の通りです。

実行時機能（enum など）を除けば、TypeScript で表現できるものはほぼすべて JSDoc でも表現できます。
- ジェネリクスはやや不便です：戻り値を型付けしてジェネリックパラメータを推論させる必要がありますが、これにより開発者は自動推論へと誘導され、結果として良い実装習慣が促進されます。
JSDoc で型付けされたパッケージでは、関数を Ctrl/Cmd‑クリック すると
```
.d.ts
```
ファイルではなく実装に直接ジャンプできます ― 私はこの体験の方が好みです。
TypeScript のツールチェーンは JSDoc プロジェクトにも驚くほど再利用可能です。
- OpenAPI や GraphQL などスキーマから型を生成するライブラリは、TypeScript コードではなく JSDoc コメントを出力できるように設定できます。

「大の TypeScript 愛好家からのお墨付き」：JSDoc は TypeScript に対抗する立場ではなく、ビルドステップなしで同等の静的解析を提供します。

なぜ enum が言語に追加されたか（残念ながら）

付記として。TypeScript をマスターするには、その文書の半分がリリースノートにあることを知る必要があります。たとえば…

```
#jsdoc
```
```
#typescript
```

（これらのタグはリリースノートで頻繁に登場し、JSDoc と TypeScript がいかに密接に結びついているかを示しています。）

Japanese Translation:

背景

私自身の経験

なぜ enum が言語に追加されたか（残念ながら）

同じ日のほかのニュース