TypeScriptのpossibly undefinedエラーの直し方

​​TypeScript​JavaScript,トラブルシュート

TypeScript の error TS2532: Object is possibly 'undefined'. は、undefined になるかもしれない値のプロパティを、確かめずに読もうとしたときに出ます。配列の find で検索した結果や、users[0] のように番号で取り出した要素でよく出ます。if で undefined でないことを確かめるか、?. と ?? で「見つからなかったとき」の値を決めると、エラーは消えます。

検索結果が見つからないときの処理を書き忘れた、という実行時のバグを、型チェックの段階で知らせてくれるエラーです。私は検証環境で tsc とエディターが使う言語サーバーの両方でこのエラーを起こし、メッセージの全文と、直すと消えることを確かめました。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。TypeScript は 7.0.2 を使い、比べるために 5.9.3 と 6.0.3 でも同じファイルを tsc にかけました。エディターの表示は、VS Code などのエディター本体ではなく、エディターが診断に使う TypeScript の言語サーバー(tsc --lsp --stdio)を直接動かして確かめました。VS Code の画面での見え方、React などのフレームワークの中で出る場合は試していません。

エラーの全文

検証環境で、空のフォルダーに TypeScript 7.0.2 を入れ、npx tsc --init で tsconfig.json を作りました。できた tsconfig.json には "strict": true と "noUncheckedIndexedAccess": true が入っていました。

src/find.ts に、ユーザーの配列から id が 3 の人を find で探し、その名前を表示するコードを書きました。

ts
type User = { id: number; name: string };

const users: User[] = [
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob" },
];

console.log(users.find((u) => u.id === 3).name);

npx tsc --noEmit を実行すると、次のように出ました(終了コードは1)。src には、このあとで出てくるほかの3つのファイルも置いていたので、実際にはエラーが4行出ています。ここでは src/find.ts の1行だけを載せます。

text
src/find.ts(8,13): error TS2532: Object is possibly 'undefined'.

--pretty を付けると、どこが問題なのかが波線で示されます(色を付けるための制御文字は消し、ほかのファイルの分と最後の集計は省いています)。

text
src/find.ts:8:13 - error TS2532: Object is possibly 'undefined'.

8 console.log(users.find((u) => u.id === 3).name);
              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

「そのオブジェクトは undefined かもしれない」という意味です。波線は .name ではなく、その手前の users.find((u) => u.id === 3) に引かれています。undefined かもしれないのは find の結果のほうだ、ということです。

find は、条件に合う要素がなければ undefined を返します(MDN の Array.prototype.find() の説明(英語))。TypeScript でも find の戻り値は User | undefined 型です。strictNullChecks の説明にあるとおり、このオプションが有効だと、undefined かもしれない値をそのまま使うとエラーになります。strictNullChecks は strict に含まれるので、"strict": true のプロジェクトではこのエラーが出ます。

エディターでも同じエラーが出る

エディターは、TypeScript の言語サーバーから診断(エラーの位置とメッセージ)を受け取って、赤い波線を引きます。TypeScript 7.0.2 の言語サーバーを tsc --lsp --stdio で起動し、エディターと同じ手順で src/find.ts を開かせると、次の診断が返ってきました。返ってきた JSON を、私が書いた小さなスクリプトで1件1行に整えて表示しています(ホバーの行は省いています)。

text
server: typescript-go 7.0.2
diagnostics (1):
  8:13-8:42 severity=1 source=ts code=2532 Object is possibly 'undefined'.

8:13-8:42 は、8行目の13文字目から、42文字目(.name の .)の手前までで、tsc --pretty の波線と同じ範囲です。severity=1 はエラー、code=2532 は TS2532 のことです。メッセージの文面も tsc と同じでした。

変数に入れると TS18048 に変わる

find の結果をいったん変数に入れてから使うと、エラーの番号と文面が変わります。

ts
const user = users.find((u) => u.id === 3);
console.log(user.name);
text
src/find-var.ts(9,13): error TS18048: 'user' is possibly 'undefined'.

TS2532 では「Object」だった部分に、変数の名前 'user' が入りました。言語サーバーで user にカーソルを合わせたときの表示(ホバー)は const user: User | undefined でした。省略できるプロパティでも同じです。type Config = { db?: { host: string } }; の db のように ? を付けたプロパティを、確かめずに config.db.host とたどると、'config.db' is possibly 'undefined'. のように、たどったプロパティの名前まで入った TS18048 になりました。

検証した4つの書き方で出たエラーをまとめると、次のとおりです。TS2532 と TS18048 は、どちらも同じ理由で出るエラーで、直し方も同じです。

書き方 出たエラー
users.find(...).name TS2532: Object is possibly 'undefined'.
users[0].name TS2532: Object is possibly 'undefined'.
const user = users.find(...) のあと user.name TS18048: 'user' is possibly 'undefined'.
config.db.host(db は省略できるプロパティ) TS18048: 'config.db' is possibly 'undefined'.

