TypeScriptのas: 型アサーションとキャストを解説

value as Type は型アサーションで、value を Type として扱うようTypeScriptに伝えます。キャストと呼ばれることがありますが、コンパイラーへの指示にすぎません。JavaScriptの出力からは消え、実行時には何も変換せず、何もチェックしません。

interface Config {
  port: number;
  host: string;
}

const text = '{"port": 8080, "host": "localhost"}';

// JSON.parse returns any; the assertion gives the result a useful type
const config = JSON.parse(text) as Config;

console.log(config.port + 1);            // 8081
console.log(config.host.toUpperCase());  // LOCALHOST

これが典型的な使い方です。コンパイラーにはわからない値の情報（ここではJSONの形）を自分が知っていて、それを伝えています。間違っていても何も警告されません。以下では、それが何を意味するか、そして実行時のチェックのほうがよいのはどんなときかを説明します。

as と山かっこの構文

同じアサーションに2つの書き方があります:

const someValue: unknown = "hello";
const a = someValue as string;   // as syntax
const b = <string>someValue;     // angle-bracket syntax, same meaning

山かっこの形は .tsx ファイルでは使えません。<string> がJSXのタグとして読まれてしまうからです。どこでも as を使えば、この問題は起きません。アサーションの結合は弱いので、式を続けるときはかっこで囲みます: (value as string).length。

アサーションは値を変換しない

ここが実際のバグにつながる部分です。アサーションが変えるのは値についてのコンパイラーの認識であって、値そのものではありません:

const input: unknown = "42";

const asserted = input as number;  // compiles: unknown can be asserted to anything
const converted = Number(input);   // an actual conversion

console.log(asserted + 1);   // 421 (string concatenation: it is still "42")
console.log(converted + 1);  // 43
console.log(typeof asserted, typeof converted); // string number

コンパイラーは asserted を number だと信じているので、asserted + 1 は算術演算として型チェックを通ります。実行時には文字列 "42" のままなので、JavaScriptは文字列を連結します。値の型を変えるには変換します: Number(x)、String(x)、Boolean(x)、BigInt(x)、new Date(x)。変換関数の比較は 文字列を数値に変換 のページにあります。

コンパイラーが許可する範囲

as は無制限ではありません。TypeScriptが x as T を許可するのは、どちらかの型がもう一方に代入できるときです。広げる方向（"a" as string、dog as Animal）も狭める方向（animal as Dog、unknown as User）も問題ありません。型にまったく重なりがなければ拒否します:

// This does not compile: string and number do not overlap.
const input = "42";
const n = input as number;

console.log(n);

コンパイラーは index.ts(3,11): error TS2352: Conversion of type 'string' to type 'number' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first. を報告します。メッセージ自体が抜け道を示しています: input as unknown as number。この二重アサーションはコンパイルできますが、実行時には上の例とまったく同じように間違っています。これが必要だと感じたら、たいていは変換（Number(input)）か、型を見直すのが正しい直し方です。

オブジェクトでは重なりのルールがゆるくなります。プロパティの一部を持つオブジェクトリテラルは受け入れられるので、as は不完全なオブジェクトを黙って通してしまいます:

interface User {
  name: string;
  email: string;
}

const draft = { name: "Ada" } as User; // compiles: email is missing
const empty = {} as User;              // compiles too

console.log(draft.name);               // Ada
console.log(typeof draft.email);       // undefined, although the type says string
console.log(empty.name?.length);       // undefined

型注釈（const draft: User = { name: "Ada" }）や satisfies User なら、足りない email を報告します（TS2741）。オブジェクトリテラルに as を使うのは本当にあとで埋めるつもりのときだけにして、完全なオブジェクトを作るほうを選びましょう。

as const は別物

as const はアサーションに見えますが、型をゆるめるのとは逆のことをします。リテラルをできるだけ狭い型にします。文字列はリテラル型のまま、配列は readonly のタプルになり、オブジェクトのプロパティは readonly になります。

const sizes = ["small", "medium", "large"] as const;
type Size = (typeof sizes)[number]; // "small" | "medium" | "large"

const point = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

function isSize(value: string): value is Size {
  return (sizes as readonly string[]).includes(value);
}

console.log(isSize("medium"), isSize("huge")); // true false
console.log(point.x + point.y);                // 3

コンパイラーに見えないことを主張するのではなく、リテラルを正確に表すだけなので安全です。（isSize の中の sizes as readonly string[] は広げる方向のアサーションで、これも安全です。includes が任意の文字列を受け付けるようになります。）詳しくは リテラル型 を参照してください。

型ガードのほうが向いている場面

as は主張で、型ガードはチェックです。データがコードの外から来る境界（JSON、fetch、localStorage、ユーザー入力、メッセージ）では、その主張が間違っていることがあり、アサーションは境界でのわかりやすいエラーを、どこか別の場所でのわかりにくいエラーに変えてしまいます。

interface Point {
  x: number;
  y: number;
}

function isPoint(v: unknown): v is Point {
  return typeof v === "object" && v !== null &&
    "x" in v && typeof v.x === "number" &&
    "y" in v && typeof v.y === "number";
}

const raw: unknown = JSON.parse('{"x": 3, "y": "4"}');

// With as: compiles, and the bug surfaces later
const p1 = raw as Point;
console.log(p1.x + p1.y); // 34 (a string snuck in)

// With a guard: the bad data is caught where it enters
if (isPoint(raw)) console.log(raw.x + raw.y);
else console.log("invalid point");

似たように見える方法の大まかな使い分けです:

as の正しい使い道は2つ残ります。コンパイラーが追えないものを絞り込む場合（2行前にセットした Map のエントリー、型のないライブラリからの値）と、部分的なテスト用データを作るテストコードです。どちらも小さく保ち、その主張が正しいとわかっている場所の近くに置きましょう。