JSDocと`@import`で切り開く、TypeScriptに頼らない「純粋JS」の型駆動アーキテクチャ
こんにちは。ブラウザのC++エンジン（V8やSpiderMonkey）がパースするバイトコードの匂いを嗅ぎつけるだけでご飯が3杯いけるような、フロントエンドのギークなアーキテクチャ偏愛者です。
現代のWebフロントエンド開発において、「型安全」を手に入れるための唯一の切符はTypeScriptだと思い込んでいませんか？ 確かに、あの静的型付けの快適さは罪作りなほど魅力的です。しかし、ビルドステップの複雑化、ソースマップの剥離問題、そして何より「ただのJavaScriptを動かしたいだけなのに、なぜ大げさなトランスパイルが必要なんだ？」という根源的なモヤモヤを抱えているシニアエンジニアも少なくないはずです。
私たちは忘れてはならない。JavaScriptのruntime（ランタイム）は、JSDocという強力な原生林の武器を最初から持っているということを。
今回は、そのJSDocのポテンシャルを極限まで引き出し、VS CodeなどのLSP（Language Server Protocol）を完全にハックして、TypeScriptのコンパイラを使わずに極上の型安全を実現する`@import`による外部型定義のインポートについて、アーキテクチャの深層から解説していこう。
—
なぜ今、純粋なJavaScript＋JSDocなのか？
「ビルドレス」や「エッジランタイムでの直接実行」が再評価されている昨今、トランスパイルのオーバーヘッドは、時としてパフォーマンスのボトルネックになり得ます。特に大規模なマイクロフロントエンドや、ミリ秒単位のロード最適化が求められる環境では、開発体験（DX）のために余計なビルドパイプラインを挟むこと自体がリスクになる。
しかし、型がないコードは、数ヶ月後の自分やチームメンバーにとって「時限爆弾」でしかない。
ここで登場するのが、JSDocを用いた型注釈です。V8などのJSエンジンは、コメントとして書かれたJSDocを完全に無視（スキップ）するため、ランタイムのメモリ効率やパース負荷、レンダリング前の初期化速度には1バイトの影響も与えません。 一方で、VS CodeのTSサーバーはこれを厳密に解析し、IDE上ではTypeScriptと同等の静的解析、補完、リファクタリングの恩恵を受けられます。
つまり、「プロダクションコードは純度100%の軽量なJavaScriptでありながら、開発時は最高峰の型安全を手に入れる」 という、エンジニアの欲しかったすべてがここに揃うわけです。
—
`@import` 構文の基本と、JSDocの限界突破
TypeScriptの `import type` に相当する機能が、実は標準のJSDoc（TypeScript 5.5以降のLSP等で完全にサポートされている記法）にも導入されています。これが `@import` です。
従来のJSDocでは、別ファイルの型を参照するためには `@typedef` と `@param {import(‘./path’).TypeName}` を組み合わせるという、冗長で視認性の悪い書き方を強いられていました。これを劇的にスマートにするのが、ファイルスコープでのインポートです。
実際のコードを見てみましょう。まずは型定義の置き場所となるモジュールから。
// types.js
/
- ユーザーのドメインモデルを表すオブジェクト
- @typedef {Object} User
- @property {string} id – 一意のユーザーID（UUIDv4）
- @property {string} name – ユーザーのフルネーム
- @property {‘admin’ | ‘editor’ | ‘viewer’} role – 権限ロール
- @property {number} lastLoginAt – 最終ログインのUNIXタイムスタンプ
/
/
- APIレスポンスの共通エンベロープ
- @template T
- @typedef {Object} ApiResponse
- @property {boolean} success – 処理が成功したかどうか
- @property {T} data – ペイロードデータ
- @property {string | null} [errorCode] – エラー時のコード
/
この純粋なJSファイル（実行時には何も仕事をしない、ただの型カタログ）を、実際のビジネスロジックを扱うファイルから `@import` で取り込みます。
// userService.js
/ @import { User, ApiResponse } from ‘./types.js’ /
/
- 指定されたIDのユーザーをリモートから非同期で取得する
- ネットワーク層の競合やレートリミットを考慮した堅牢なフェッチ処理
- @param {string} userId – 取得対象のユーザーID
- @returns {Promise
/
export async function fetchUserById(userId) {
// 非同期処理における競合（Race Condition）を防ぐためのAbortControllerの準備など
const response = await fetch(`/api/users/${userId}`);
if (!response.ok) {
throw new Error(`Failed to fetch user: ${response.statusText}`);
}
/ @type {ApiResponse
const json = await response.json();
return json;
}
このコードの美しさに気付いてほしい。`userService.js` の中には、TypeScript特有の型定義構文（`interface` や `type` キーワード、ジェネリクスの山括弧など）が一切ありません。しかし、VS Codeでこの関数にマウスオーバーすれば、`ApiResponse
—
アーキテクチャ的考察：なぜこれが「実務レベル」で強力なのか？
シニアエンジニアやアーキテクトが直面する現場の課題に照らし合わせ、この手法がなぜ優れているのかをもう少し深く解剖してみましょう。
1. 循環参照とメモリ／LSPのパフォーマンス最適化
巨大なアプリケーションを構築する際、型定義の循環参照（Circular Dependency）はTypeScriptコンパイラをスローダウンさせる大きな原因の一つです。コンパイラが型解決のためにグラフを何周も巡回し、メモリを大量消費する。
JSDocの `@import` は、LSPのインデックス貼りの段階で効率的に遅延解決されるため、プロジェクト全体のメモリ効率（IDEのバックグラウンドプロセスにおけるヒープ消費量）が圧倒的に軽量に保たれます。ブラウザの実行メモリには1バイトも影響を与えないため、クライアントサイドのレンダリング負荷やJavaScriptのパース／コンパイル時間（TBT: Total Blocking Time）への悪影響は完全にゼロです。
2. 「型落ち」バグの防止とサードパーティライブラリの型汚染回避
TypeScriptを使っていると、ライブラリのバージョンアップに伴う型定義（`@types/`）の不整合地獄にハマることがあります。
JSDocベースであれば、必要に応じてJSDocコメント内で直接サードパーティの型をインポートし、プロジェクト側で独自にラップ（Type Augmentation）することが極めて容易です。
/ @import { Request, Response } from ‘express’ /
/
- カスタムミドルウェアの型安全な実装
- @param {Request} req
- @param {Response} res
- @param {import(‘express’).NextFunction} next
/
export function rateLimiterMiddleware(req, res, next) {
// 独自のレートリミットロジック
next();
}
コンパイルエラーに怯えることなく、動的に振る舞うJavaScriptの柔軟性を保ったまま、ピンポイントで厳格な型制約をかけられる。このコントロール感は、泥臭いレガシーコードのモダナイゼーションにおいて最強の武器になります。
—
実務でハマる罠と、その回避策（チーフアーキテクトからの助言）
もちろん、甘い言葉ばかりではありません。この手法をプロダクションに投入する際、いくつかの「現場の罠」が存在します。先回りして回避策を授けておきましょう。
- 罠1: 相対パスの変更に弱い
- 現実: ディレクトリ構造をリファクタリングしてファイルを移動した際、JSDoc内の相対パス（`@import { … } from ‘./types.js’`）が壊れやすい。TypeScriptのようにパスエイリアス（`@/types` など）をJSDoc内で綺麗に解決させるには、`jsconfig.json` や `tsconfig.json`（`allowJs: true` かつ `checkJs: true` の設定）の `compilerOptions.paths` を正しく設定し、LSPにパスを教え込む必要があります。
- 罠2: チームメンバーの学習コスト
- 現実: 「JSDocなんて古い、なぜTSを使わないんだ」というモダンかぶれ（失礼）のジュニアエンジニアから反発が出るかもしれない。
- 対策: 「ランタイムコストゼロで、トランスパイルエラーに縛られない高速な開発サイクル」という実利を数字で見せつけてやりましょう。ビルドツールチェーンの複雑性を排除できる点は、DevOpsの観点からも強力な説得材料になります。
—
まとめ
JavaScriptのデータ型と型判定、そしてJSDocによる `@import` の活用は、単なる「TypeScriptの妥協案」ではありません。それは、言語のランタイム本来の軽快さと、開発時の静的解析の強靭さを極限のバランスで融合させた、洗練されたアーキテクチャスタイル です。
フレームワークやツールチェインの流行り廃りに振り回されることなく、JavaScriptというプラットフォームのプリミティブな仕様の深淵を愛し、コントロールする。それこそが、真に堅牢なWebアプリケーションを生み出すシニアエンジニアの矜持ではないでしょうか。
さあ、今日のデプロイから、あなたのエディタのJSDocを少しだけブラッシュアップしてみませんか？ 鮮やかな補完と、軽やかな実行速度が、あなたを待っています。
コメント