TypeScript 5.9.3 と 6.0.3 でも、同じファイルで同じ番号と文面のエラーが出ました。ただし tsc の終了コードは、5.9.3 と 6.0.3 では 2、7.0.2 では 1 でした。CI などで終了コードの値そのものを見ている場合は、気をつけてください。

users[0] で出るのは noUncheckedIndexedAccess のため

users[0].name でも TS2532 が出ました。配列の要素を番号で取り出したときに undefined を足すのは、noUncheckedIndexedAccess というオプションです。TypeScript 7.0.2 の tsc --init で作った tsconfig.json では、これが true になっていました。

同じファイルで --noUncheckedIndexedAccess false を付けて tsc を実行すると、users[0].name のエラーだけが消え、find と config.db のエラーは残りました。find の結果に undefined が付くのは、noUncheckedIndexedAccess とは関係なく、strictNullChecks によるものだからです。strictNullChecks も無効にすると、4つともエラーは出なくなりました。このとき、tsc --init の設定に入っている exactOptionalPropertyTypes は、strictNullChecks なしでは指定できず TS5052 のエラーになったので、これも無効にしました。

確かめずに実行すると TypeError で止まる

型のエラーは、実行時に起きることを先に知らせているだけです。src/find.ts を Node.js 22.23.4 でそのまま実行すると(Node.js は型の注釈を取り除いて実行するだけで、型チェックはしません。Node.js の TypeScript の説明)、次のように止まりました(終了コードは1。パスは例示用の値に置き換え、スタックの残りは省いています)。

text
/path/to/app/src/find.ts:8
console.log(users.find((u) => u.id === 3).name);
                                         ^

TypeError: Cannot read properties of undefined (reading 'name')
    at Object.<anonymous> (/path/to/app/src/find.ts:8:42)

id が 3 のユーザーがいないので find が undefined を返し、その .name を読もうとして止まっています。TS2532 は、このエラーを実行する前に知らせてくれていたわけです。

直し方とエラーが消えたこと

直したファイルに入れ替えて npx tsc --noEmit を実行すると、何も表示されずに終了コード 0 で終わりました。言語サーバーに開かせても、どのファイルも diagnostics (0): で、エラーは返ってきませんでした。

if で undefined でないことを確かめる

見つからなかったときに別の処理をしたいなら、if で分けます。

ts
const user = users.find((u) => u.id === 3);
if (user === undefined) {
  console.log("id 3 のユーザーはいません");
} else {
  console.log(user.name);
}

if で確かめたあとは、TypeScript が user の型を絞り込みます(公式ハンドブックの、=== による型の絞り込みの説明)。言語サーバーのホバーで見ると、if (user === undefined) の行の user は User | undefined ですが、else の中の user は User になっていました。実行すると「id 3 のユーザーはいません」と表示されました。

users[0] のときも、いったん変数に入れて if (first) で確かめるとエラーは消えました。配列のすべての要素を順に使うだけなら、for (const user of users) で回せば確かめる必要はありません。ホバーで見ると user の型は User で、エラーは出ませんでした。

?. と ?? で見つからなかったときの値を決める

表示するだけなど、見つからなければ代わりの値で済むときは、?.(オプショナルチェーン)と ?? を使うと1行で書けます(TypeScript 3.7 のリリースノート)。

ts
console.log(users.find((u) => u.id === 3)?.name ?? "(見つかりません)");

?. は、手前の値が undefined か null なら、その先を読まずに undefined を返します。?? は、左が undefined か null なら右の値を使います。実行すると「(見つかりません)」と表示されました。省略できるプロパティの config.db.host も、config.db?.host ?? "localhost" にするとエラーが消え、localhost と表示されました。

見つからないのがおかしいなら例外を投げる

必ずあるはずのデータが見つからないのは、プログラムの誤りです。その場合は、見つからなかったらその場で例外を投げる関数にまとめると、呼び出す側では undefined を気にせずに済みます。

ts
function getUser(id: number): User {
  const user = users.find((u) => u.id === id);
  if (!user) {
    throw new Error(`id ${id} のユーザーが見つかりません`);
  }
  return user;
}

console.log(getUser(2).name);

if のあとの return user; では、user は User 型に絞り込まれているので、戻り値の型 User と合います。実行すると Bob と表示されました。

! でエラーを消すと、実行時に止まる

find(...)!.name のように ! を付けても、TS2532 は消えます。tsc も言語サーバーも、エラーを出しませんでした。

ts
console.log(users.find((u) => u.id === 3)!.name);
注意

! は「この値は undefined ではない」と TypeScript に伝えるだけで、実行時の動きは変わりません(公式ハンドブックの、! 演算子の説明)。このファイルを実行すると、直す前と同じ TypeError: Cannot read properties of undefined (reading 'name') で止まりました。! を使うのは、undefined にならないと分かっているときだけにします。

Node.js がこのファイルを実行したときのエラー表示では、8行目は console.log(users.find((u) => u.id === 3) .name); となっていて、! があった場所が空白になっていました。! は型のための書き方なので、Node.js が実行する前に空白に置き換えて取り除いています(Node.js の型の除去の説明)。

​Posted by 86