【実務・中級編】 @readonlyによるイミュータブルなプロパティ定義 – JavaScript実践ガイド

やあ。最近、プロダクトの規模が膨らみすぎて「どこで誰がこのステートを書き換えたんだ…？」という不毛なバグハンティングに時間を溶かしてないかい？

中級から一段上のシニアへと駆け上がるエンジニアが必ず直面するのが、この「意図しないプロパティの書き換え（ミュータビリティの暴走）」という悪夢だ。特にTypeScriptを導入していれば `readonly` や `as const` で守られるけれど、レガシーなJSコードベースや、あえてJSDocをメインに据えた軽量なモジュール開発では、油断するとすぐにオブジェクトが汚染されてしまう。

そこで今回は、TypeScriptを使わずとも、JSDocの `@readonly` アノテーションを駆使してIDE（VSCodeなど）上でバグの芽をバキバキに摘み取る実務テクニックを伝授しよう。ブラウザの裏側の挙動も含めて、本質を叩き込んでいくから、ついてきてくれよ。

—

1. JavaScriptにおける「読み取り専用」の現実と、JSDocがもたらす恩恵

まず前提として、JavaScriptのオブジェクトはデフォルトで「何でもあり」のオープンな世界だ。`const` で宣言した変数であっても、オブジェクトのプロパティそのものは平気で書き換えられる。

const user = { name: ‘Alice’ };
user.name = ‘Bob’; // 普通に通る。constが守るのは「再代入」だけで、「プロパティの変更」ではない。

これを防ぐために、標準APIには `Object.freeze()` が存在する。

裏側の処理：`Object.freeze()` とブラウザの最適化

`Object.freeze(obj)` を呼ぶと、JavaScriptエンジン（V8など）は内部のオブジェクトのフラグを書き換えて、プロパティの追加・削除・変更を禁止する（`extensible: false`, `writable: false`, `configurable: false` になる）。

runtime（実行時）の安全性としては最高だが、実務でこれをやると「厳格モード（strict mode）下では、書き換えようとした瞬間に例外（TypeError）がスローされる」という副作用がある。開発中のちょっとしたミスでアプリ全体がクラッシュするのは、ユーザー体験としても避けたいところだ。

そこで登場するのが、JSDocの `@readonly` だ。
これは実行時ではなく、開発時（IDEの静的解析のレイヤー）で私たちを救ってくれる。ブラウザのメモリやパフォーマンスを一切汚さずに、コードを書いているまさにその瞬間にエディタが赤く警告を出してくれるという、現代フロントエンド開発の必須教養なのだ。

—

2. 実践！ `@readonly` を使った堅牢なオブジェクト定義

百聞は一見にしかず。実務のコードベースでそのまま使える、綺麗なサンプルを見ていこう。
エディタ（VSCode等）で開けば、誤った代入に対して即座に波線（エラー警告）が出るはずだ。

/

• @typedef {Object} SystemConfig
• @property {string} API_BASE_URL – APIのエンドポイント
• @property {number} TIMEOUT_MS – 通信タイムアウト時間
• @property {boolean} DEBUG_MODE – デバッグモードのフラグ

/

/

• アプリケーションのグローバル設定
• @type {SystemConfig}
• @readonly

/
export const CONFIG = {
API_BASE_URL: ‘https://api.example.com/v1’,
TIMEOUT_MS: 5000,
DEBUG_MODE: process.env.NODE_ENV !== ‘production’,
};

// ———————————————————
// ここから下で「うっかりミス」をやってしまった場合の実例
// ———————————————————

// ❌ 警告（またはエラー）: Cannot assign to read-only property ‘API_BASE_URL’ of object ‘#