【入門編】 @typedefによるカスタム型定義 – JavaScript実践ガイド

こんにちは！フロントエンド・アーキテクチャの現場を長年うろついている者です。

JavaScriptを書き始めて少し慣れてくると、「あれ、このデータの中身って今どんな形だっけ？」「さっき作った関数、どんなプロパティを持つオブジェクトを渡せばいいんだっけ？」と迷子になる瞬間、ありませんか？私は数え切れないほどやってきました。特に大規模なアプリケーションになればなるほど、この「データの形が分からない問題」は開発者のメンタルをゴリゴリと削っていきます。

TypeScriptを導入するのが王道の一手ではありますが、「今のプロジェクトのビルド環境を変える余裕がない」「もっと手軽に、バニラなJavaScriptのままで型安全の恩恵を受けたい！」という現場の悲鳴もよく耳にします。

そんなあなたにそっと差し出したいのが、JSDocの`@typedef`という秘密兵器です。
今回は、この`@typedef`を使って、複雑なオブジェクトの構造をスッキリ整理し、あなたのエディタを「優秀な相棒」に変える方法を一緒に見ていきましょう。大丈夫、難しいことは一つもありませんよ！

—

1. 散らかった引き出しを整理しよう！ `@typedef`ってなに？

突然ですが、あなたの机の引き出しを想像してみてください。ペン、クリップ、レシート、謎のケーブルがひとつの引き出しにポイッと放り込まれている状態だと、いざボールペンを使いたい時に「あれ、どこだっけ？」と探すハメになりますよね。

JavaScriptのオブジェクトもこれとまったく同じです。例えば、「ユーザー情報」を扱うとき、コードのあちこちでこんなオブジェクトを作っていませんか？

// あちこちでバラバラに作られがちなユーザーデータ
const user1 = { id: 1, name: “山田太郎”, email: “yamada@example.com”, isPremium: true };
const user2 = { id: 2, name: “佐藤花子”, email: “sato@example.com” }; // あれ、isPremiumがない？

これ、コードの規模が大きくなると「このオブジェクトには何のプロパティが必須なんだっけ？」と完全に迷子になります。

そこで登場するのが `@typedef` です。
これは、いわば「我が家の引き出しのルールブック（設計図）」を作る機能です。「我が家における『ユーザー』とは、こういう形をしています！」とあらかじめ定義しておくことで、エディタ（VS Codeなど）がそれを読み取り、私たちのコーディングを強力にサポートしてくれるようになります。

—

2. お買い物のレシートでイメージしてみる

もう少し身近な例で考えてみましょう。
「オンラインショップのお買い物カート」を想像してください。カートの中には「商品」が入っていますよね。

商品は、「商品ID」「商品名」「価格」「個数」という決まった項目（プロパティ）を持っています。これを`@typedef`を使って定義してみましょう。

実際のコードを見てみてください。

@typedef {Object} CartItem
@property {string} id – 商品のユニークなID
@property {string} name – 商品の名前
@property {number} price – 商品の単価（円）
@property {number} quantity – 購入する個数

たったこれだけです！
見慣れない書き方をしているかもしれませんが、怖がらなくて大丈夫。分解して読んでみましょう。

1. `/ … /` : これはJSDocと呼ばれる特別なコメントの書き方です。エディタはこの中身を「ただのメモ書き」ではなく「コードの指示書」として読み取ります。
2. `@typedef {Object} CartItem` : 「ここから新しい型（カスタム型）の定義を始めます。名前は `CartItem` にします。中身はオブジェクトです」と宣言しています。
3. `@property {型} プロパティ名 – 説明` : オブジェクトの中身のパーツを一つずつ登録しています。

これで、「CartItem」という名の便利なカスタム型が一つ完成しました！

—

3. 実際にエディタで使ってみよう！

さて、作った設計図（型定義）をどうやって実際のコードで使うのか、お買い物の合計金額を計算する関数を例に見てみましょう。

以下のコードを、そのままVS Codeなどのエディタに貼り付けてみてください。

@typedef {Object} CartItem
@property {string} id – 商品のユニークなID
@property {string} name – 商品の名前
@property {number} price – 商品の単価（円）
@property {number} quantity – 購入する個数

カート内の総額を計算する関数
@param {CartItem[]} items – カートに入っている商品の配列
@returns {number} 税込の総額

/
function calculateTotalPrice(items) {
// reduceを使って合計金額を計算
const subtotal = items.reduce((sum, item) => {
return sum + (item.price item.quantity);
}, 0);

// 10%の税金を足して返す
return Math.floor(subtotal 1.1);
}

// — 実際に使ってみる —

/ @type {CartItem[]} /
const myCart = [
{ id: “p001”, name: “JavaScriptの極意（本）”, price: 3000, quantity: 1 },
{ id: “p002”, name: “特製マグカップ”, price: 1500, quantity: 2 }
];

const total = calculateTotalPrice(myCart);
console.log(`お支払い総額（税込）: ${total}円`);

ここで注目してほしいポイントがあります。
`@param {CartItem[]} items` と書くことで、「この関数には、さっき定義した `CartItem` がたくさん詰まった配列（Array）を渡してくださいね」とエディタに伝えています。

もし、あなたがうっかり `price` というプロパティ名を `amount` と打ち間違えたり、文字列を入れなきゃいけないところに数字を突っ込んだりすると、エディタが波線（エラー表示）を出して「ちょっと待って、それ設計図と違うよ！」と優しく教えてくれるようになります。

—

4. 現場で役立つ！ちょっと踏み込んだテクニック

基本の形ができるようになったら、実務でよく使う少し便利な書き方も知っておくと、さらにコーディングが楽しくなります。

オプショナル（なくてもいい）プロパティの指定

すべてのデータに同じ項目があるとは限りませんよね。例えば、ユーザー情報で「ミドルネーム」は人によって無い場合があります。そんなときは、プロパティ名を角括弧 `[]` で囲みます。

@typedef {Object} User
@property {string} name – 名前（必須）
@property {string} [middleName] – ミドルネーム（無くてもOK）

これだけで、「あ、このプロパティは存在しないかもしれないから、使うときは値があるかチェックしなきゃな」とエディタが気づかせてくれます。

型を組み合わせる（ネスト構造）

オブジェクトの中に、さらに別のオブジェクトが入るような複雑な構造も表現できます。

@typedef {Object} Address
@property {string} zipcode – 郵便番号
@property {string} city – 市区町村

@typedef {Object} UserProfile
@property {string} name – ユーザー名
@property {Address} address – 住所（先ほどのAddress型を利用！）

このように型同士を組み合わせることで、どれだけ複雑なデータ構造であっても美しくドキュメント化することができます。

—

まとめ：ドキュメントと型安全を同時に手に入れよう

今回は、JavaScriptの `@typedef` を使ったカスタム型定義について解説しました。

`@typedef` は、JavaScriptの世界で使える「データの設計図」
エディタ（VS Codeなど）が型を解釈し、入力補完やエラーチェックで助けてくれるようになる
TypeScriptにすぐ移行できなくても、今すぐバニラなJSのままで導入できる

「なんだかコードにコメントをたくさん書くの面倒だな…」と思われるかもしれませんが、未来の自分や、一緒に働くチームメイトにとって、これほどありがたい道標（みちしるべ）はありません。数日後のあなたが、「おっ、前の自分、丁寧な設計図を残してくれてるじゃん！」と感動する日が必ず来ます。

まずは小さなオブジェクトから、ぜひ今日のコードに `@typedef` を取り入れてみてくださいね。あなたの開発ライフが、少しでも快適で楽しいものになりますように！