こんにちは！フロントエンドの現場を渡り歩いているチーフアーキテクトの私です。
JavaScriptを書いていると、「あー、この変数には文字列も入るし、数字も入るようにしたいな……」なんて場面、めちゃくちゃよく遭遇しますよね。特にWeb制作の現場や、ちょっとした入力フォームのデータを扱うときなんかは、「自由度が高すぎて、逆に型が迷子になる！」という悩みを抱えがちです。
そんなとき、TypeScriptを導入するほどじゃないけれど、エディタ（VS Codeなど）の補完機能や自分自身のメモ書きとして、型をビシッと綺麗に定義したい！
そこで登場するのが、今回のお題「JSDocにおけるユニオン型（複数の型を許容する定義）」です。
難しい言葉や堅苦しいルールは、この際いったん脇に置きましょう。身近なたとえ話を交えながら、優しく紐解いていきますね。大丈夫、一緒に見ていけばすぐに使いこなせるようになりますよ！
—
そもそも「ユニオン型」ってなに？ お買い物の「お支払い方法」で考えてみよう
いきなりプログラムの話をする前に、ちょっと身の回りの便利なものを想像してみてください。
例えば、街のカフェやコンビニのレジ横にある「お支払い方法」の看板。
そこには、「現金 または クレジットカード または 電子マネー」と書かれていますよね。店員さん側からすると、「このお客さんはどれを使うか分からないけれど、この3つのうちどれか一つで支払いに来るはずだ」とあらかじめ心構えができます。
JavaScriptのユニオン型（Union Type）も、これとまったく同じです。
パイプと呼ばれる縦棒記号（`|`）を使って、「この変数には、文字列も入るし、数値も入るよ。でも、許可されているのはその中身だけだからね！」と、変数にお墨付き（ルールの看板）を立ててあげる仕組みのことです。
JSDocを使えば、JavaScriptの自由な良さを残したまま、エディタに「この変数はこの中のどれかだよ」と優しく教えてあげることができるんです。
—
JSDocでユニオン型を書いてみよう（基本のき）
それでは、実際の書き方を見てみましょう。
JSDocというのは、JavaScriptのコードの上に書く「コメント（説明書）」のことです。エディタはこのコメントを読み取って、「おっ、ここはこういうデータなんだな」と理解してくれます。
例えば、「ユーザーのID」を管理する場面を想像してください。IDは数字のこともあれば、文字と数字が混ざった文字列のこともありますよね。そんなときは、こんな風に書きます。
/
- ユーザーの識別IDを保持する変数
- @type {string | number} – 文字列または数値を許容するユニオン型
/
let userId;
// これらはすべてルール違反になりません（OK！）
userId = “A-1024”; // 文字列のID
userId = 42; // 数値のID
// もしここに「真偽値（true/false）」を入れようとすると、
// エディタが「おいおい、それはルール違反だぜ」とそっと教えてくれます。
この `@type {string | number}` の部分が、まさにユニオン型です。`|`（パイプ）で区切るだけで、「これまたはこれ！」という複数の選択肢を作ることができます。おサルさんでも分かるくらいシンプルでしょう？
—
【実践編】Web制作でよくある「表示モード」を制御してみる
もう少し実務に近い話をしましょう。
Webサイトを作るときに、「ダークモード」や「ライトモード」、あるいは「システム設定に従う（auto）」という状態を切り替える機能を実装するとします。
この「テーマ（表示モード）」を管理する変数には、決まった3つの文字（文字列）しか入れたくありません。そんなときも、ユニオン型が大活躍します。
/
- 現在のWebサイトのテーマ設定を表す変数
- @type {‘light’ | ‘dark’ | ‘auto’} – 3つの文字列のいずれかしか受け付けない
/
let currentTheme = ‘light’; // 初期値はライトモード
/
- テーマを変更する関数
- @param {‘light’ | ‘dark’ | ‘auto’} newTheme – 新しく適用するテーマ
/
function setTheme(newTheme) {
currentTheme = newTheme;
console.log(`テーマが「${currentTheme}」に変更されました！`);
}
// 正常な使い方
setTheme(‘dark’); // 「テーマが「dark」に変更されました！」と表示される
// うっかりタイポ（入力ミス）をしてしまった場合
// 例: setTheme(‘darK’); などと書いても、エディタが警告を出して気づかせてくれます！
このように、特定の文字列だけを許容するユニオン型（文字列リテラル型と言ったりもします）を定義しておくと、「うっかりキーボードの打ち間違えをしてバグを生んでしまった……」という現場の悲劇を未然に防ぐことができます。これは本当に助かりますよね。
—
つまずきやすいポイントと、優しいたとえ話
初心者の頃、私が一番混乱したのが「ユニオン型と、実際の値（JavaScriptの処理）をごっちゃにしてしまうこと」です。
ここで一つ、大切な注意点をお話しします。
JSDocで `@type {string | number}` と書いたからといって、JavaScriptが勝手にデータを変換してくれるわけではありません。
あくまでこれは「エディタに対する事前申告」です。
レストランの「お好み定食」のたとえ
ユニオン型は、レストランの「メインのおかずは、ハンバーグか唐揚げのどちらかを選べます」というメニュー表のようなものです。
メニュー表にそう書いてあっても、厨房から料理が出てきたときに、勝手にハンバーグと唐揚げが合体して出てくるわけではないですよね。どちらか一方が「ドンッ」とテーブルにやってきます。
プログラムも同じです。ユニオン型で定義された変数の中身を使うときは、今どちらのデータが入っているのかを、コードの中でちゃんと確認してあげる必要があります。
/
- スコアを表示する関数
- @param {string | number} score – 文字列または数値のスコア
/
function displayScore(score) {
// 中身が「数値」なのか「文字列」なのかをtypeofで判定する
if (typeof score === ‘number’) {
// 数値だった場合の処理
console.log(`スコアは数値です: ${score.toFixed(1)}`);
} else {
// 文字列だった場合の処理
console.log(`スコアは文字列です: ${score.toUpperCase()}`);
}
}
displayScore(95.5); // “スコアは数値です: 95.5”
displayScore(“level-max”); // “スコアは文字列です: LEVEL-MAX”
「あれ？さっき定義したのに、なんでメソッド（`.toFixed()`とか）を使うときに怒られるんだろう？」と悩んだら、この「中身の確認（型ガード）」を忘れていないか、そっとチェックしてみてくださいね。
—
まとめ
今回は、JSDocにおけるユニオン型の基本と、現場で役立つ実践的な使い方をお届けしました。
- ユニオン型（`|`）を使えば、「AまたはBまたはC」という複数の型を一つの変数に優しく許容できる。
- Web制作の現場では、文字列を限定する（`’light’ | ‘dark’` など）ことで、うっかりミスを防ぐ強力な武器になる。
- あくまでエディタへの「説明書」なので、実際の処理では `typeof` などで中身を確認してあげることが大切。
JavaScriptはとても自由で楽しい言語ですが、規模が大きくなると「あれ、この変数になにが入るんだっけ？」と迷子になりがちです。そんなとき、JSDocのユニオン型をそっと添えてあげるだけで、未来の自分や一緒に働く仲間を救うことができます。
最初は難しく感じるかもしれませんが、まずは簡単な変数や関数の引数から、ぜひ気軽に試してみてくださいね。あなたの開発ライフが、少しでも快適でワクワクするものになりますように！
コメント