JSDocはTypeScriptだ

 (culi.bearblog.dev)
1 ポイント 投稿者 GN⁺ 2025-12-16 | 1件のコメント | WhatsAppで共有
  • 2023年、SvelteリポジトリのリファクタリングPRがJSDocベースのコードへ移行し、TypeScript懐疑派の注目を集めた
  • Svelte側はこれを反TypeScriptの立場ではなく、TypeScriptへの継続的な依存の一環だと説明
  • この記事はJSDocとTypeScriptを対立構造で捉えず、JSDoc自体がTypeScriptの一部であることを強調
  • TypeScriptはIntelliSenseエンジンとして、JSDocコメントの解釈とコード補完機能の両方を担う
  • JSDocはビルド段階なしで同等の静的解析能力を提供し、現代のJSプロジェクトで実質的にTypeScriptと同じ役割を果たす

Svelte PRと論争の背景

  • 2023年5月、Svelteリポジトリの内部リファクタリングPRがHacker Newsのトップページに掲載された
    • このPRは.tsファイルの型宣言を.jsファイルのJSDocコメントへ移す変更だった
    • 一部ではこれをTypeScriptの利点を拒否する行為だと解釈した
  • Svelteの創設者Rich HarrisはHNで直接「これは反TypeScriptではない」と説明
    • SvelteのTypeScriptへのコミットメントは依然として強いとも述べた
  • この出来事以降、「TypeScript vs JSDoc」を比較する記事が多数登場し、JSDocを「ビルド段階のないTypeScript」と評価する流れが広がった

TypeScriptの起源と本質

  • 2000年代後半〜2010年代初頭、JavaScriptは自動補完・型安全性が不足した言語と見なされていた
    • Microsoftの開発者たちはScriptSharpを使い、C#コードをJSに変換する方式で対応していた
  • このような背景からTypeScriptが誕生し、本質的にはJS開発を改善するためのビルドツールとして出発した

TypeScriptはIntelliSense

  • TypeScriptは単なる言語ではなく、IntelliSenseエンジンとして機能する
    • .tsファイルを使わなくても、コード補完・引数情報・シンボル探索などの機能はTypeScript言語サービスが提供する
    • ほとんどのエディタでは、JSコードを書いているときでもTypeScriptサービスがバックエンドとして動作している

TypeScriptはJSDoc

  • TypeScript言語サービスはJSDocコメントの解釈にも使われている
    • TypeScriptのCHANGELOGにはJSDoc関連機能の追加履歴が頻繁に含まれる
    • JSDocベースのプロジェクトもtsconfig.jsonで設定でき、tscコマンドで型チェックを実行可能
  • したがってJSDocを使う開発者も、すでにTypeScriptを使っていることになる

JSDocベースのプロジェクト経験

  • 筆者は既存プロジェクトのフロントエンドをJSDoc型コメントベースで書き直した経験を共有している
    • **列挙型(enum)**のようなランタイム機能を除けば、ほとんどのTypeScript表現はJSDocで可能
    • ジェネリクスは文法がやや複雑だが、型推論をより積極的に活用するようになる
  • JSDocプロジェクトでは関数をクリックしたときに実際のコードへ移動でき、開発体験が向上した
  • TypeScriptツールのエコシステムはJSDocプロジェクトでも再利用可能
    • 例: OpenAPIやGraphQLスキーマから型を生成するライブラリは、JSDocコメント形式で型を生成できる

結論と追加事例

  • JSDocはTypeScriptの代替ではなく、同じ静的解析体系を共有している
    • ビルド段階を省略しながらも、同等の型安全性を提供する
  • さらに、webpackプロジェクトもJSDocへ移行した事例が言及されている
  • TypeScriptの専門家として、筆者は「JSDocはTypeScriptだ」という立場を明確に示している

関連記事

