TypeScript ドキュメント
簡潔で実例中心の TypeScript リファレンス。概念を読み、コードを見て、Coddy のジャーニーで実践しましょう。
TypeScript のガイド付き学習を始めるはじめに
- TypeScriptとはTypeScriptとは、静的な型を持つJavaScriptです。この入門ページでは、値に型を注釈し、実行前にコンパイラーがチェックし、ブラウザーやNode.js、Deno、Bunで動く普通のJavaScriptが出力されるまでを、実行できるサンプルで解説します。
- TypeScriptとJavaScriptの違いTypeScriptとJavaScriptの違いは、実行前にチェックされる静的な型システムがあるかどうかです。構文、型チェッカーが見つけるバグ、ビルドの手順、実行速度、学習コスト、JavaScriptのプロジェクトを移行する方法を並べて比較します。
- インストールTypeScriptをnpmでプロジェクトの開発用依存としてインストールし、npx tsc --version でバージョンを確認し、tsc --init で tsconfig.json を作り、最初のファイルをコンパイルします。グローバルインストール、pnpm、Yarn、Bun、よくあるエラーも解説します。
- TypeScriptの実行.tsファイルを実行する5つの方法を解説します。tscでコンパイルしてJavaScriptを実行する、node file.ts で直接実行する（型ストリッピング）、tsxやts-nodeを使う、DenoやBunを使う。それぞれ型チェックをするか、どの構文に対応するか、どれを選ぶべきかをまとめます。
- tsconfig.jsontsconfig.jsonはフォルダーをTypeScriptのプロジェクトとして扱い、コンパイラーオプションを設定するファイルです。重要なオプション（target、module、moduleResolution、strict、rootDir、outDir、include、lib、types、noEmit、skipLibCheck）、おすすめの初期設定、extends、TypeScript 7での変更点を解説します。
- TypeScript 7TypeScript 7は、TypeScriptのコンパイラーをGoで書き直したネイティブ版です。約10倍速く、tscコマンドも言語も同じです。利用者にとっての変更点（新しいデフォルト、削除されたオプション、JavaScript APIの欠如）、まだTypeScript 6が必要なツール、アップグレードの手順を解説します。
- コメントTypeScriptのコメントはJavaScriptと同じ // と /* */ に加えて、エディターのホバーに表示されるJSDocの /** */ コメントがあります。さらに @ts-expect-error、@ts-ignore、@ts-nocheck、@ts-check、/// <reference> ディレクティブという特別なコメントも読み取ります。
- TypeScript vs PythonTypeScriptとPythonはどちらもガベージコレクションを備えた高水準言語ですが、TypeScriptは実行前に型をチェックし、Pythonの型ヒントは任意で実行時には無視されます。型、ランタイム、速度、エコシステム、用途を、同じプログラムを両方で書いて比べます。
基本の型
- 基本の型TypeScriptの組み込み型 string、number、boolean、bigint、symbol、null、undefined と、配列・オブジェクトの概要。型注釈の書き方、整数型がない理由、String ではなく string と書く理由を解説します。
- 型推論TypeScriptはほとんどの型を書いた値から推論します。変数、let と const、オブジェクト、配列、戻り値で何が推論されるか、コールバックが文脈から型を得るしくみ、型注釈がまだ必要な場所を解説します。
- 文字列TypeScriptで文字列を扱う方法。テンプレートリテラルでの変数の埋め込み、複数行の文字列、部分文字列を含むかどうかの判定、よく使うメソッドとその戻り値の型、文字列リテラル型を解説します。
- 文字列と数値の変換TypeScriptで文字列を数値に変換する方法。Number()、parseInt()、parseFloat()、単項プラスがそれぞれ "42px"、""、"1e3" のような入力をどう扱うか、NaN の安全なチェック、数値から文字列への変換を解説します。
- 配列TypeScriptで配列に型を付ける方法。T[] と Array<T> の違い、オブジェクトの配列、複数の型を持つ配列、readonly 配列、map・filter・reduce・find の戻り値の型、リテラルの配列での includes の落とし穴を解説します。
- タプルTypeScriptのタプルは、[string, number] のように要素数が決まっていて位置ごとに型がわかる配列です。構文、ラベル付き要素、省略可能な要素と残余要素、readonly タプルと as const、関数からタプルを返す方法、配列との違いを解説します。
- オブジェクト型TypeScriptでオブジェクトに型を付ける方法。インラインのオブジェクト型、? による省略可能なプロパティ、readonly プロパティ、入れ子のオブジェクト、メソッド、余剰プロパティチェック、object と {} と Object の違いを解説します。
- enum（列挙型）TypeScriptの enum は、enum Direction { Up, Down } のように名前の付いた定数の集合です。数値 enum と文字列 enum、enum がコンパイルされたJavaScript、逆マッピング、enum のループ、const enum、そして文字列リテラルのユニオンや as const オブジェクトのほうが向いている場面を解説します。
特殊な型
- リテラル型リテラル型とは、"GET" や 404 のように値がちょうど1つしかない型です。文字列・数値・boolean のリテラル型、リテラル型のユニオン、let は型が広がり const は広がらない理由、as const の働き、const 型パラメーターを解説します。
- any と unknownany と unknown はどちらもあらゆる値を受け付けます。any はその値の型チェックを止め、unknown は使う前に値をチェックさせます。違い、unknown の絞り込み方、noImplicitAny、型付きのコードに any が紛れ込む場所を解説します。
- never 型never は値を1つも持たない型です。終わらない関数の戻り値の型であり、絞り込みですべてのケースを除外したあとに残る型であり、switch の網羅性チェックを支える道具です。never がどこから現れるか、void とどう違うかを解説します。
- null と undefinedstrictNullChecks が有効なら、null と undefined は別々の型で、TypeScriptはその処理を求めます。チェックの方法、オプショナルチェーン（?.）、Null 合体演算子（??）と ??=、そして省略可能なプロパティと | undefined の違いを解説します。
- 非null アサーション（!）user! のように値のあとに付けるエクスクラメーションマークは非 null アサーション演算子で、実行時のチェックなしに型から null と undefined を取り除きます。x! が何をするか、確実な代入アサーション let x!: T と prop!: T、それらが危険な理由、より安全な代替手段を解説します。
インターフェースと型エイリアス
- interface（インターフェース）interface はオブジェクトの形、つまりどんなプロパティを持ち、それぞれがどんな型かに名前を付けます。宣言の書き方、省略可能なプロパティと readonly プロパティ、メソッド、インデックスシグネチャ、継承、クラスでの実装、宣言のマージ、ジェネリックなインターフェース、インターフェースにデフォルト値を与える方法を解説します。
- 型エイリアス（type）型エイリアスは、type キーワードであらゆる型に名前を付けます。オブジェクトの形、ユニオン型、タプル、関数、ジェネリクス、再帰的な型です。構文、それぞれの形の書き方、そしてエイリアスは名前にすぎず、別の新しい型ではない理由を解説します。
- interface と type の違いinterface と type はどちらもオブジェクトの形を表せ、たいていはどちらでも動きます。本当の違い、つまり宣言のマージ、ユニオン型とマップ型、extends と交差型、暗黙のインデックスシグネチャ、エラーの表示とコンパイラーのパフォーマンスを解説し、選び方のはっきりしたルールを示します。
- extends キーワードextends キーワードは、ある型から別の型を作ります。インターフェースの拡張（1つから、または複数から）、& による型エイリアスの拡張、プロパティの型の上書き、Omit によるプロパティの置き換え、そしてクラス、ジェネリクスの制約、条件型での extends の意味を解説します。
- ユニオン型string | number のようなユニオン型は、値がいくつかの型のどれか1つであることを表します。ユニオン型でできること（すべてのメンバーが持つものだけ）、絞り込み方、リテラルやオブジェクト型のユニオン、(A | B)[] と A[] | B[] の違いを解説します。
- 交差型交差型 A & B は、同時に A でも B でもある値を表すので、両方のメンバーをすべて持ちます。& でオブジェクト型を組み合わせる方法、衝突するプロパティが never になる理由、ユニオン型の交差型が共通のメンバーだけを残すこと、代わりに extends を使うべき場面を解説します。
- 判別可能なユニオン型判別可能なユニオン型とは、kind や status のような共通のリテラルのタグプロパティを持つオブジェクト型のユニオンです。タグをチェックするとオブジェクト全体が絞り込まれます。パターンの書き方、switch による絞り込み、never による網羅性チェック、APIの結果、リクエストの状態、状態機械のモデル化を解説します。
関数
- 関数TypeScriptで関数に型を付ける方法。すべての引数に型注釈を書き、戻り値の型は書くか推論に任せ、何も返さない関数には void を使います。アロー関数、関数式、async 関数、this パラメーターの型付けも解説します。
- 関数型TypeScriptで関数の型を書く方法。アロー構文 (a: number) => string、関数の型エイリアス、アロー関数とコールバックの型付け、呼び出しシグネチャとコンストラクトシグネチャ、そして Function 型がゆるすぎる理由を解説します。
- 省略可能な引数TypeScriptでは引数に ? を付けると省略可能になり、デフォルト値を付けたり、残余引数で任意の数の引数を受け取ったりもできます。引数の順序のルール、省略と undefined の違い、オプションオブジェクト、関数型の中の省略可能な引数を解説します。
- 関数のオーバーロードTypeScriptの関数オーバーロードを使うと、1つの関数に呼び出しシグネチャを複数持たせ、それぞれに別の戻り値の型を付けられます。オーバーロードシグネチャと実装の書き方、コンパイラーがチェックするルール、ユニオン型の引数のほうがよい場面、クラスでのオーバーロードを解説します。
型の絞り込みと判定
- 型の絞り込み型の絞り込み（narrowing）とは、TypeScriptが string | number のような広い型を、if や switch の中、早期 return のあとで具体的な型にすることです。typeof、truthiness、等価比較、in、instanceof、代入、型述語、判別可能なユニオン型まで、絞り込みの方法を1か所にまとめました。
- typeof 演算子TypeScriptの typeof には2つの役割があります。コードの中では実行時に "string"、"number"、"object" などを返すJavaScriptの演算子で、TypeScriptはこれで型を絞り込みます。型の中では変数の型をコピーする型クエリで、keyof typeof obj や ReturnType<typeof fn> のように使います。
- instanceof 演算子instanceof は、オブジェクトがクラスから作られたかを実行時にチェックし、TypeScriptは変数をそのクラスに絞り込みます。自作クラスと Error のサブクラスでの使い方、インターフェースや型エイリアスをチェックできない理由、意外な結果になる場面を解説します。
- 型ガード型ガードとは、TypeScriptが理解できる実行時のチェックです。組み込みの型ガード、value is Type という型述語を使った自作の型ガード、オブジェクトがある型かどうかのチェック、asserts を使ったアサーション関数、unknown のデータの検証方法を解説します。
- 型アサーション（as）as キーワードは、値を別の型として扱うようTypeScriptに伝えます。キャストではありません。実行時には何も変換もチェックもされません。as と山かっこの構文、コンパイラーが許可する範囲、unknown を経由する二重アサーション、型ガードのほうが向いている場面を解説します。
- satisfies 演算子satisfies 演算子は、値の推論された型を変えずに、その値が型に合っているかをチェックします。何をするのか、型注釈や as との比較（同じオブジェクトを3通りに書いて比較）、as const との組み合わせ、設定オブジェクトに向いている理由を解説します。
クラス
- クラスTypeScriptのクラスは、フィールド、メソッド、コンストラクターに型が付いたJavaScriptのクラスです。フィールド宣言と strictPropertyInitialization の仕組み、this の型付け、getter と setter、static メンバー、implements、そしてクラスが型としても使えることを解説します。
- コンストラクターTypeScriptでクラスのコンストラクターに型を付ける方法。型付きの引数と省略可能な引数、constructor(private name: string) のような引数プロパティ、フィールドの初期化の順序、コンストラクターのオーバーロード、サブクラスでの super の呼び出し、private コンストラクター、new を使ったコンストラクターの型を解説します。
- アクセス修飾子TypeScriptには public、private、protected の3つのアクセス修飾子と readonly があります。それぞれが何を許可するか、TypeScriptの private がコンパイル時のチェックであるのに対し、JavaScriptの #private フィールドが実行時に強制される理由、どちらを選ぶべきかを解説します。
- 継承TypeScriptのクラス継承を解説します。extends と super、型の互換性を保ったメソッドのオーバーライド、override キーワードと noImplicitOverride、protected メンバー、declare を使ったフィールドの再宣言、implements のほうが向いている場面です。
- 抽象クラスTypeScriptの抽象クラスは、インスタンスを作れず、メソッドの実装をサブクラスに任せられる基底クラスです。抽象メソッドと抽象プロパティ、テンプレートメソッドパターン、抽象コンストラクターの型、インターフェースのほうが向いている場面を解説します。
- デコレーターデコレーターは、@ 構文でクラスのメンバーをラップしたり置き換えたりする関数です。TypeScriptがフラグなしでサポートする標準のデコレーター（クラス、メソッド、getter、フィールド、accessor）、デコレーターファクトリー、addInitializer、そして Angular や NestJS が使う従来の experimentalDecorators との違いを解説します。
ジェネリクス
- ジェネリクスジェネリクスを使うと、関数、インターフェース、型、クラスが多くの型に対応しつつ、型どうしのつながりを保てます。入れた型が出てくる型を決めます。ジェネリック関数、型引数の推論、複数の型パラメーター、ジェネリックなインターフェースとクラス、デフォルトの型、ジェネリクスを使わないほうがよい場面を解説します。
- ジェネリクスの制約ジェネリクスの制約 T extends Something は、型パラメーターが受け付ける型を制限し、制約が保証するものを関数の中で使えるようにします。オブジェクトの形やインターフェースを使った extends、プロパティに安全にアクセスする K extends keyof T、プリミティブへの制約、よく出会うエラーを解説します。
型演算子
- keyof 演算子keyof はオブジェクト型を受け取り、そのプロパティ名のユニオン型を返します。インターフェースに対する keyof、普通のオブジェクトに対する keyof typeof、ジェネリクスを使った型付きのプロパティアクセス、インデックスシグネチャ（string | number）、Object.keys が string[] を返す理由を解説します。
- インデックスアクセス型インデックスアクセス型は、別の型からプロパティの型を読み出します。Person["age"] は number です。T["key"]、ユニオン型のキー、T[keyof T]、配列の要素の型を得る T[number]、タプルのインデックス、そして const の配列をユニオン型に変える (typeof arr)[number] を解説します。
- マップ型（Mapped Types）マップ型は、キーをループして新しいオブジェクト型を作ります: { [K in keyof T]: ... }。構文、+/- を使った readonly と ? の修飾子、as によるキーの再マッピング、キーの絞り込み、そして Partial、Readonly、Required、Pick、Record がどう書かれているかを解説します。
- 条件型条件型は、テストに基づいて2つの型のどちらかを選びます: T extends U ? X : Y。構文、条件型がユニオン型に分配される仕組み（とその止め方）、infer による型の取り出し、ReturnType を自分で書く方法を解説します。
- テンプレートリテラル型テンプレートリテラル型は、JavaScriptのテンプレート文字列と同じバッククォートの構文で文字列リテラル型を作ります: `on${Capitalize<E>}`。構文、ユニオン型が掛け合わされる仕組み、Uppercase と Capitalize、`${number}px` のようなパターン、マップ型での getter、infer による文字列の解析を解説します。
- ブランド型ブランド型は、string & { readonly __brand: "UserId" } のように見えないタグを付けたプリミティブで、OrderId が期待される場所に UserId を渡せなくします。ブランドの仕組み、検証するコンストラクター関数、汎用の Brand ヘルパー、unique symbol のブランド、ブランド付きの数値を解説します。
ユーティリティ型
- ユーティリティ型TypeScriptの組み込みユーティリティ型をすべて1か所にまとめました。Partial、Required、Readonly、Pick、Omit、Record、Exclude、Extract、NonNullable、Parameters、ReturnType、Awaited、文字列の型など、それぞれに1行の説明と実行できるサンプルを付けています。
- RecordRecord<K, V> は、キーが K で値がすべて V のオブジェクト型です。文字列のキーとユニオン型のキー（すべてのキーが必須）での Record、Partial<Record>、型付きのキーでの Record のループ、存在しないキーの落とし穴、インデックスシグネチャや Map を使うべき場面を解説します。
- Partial と RequiredPartial<T> は T のすべてのプロパティを省略可能にします。更新やパッチのオブジェクトにぴったりの型です。更新関数での Partial、それが浅い理由、DeepPartial の書き方、明示的な undefined の落とし穴、そしてその逆の Required<T> を解説します。
- OmitOmit<T, K> は、T のプロパティからキー K を除いたすべてを持つ型を作ります。1つや複数のキーの Omit、プロパティの型の上書き、実行時のプロパティの削除、Omit と Exclude や Pick の違い、Omit が存在しないキーを受け付ける理由、厳密な Omit、ユニオン型への Omit を解説します。
- PickPick<T, K> は、T のプロパティのうちキーが K に含まれるものだけを持つ型を作ります。1つや複数のキーの Pick、キーのチェックのされ方、Pick と Omit の違い、ネストした型からの Pick、型付きの pick() 関数、値の型によるプロパティの選択を解説します。
- readonly と Readonlyreadonly 修飾子とユーティリティ型 Readonly<T> は、コードがプロパティを再代入するのを止めます。readonly プロパティとクラスのフィールド、Readonly<T>、readonly 配列（readonly T[] と ReadonlyArray）、ReadonlyMap と ReadonlySet、readonly が浅くコンパイル時だけのものである理由、Object.freeze や as const との比較を解説します。
- Exclude と ExtractExclude、Extract、NonNullable はユニオン型のメンバーを絞り込むユーティリティ型です。それぞれが何を残し何を取り除くか、形でユニオン型のメンバーを選ぶ方法、条件型による定義、Omit や Pick との違いを解説します。
- ReturnType と ParametersReturnType、Parameters、ConstructorParameters、InstanceType、Awaited は、関数、クラス、Promise から型を取り出すユーティリティ型です。typeof と組み合わせた使い方、async 関数の結果の型の取り方、オーバーロードやジェネリクスでの動き、infer による ReturnType の定義を解説します。
ループとコレクション
- ループTypeScriptのループの書き方と、それぞれで得られる型。基本の for 文、配列・Map・文字列に対する for...of、文字列のキーを返す for...in、break も await も使えない forEach、オブジェクトのキーを型付きでループする方法、while を解説します。
- switch 文TypeScriptの switch 文。構文、各 case でユニオン型が絞り込まれるしくみ、case が足りないとコンパイルできなくなる網羅的な switch、switch (true) のパターン、フォールスルーとブロックスコープを解説します。
- MapTypeScriptで Map を使う方法。型付きの Map<K, V> の作り方、get が V | undefined を返す理由、set・has・delete、挿入順でのループ、オブジェクトのキー、オブジェクトや JSON との相互変換、Map とオブジェクトと Record の違い、array.map() の型を解説します。
- 連想配列（辞書）TypeScriptには辞書やハッシュマップのクラスはありません。キーと値の対応表は、インデックスシグネチャ、Record<K, V>、Map<K, V> で型付けします。それぞれの使い方、キーの存在チェック、追加・削除・ループ、そして辞書で noUncheckedIndexedAccess が重要な理由を解説します。
非同期処理とエラー
- PromiseTypeScriptでの Promise の型付けを解説します。Promise<T> 型、new Promise と resolve の型付け、then による型の変化、catch で any になる理由、タプルを返す Promise.all、Promise.allSettled の結果の型、コールバックのAPIを型付きの Promise でラップする方法です。
- async/awaitTypeScriptでの async と await の型付けを解説します。async 関数は Promise<T> を返し、await がそれを展開し、エラーは try/catch で捕まえます。トップレベルの await には ES モジュールが必要なこと、1つずつ await する場合と並列に await する場合の違い、forEach の落とし穴も扱います。
- エラー処理TypeScriptのエラー処理を解説します。catch の変数が unknown になる理由、instanceof Error での絞り込み、エラーの throw、name と cause を持つ独自のエラークラスの書き方、そして想定されるエラーのための Result 型パターンです。
- sleep（待機）TypeScriptには組み込みの sleep はありませんが、1行で作れます。setTimeout で解決される Promise<void> を返す関数です。await での使い方、ループの中での待機、遅延付きのリトライ、sleep のキャンセル、そしてJavaScriptに処理をブロックする sleep がない理由を解説します。
モジュールとツール
- モジュールトップレベルに import か export があるTypeScriptのファイルはすべてモジュールです。名前付きエクスポートとデフォルトエクスポート、import type と export type、module 設定で ES モジュールと CommonJS のどちらが出力されるか、node16 と nodenext で import に .js 拡張子が必要な理由を解説します。
- namespace（名前空間）TypeScriptの namespace は、値と型をひとつの名前の下にまとめ、普通のオブジェクトにコンパイルされます。構文、namespace どうしや関数・クラスとのマージ、ES モジュールに置き換えられた理由、宣言ファイルとグローバル拡張など今も namespace に出会う場面を解説します。
- 型定義ファイル（.d.ts）.d.ts ファイルは、JavaScriptのコードを含まずにその型だけを記述します。declare キーワードは .ts ファイルの中で同じ役割をします。型定義ファイルの生成方法、@types パッケージの位置づけ、型のないモジュールへの型付け、declare global とモジュール拡張で既存の型を広げる方法を解説します。
- strict モードtsconfig.json の strict: true は、noImplicitAny、strictNullChecks、strictPropertyInitialization など一連の型チェックを有効にします。それぞれが何を検出するか、既存のプロジェクトで strict モードを有効にする方法、strict に含まれない便利なフラグを解説します。
- JSONJSON.parse は any を返すので、TypeScriptは結果に付けた型をそのまま信じます。パースした JSON に型を付ける方法、型ガードでの検証、JSON のサンプルからインターフェースを作る方法、.json ファイルの import、JSON.stringify が Date や Set や undefined をどう変換するかを解説します。
さらに先へ
- ベストプラクティス実際のバグを防ぐTypeScriptの8つの習慣。strict を有効に保つ、any ではなく unknown を使う、推論に任せる、enum よりユニオンを選ぶ、設定を satisfies でチェックする、状態を判別可能なユニオンで表す、! と as を避ける、データを readonly にする。それぞれ実行できる修正前後のコード付きです。
- 面接質問TypeScriptの面接でよく聞かれる25の質問を、短く正確な回答とコード付きで、初級から上級まで分けて紹介します。any と unknown、interface と type、ジェネリクス、型の絞り込み、ユーティリティ型、マップ型と条件型、構造的型付け、tsconfig、TypeScript 7。
