TypeScriptのanyとunknownの違いと使い分け

any と unknown はどちらもあらゆる値を受け付けます。違いは、そのあと値に対して何ができるかです。any は何でもでき、何もチェックしません。unknown は、値が何であるかを証明するまでほとんど何もできません。

let a: any = "hello";
let u: unknown = "hello";

console.log(a.toUpperCase()); // HELLO: any allows every operation

// @ts-expect-error: 'u' is of type 'unknown'.
u.toUpperCase();

if (typeof u === "string") {
  console.log(u.toUpperCase()); // HELLO: u is a string inside this block
}

@ts-expect-error の行がなければ、u.toUpperCase() はコンパイルエラー TS18046 です。typeof のチェックが u を string に絞り込み、そのブロックの中では文字列のメソッドがすべて使えます。

any と unknown の比較

型理論の言葉で言えば、unknown はトップ型です。あらゆる型を代入でき、unknown 自身は unknown と any にしか代入できません。any は抜け道で、never 以外のすべてに対して双方向に代入できます。

any は型チェックを止める

any 型の値は無条件に信用されます。コンパイラーは打ち間違い、間違った型、存在しないプロパティを受け入れ、間違いは実行時に表れます。

const user: any = { name: "Ada" };

const total: number = user.name; // compiles: any is assignable to number
console.log(typeof total);       // string

const city = user.adress;        // typo, still compiles
console.log(city);               // undefined

try {
  console.log(user.address.city); // compiles, throws at runtime
} catch (e) {
  console.log((e as Error).message);
}

出力が問題を示しています。number と型注釈を付けた変数が文字列を持ち、最後の行は Cannot read properties of undefined (reading 'city') を投げます。any は広がりもします。user.name は any なので、そこから計算した値もすべて any になり、型のない1つの値が、入ってきた場所から遠く離れたところでチェックを止めてしまいます。

unknown は先にチェックさせる

unknown では、コードが値を絞り込むまで、コンパイラーはあらゆる操作を拒否します。絞り込みには普通のJavaScriptのチェックを使い、各ブランチの中では値はチェックした型になります。

function describe(value: unknown): string {
  if (typeof value === "string") return `string of length ${value.length}`;
  if (typeof value === "number") return `number ${value.toFixed(2)}`;
  if (Array.isArray(value)) return `array of ${value.length}`;
  if (value instanceof Date) return `date ${value.toISOString()}`;
  if (value === null) return "null";
  if (typeof value === "object" && "id" in value) return `object with id ${String(value.id)}`;
  return typeof value;
}

console.log(describe("hi"));                               // string of length 2
console.log(describe(3.14159));                            // number 3.14
console.log(describe([1, 2, 3]));                          // array of 3
console.log(describe(new Date("2024-03-15T10:30:00Z")));   // date 2024-03-15T10:30:00.000Z
console.log(describe({ id: 7 }));                          // object with id 7
console.log(describe(undefined));                          // undefined

typeof null は "object" なので、value === null のチェックはオブジェクトのチェックより前に置く必要があります。"id" in value のあとでは、オブジェクトが id プロパティを持つことをTypeScriptは知っていますが、中身については何もわからないので型は unknown です。String() で明示的にテキストに変換しています。数値として使うなら、先に typeof でチェックします。

アサーション value as string でチェックを省くこともでき、コンパイラーはそれを受け入れます。しかしそれは実行時のチェックの裏付けのない約束なので、本当のチェックを選びましょう。型アサーション を参照してください。

unknown でJSONを検証する

JSON.parse は any を返すと宣言されているので、その結果は黙ってチェックを無効にします。結果に unknown と型注釈を付け、残りのコードが信用する前に形をチェックする型ガードを書きましょう。

interface Settings {
  theme: string;
  fontSize: number;
}

function isSettings(v: unknown): v is Settings {
  return (
    typeof v === "object" && v !== null &&
    "theme" in v && typeof v.theme === "string" &&
    "fontSize" in v && typeof v.fontSize === "number"
  );
}

const inputs = ['{"theme":"dark","fontSize":14}', '{"theme":"dark"}'];

for (const text of inputs) {
  const data: unknown = JSON.parse(text);
  if (isSettings(data)) {
    console.log(`${data.theme} at ${data.fontSize}px`);
  } else {
    console.log("invalid settings:", text);
  }
}

最初の入力は dark at 14px を出力し、2つ目は fontSize がないので拒否されます。any なら、2つ目の入力は fontSize が undefined の Settings としてそのまま流れてしまいます。大きなスキーマなら、検証ライブラリが同じことをして型も作ってくれます。

noImplicitAny

any は、誰かが書いた場合にだけ現れるわけではありません。型注釈がなく推論の手がかりもない引数も any になります。strict で有効になる noImplicitAny オプションは、それをエラーとして報告します:

// This does not compile: x has no type
function double(x) {
  return x * 2;
}

console.log(double(4));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

型注釈を付ければ直ります: function double(x: number)。明示的に x: any と書いてもコンパイルでき、それが狙いです。any がコードの中で目に見える形で残り、検索もレビューもできます。

それでも any が紛れ込む場所

strict のもとでも、次のものはコードに any という単語が現れないまま any を生みます:

何でも throw でき、Error オブジェクトだけとは限らないので、strict のもとでは catch の変数は unknown です。e.message を読む前に e instanceof Error で絞り込みましょう。

any を使ってもよい場面

any は禁止されているわけではありませんが、使うたびにコンパイラーが守らない場所が1つ増えます。妥当な使い方は次のとおりです:

• JavaScriptのコードベースを移行している最中で、まだ型付けされていない部分の目印として。
• 型システムでうまく表現できないコードで、小さく保ち、型付きの関数シグネチャの内側に閉じ込めたもの。
• 意図的に不正なデータを渡すテストコード。

それ以外はすべて、unknown がチェックを保ったまま同じ「この型はわからない」というケースをカバーします。多くのチームは lint ルール @typescript-eslint/no-explicit-any でこれを強制しています。関連する型 Record<string, unknown> は、「値のわからない何かのオブジェクト」を表すときの定番です。