1件のコメント

 
GN⁺ 2025-12-16
Hacker Newsの意見

  • 長年 Python/JavaScript でWebやロボティクスのソフトウェアを開発・保守してきて学んだことをまとめたもの 型は明示しなくても存在しており、明示しなければ結局は頭の中にだけ存在することになる しかし人間の記憶は揮発性が高く、他人からアクセスしにくい だから 型付けは優れたドキュメント手段 である JSDocとTypeScriptは型を表現する標準的な形式で、どちらにも長所と短所がある 重要なのは、一貫性と予測可能性を持って型を定義することだ 型チェッカーは「では証明してみて」と言うコンピュータなりのやり方だ すべてのプログラムが同じレベルの証明を必要とするわけではなく、過剰な証明は無駄になりうる だから私は、必要な分だけ「証明できる」言語を好む

    • 「頭の中にしかない情報は揮発性が高い」という言葉には完全に同意する 特に 『他人』には未来の自分自身も含まれる ということを、仕事をしながら痛感した
    • Rustは「prove it」哲学の代表として知られているが、実際にはそうでもないと思う Rustは unsafe, Arc, clone のような方法で制約を緩められるが、その代わり、どの制約が証明されていないのかを明確に選ばせる 一方で、「証明しなくてよい」言語は内部でどんなアプローチを取ったのか分かりにくい Rustのやり方は最初はPythonのように緩く書けるが、その後の 可読性と拡張性 でははるかに有利だ
    • JSDocとTypeScriptが同じ目的を持つという点には同意する 特定のツールを擁護したかったわけではなく、単に両方とも 型システムの表現方式 だという点を強調したかった
    • 25年前の大学時代にすでにこの教訓を学んだ 静的型付け言語 のほうがチームプロジェクトでははるかに扱いやすく、今でも可能なら静的型を好んでいる
    • 「型は常に存在する」という言葉には同意するが、C#のように型を明示しなければならない言語はRubyよりはるかに多くの作業を要する 既存のJSライブラリに後から追加されたTypeScriptの型定義を見ると、複雑さはものすごい たった1つの誤った型でもコンパイル全体が壊れることがある 結局 動的言語は『自己責任』の方式 で使うべきだ

  • 私は ビルドステップなし でJavaScriptで作れるものは何でも好きだ 現代的なHTML/CSSとWeb Components、そしてJSDocの組み合わせは過小評価されている 誰にでも合うわけではないが、十分に現代的なフロントエンドスタックの候補だと思う

    • 今では Node 24 からはTypeScriptもビルドステップなしで実行できる
    • ビルドステップのないアプローチの魅力は理解できるが、実際には依存関係の管理が複雑になる HMRのような機能のおかげで、ビルドステップのコストもかなり下がっている
    • この10年間、実際に配布されたJSコードをそのまま書いたことがない いつも ViteやWebpack を通すので、ビルドなしJSの利点は実感できない
    • Web Componentsは作るのがかなりつらい 複雑なコンポーネントを簡単に作る方法があればいいのにと思う
    • HTML+CSS+JSDocの組み合わせの利点は ブラウザ開発者ツールとの自然な統合 にある ネットワークリクエストの追跡、ソースコードへの直接ジャンプ、ブレークポイント設定など、デバッグがはるかに直感的だ 規模が大きくなるほど、こうした環境は大きな助けになる

  • SPAが流行していた時代、JSDocは型管理の救世主 だった その後Google Closure Compilerが登場してJSDocベースの型安全性を提供し、TypeScriptは独自構文とともに(TS)JSDocをサポートした コミュニティは最終的にTypeScriptを選び、Closure Compilerは消えていった そのため(TS)JSDocは MSがGoogleと競っていた時代の遺物 として残った 今ではTSはジェネリクス、Enum、ユーティリティ型、Vitestの型テスト、型ガードなど、はるかに多くの機能を提供している 私はTSとJSDocを併用している — TSはコード用、JSDocはドキュメント用（@link, @see, @deprecated, @example など）

    • 実際には 現代のJSDocはTypeScript言語サービス を使っている ジェネリクス、ユーティリティ型、型ガード、正規表現パースなど、TSの機能の大半はJSDocでも利用できる 個人プロジェクトでジェネリクスを含めてすべてJSDocで実装してみたことがある
    • 上の主張は事実ではない (TS)JSDocが過去の遺物だというのは 誤情報 なので、確認せずに広めるべきではない
    • この記事そのものが、まさにその主張に対する 直接的な反論 だ

  • JSDocでは表現できない型が多いと言われるが、Flow のように言語全体としてのアプローチが可能だったらよかったのではと思う TypeScriptでもそうできたはずなのに、なぜしなかったのか分からない

    • 具体例があるなら聞いてみたい 私も以前はそう思っていたが、プロジェクトをJSDocにリファクタリングして考えが変わった JSDocでも @template で ジェネリックスロット を定義できる 例: 
      /** @type {ReturnType<typeof useState<Book[]>>} */
const [books, setBooks] = useState();
    • 今ではほとんどすべての 型システム機能がJSDoc構文にも追加 されている
    • TypeScriptの型システムは チューリング完全（Turing complete） なので、事実上無限の表現力を持つ 関連リンク

  • JSDocで書かれたパッケージは CMD/CTRLクリックで実際のコードへ移動 できるので、開発体験が良い

    • これはエディタ設定でもカスタマイズ可能だ
    • 実際にはTypeScriptでも同じように動作する

  • 5年前のミートアップで、ある発表者が「TypeScriptが嫌ならJSDocが代替になる」と言っていた 私はそれは結局 どちらもTypeScript だと説明したが、上司は信じなかった

    • 違いは構文の 圧縮度（syntax compression） 程度だと思う
    • 「JSDocも結局TypeScriptだ」という言い方は半分だけ正しい JSDocとTSはどちらも型を明示的に表現するが、TS構文のほうがはるかに強力 だ それでも、JS環境を維持しながら型ツールの恩恵を得たい人にとってはJSDocは良い選択肢だ

  • 反論として、JSDocはTypeScriptではない @typedef で定義した型は自動的にexportされ、それを制御する方法がない 関連イシュー このためライブラリ開発時に IntelliSenseが雑然と露出 して不便だった

    • Web ComponentsにはJSDocがかなりよく合う “my-component.js” ファイルをそのままコピーしてもビルドなしで動く ただし大規模プロジェクトではTS構文を好む
    • 技術的には正しい指摘だが、@importを調整 すれば大半は解決できる

  • 「JSDocはTypeScriptの代替ではない」という主張には同意する JSDocも 静的解析を提供するがビルドステップがない Node公式ドキュメント 参照

    • 内部的には依然としてビルドステップは存在する しかしJSDocベースのTSはブラウザでも動作する 個人的には TS構文の可読性 を好んでおり、swc のようなツールでの型削除速度も十分速い
    • ただしこの機能は Node環境に限定 されており、ブラウザでは動かない

  • TypeScriptが他の選択肢を押しのけて勝利した理由は、新しい言語ではなく型チェッカーであり続けたから だ 初期には方向性がややぶれたが、適切に修正され、今ではほとんどのコードでenumすらあまり使われていない

  • VSCodeでは「TypeScript: Prefer Go To Source Definition」設定を有効にすると、実際のソースへ移動できる また tsconfig に declarationMap: true を追加すると、より正確に動作する 私はほとんど常に cmd+clickでソースを見る ほうを好む