typescript-ops

TypeScript の操作

型システム、ジェネリクス、本番環境向けのパターンを網羅する TypeScript スキルです。

エコシステムの情報は 2026-08-08 時点で検証済みです（TypeScript 7、Zod 4、Valibot 1）。

古さの確認： python scripts/check-typescript-facts.py --offline を実行すると、 カタログにあるバージョン関連の情報（TypeScript のメジャーバージョン、zod、valibot）が 本文中に引き続き記載されていることと、上記の日付付きの最新性に関する注記があることを確認できます。各パッケージの npm メジャーバージョンが記載されたメジャーバージョンと一致するか確認するには、--live を実行してください。カタログ：assets/typescript-facts.json。

型の絞り込みの判断ツリー

How to narrow a type?
│
├─ Primitive type check
│  └─ typeof: typeof x === "string"
│
├─ Instance check
│  └─ instanceof: x instanceof Date
│
├─ Property existence
│  └─ in: "email" in user
│
├─ Discriminated union
│  └─ switch on literal field: switch (event.type)
│
├─ Null/undefined check
│  └─ Truthiness: if (x) or if (x != null)
│
├─ Custom logic
│  └─ Type predicate: function isUser(x: unknown): x is User
│
└─ Assertion (you know better than TS)
   └─ as: value as string (escape hatch, avoid when possible)

型ガードの例

interface Dog { bark(): void; breed: string }
interface Cat { meow(): void; color: string }

function isDog(pet: Dog | Cat): pet is Dog {
    return "bark" in pet;
}

function handlePet(pet: Dog | Cat) {
    if (isDog(pet)) {
        pet.bark(); // TS knows it's Dog here
    } else {
        pet.meow(); // TS knows it's Cat here
    }
}

判別可能なユニオン

type Result<T> =
    | { status: "success"; data: T }
    | { status: "error"; error: string }
    | { status: "loading" };

function handle<T>(result: Result<T>) {
    switch (result.status) {
        case "success": return result.data;     // data is available
        case "error":   throw new Error(result.error); // error is available
        case "loading": return null;
    }
    // Exhaustiveness check: result is `never` here
    const _exhaustive: never = result;
}

ユーティリティ型のチートシート

ユーティリティ	機能	例
Partial<T>	すべてのプロパティを省略可能にする	更新ペイロードに使う Partial<User>
Required<T>	すべてのプロパティを必須にする	検証済みの設定に使う Required<Config>
Readonly<T>	すべてのプロパティを読み取り専用にする	不変の状態に使う Readonly<State>
Pick<T, K>	特定のプロパティを選択する	Pick<User, "id" | "name">
Omit<T, K>	特定のプロパティを除外する	Omit<User, "password">
Record<K, V>	型指定されたキーと値を持つオブジェクト	Record<string, number>
Exclude<U, E>	ユニオンから型を除外する	Exclude<Status, "deleted">
Extract<U, E>	ユニオンから型を抽出する	Extract<Event, { type: "click" }>
NonNullable<T>	null／undefined を除外する	NonNullable<string | null>
ReturnType<F>	関数の戻り値の型	ReturnType<typeof fetchUser>
Parameters<F>	関数の引数をタプルとして取得する	Parameters<typeof createUser>
Awaited<T>	Promise 型をアンラップする	Awaited<Promise<User>> = User

ジェネリクスのパターン

制約付きジェネリクス

// Basic constraint
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
    return obj[key];
}

// Multiple constraints
function merge<T extends object, U extends object>(a: T, b: U): T & U {
    return { ...a, ...b };
}

// Default generic type
type ApiResponse<T = unknown> = {
    data: T;
    status: number;
};

条件型

// Basic conditional
type IsString<T> = T extends string ? true : false;

// infer keyword - extract inner type
type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
type UnwrapArray<T> = T extends (infer U)[] ? U : T;

// Distributive conditional (distributes over union)
type ToArray<T> = T extends any ? T[] : never;
// ToArray<string | number> = string[] | number[]

// Prevent distribution with wrapping
type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;
// ToArrayNonDist<string | number> = (string | number)[]

マップ型

// Make all properties optional and nullable
type Nullable<T> = { [K in keyof T]: T[K] | null };

// Add prefix to keys
type Prefixed<T, P extends string> = {
    [K in keyof T as `${P}${Capitalize<string & K>}`]: T[K];
};
// Prefixed<{ name: string }, "get"> = { getName: string }

// Filter keys by value type
type StringKeys<T> = {
    [K in keyof T as T[K] extends string ? K : never]: T[K];
};

詳しく学ぶ： 高度な型レベルプログラミング、再帰型、テンプレートリテラル型については、./references/generics-patterns.md を読み込んでください。

最新の言語機能（TypeScript 5.x → 6.0）

機能	バージョン	利点
satisfies 演算子	4.9	型を拡大せずに、値が型に適合するかを確認する
標準（TC39）デコレーター	5.0	experimentalDecorators を使わずに、クラス／メソッドに @decorator を適用する
const 型パラメーター	5.0	function f<const T>(x: T) により、呼び出し側で as const を使わずにリテラル型を推論する
using 宣言	5.2	明示的なリソース管理（Symbol.dispose）を行い、スコープ終了時に自動クリーンアップする
推論される型述語	5.5	arr.filter(x => x !== null) により、手書きの x is T ガードなしで型を絞り込む
verbatimModuleSyntax	5.0	型のみのインポートには import type を必須にする — importsNotUsedAsValues を置き換える

// const type parameters (5.0) - literal inference without as const
function routes<const T extends readonly string[]>(paths: T): T { return paths; }
const r = routes(["/home", "/about"]); // readonly ["/home", "/about"], not string[]

// using declarations (5.2) - deterministic cleanup
function readConfig() {
    using file = openFile("config.json"); // file[Symbol.dispose]() runs at scope exit
    return parse(file.contents);
}

// Inferred type predicates (5.5) - no manual guard needed
const names = ["a", null, "b"].filter(x => x !== null); // string[], not (string | null)[]

TypeScript 6.0（橋渡しのリリース）

TS 6.0 は JavaScript ベースのコンパイラーを使う最後のリリースです。TS 7 のネイティブ（Go）コンパイラーへの橋渡しを目的としているため、主な変更点は、より厳格で最新化されたデフォルト設定です。

• strict: true がデフォルトになります — これまで設定されていなかった tsconfig でも、完全な厳密チェックが有効になります
• デフォルト設定を最新化：module: esnext、target: es2025。es2025 lib には Temporal、Map.getOrInsert、RegExp.escape の型が含まれます
• レガシーオプションを削除：moduleResolution: classic、module: amd/umd/system/none。最小の target は ES2015 になり（es5 は非推奨）、これより古い設定は使えません
• 相互運用性を常に有効化：esModuleInterop／allowSyntheticDefaultImports を無効にできなくなります
• 新しい --stableTypeOrdering フラグにより、6.0 から 7.0 への移行時の差分比較が容易になります

TypeScript 7（現行メジャーバージョン — ネイティブコンパイラー）

TS 7 は Go ネイティブの書き直し版（以前の名称は tsgo）で、2026-07-08 から npm で安定版として提供されています。 型チェックの動作は同じで、型チェックは約 8～16 倍高速です。ただし、パッケージに含まれるのは bin/tsc の shim のみで、JavaScript コンパイラー API はありません。7.0.x では require('typescript') を実行すると MODULE_NOT_FOUND がスローされます（API は 7.1 以降で復活します）。採用の妨げとなる影響は次のとおりです。

• TS のプログラマティック API（ts.createSourceFile、カスタム lint スクリプト、codemod、typescript-eslint）を使うリポジトリのツールでは、AST を使わない方式に移行するか、パーサーを切り替えるか、エイリアスを固定する必要があります
• 埋め込み言語を型チェックするツール（vue-tsc、svelte-check、Astro、MDX）は、7.1 以降の API に移植されるまで TS 6 に固定されています。これは実際のスタック選定に影響する要素です
• すでに TS 6 を使っている tsconfig は、そのまま採用できます（6.0 のブリッジは省略可能です）。baseUrl は重大なエラーになります（TS5102）
• 移行期間中に typescript5 フォールバックのエイリアスと 7 を併用すると、単独の npx tsc が曖昧になります。スクリプトではコンパイラーのパスを明示する必要があります

詳細：./references/ts7-native-compiler.md を読み込み、JavaScript API がない場合の回避策、2 つ同時にインストールした場合の bin の曖昧さ、エコシステムの利用不可状況の表、採用ベンチマークの実測値（12.1 倍）、採用可否チェックリストを確認してください。

tsconfig クイックリファレンス

{
    "compilerOptions": {
        // Strict mode (default in TS 6; state it explicitly anyway)
        "strict": true,               // Enables all strict checks
        "noUncheckedIndexedAccess": true,  // arr[0] is T | undefined

        // Module system (TS 6 defaults to module: esnext; interop is always on)
        "module": "esnext",           // or "nodenext" for Node
        "moduleResolution": "bundler", // or "nodenext"

        // Output (TS 6 defaults target to es2025; min supported is es2015)
        "target": "es2022",
        "outDir": "dist",
        "declaration": true,          // Generate .d.ts
        "sourceMap": true,

        // Paths — tsconfig-relative; don't add baseUrl (TS 7 hard-errors on it, TS5102)
        "paths": { "@/*": ["./src/*"] },

        // Strictness extras
        "noUnusedLocals": true,
        "noUnusedParameters": true,
        "noFallthroughCasesInSwitch": true,
        "forceConsistentCasingInFileNames": true
    },
    "include": ["src"],
    "exclude": ["node_modules", "dist"]
}

詳細：./references/config-strict.md を読み込み、strict モードへの移行、モノレポの設定、プロジェクト参照を確認してください。

よくある落とし穴

落とし穴	理由	対処法
any の漏出	any は、それが関わるすべての型チェックを無効にします	代わりに unknown と絞り込みを使います
as によるアサーションがバグを隠す	アサーションは実行時にチェックされません	型ガードまたはバリデーション（Zod）を使います
enum の癖	数値 enum は型安全ではなく、逆マッピングが混乱の原因になります	as const オブジェクトまたは文字列リテラルのユニオンを使います
object と Record と {} の違い	{} は null 以外の値に一致し、object はプリミティブではない値を表します	「任意のオブジェクト」には Record<string, unknown> を使います
配列インデックスへのアクセス	デフォルトでは arr[999] は T | undefined ではなく T を返します	noUncheckedIndexedAccess を有効にします
オプショナルと undefined の違い	{ x?: string } ではキーを省略できますが、{ x: string | undefined } ではキーが必須です	どちらを意図するのか明示します
! による非 null アサーション	null チェックを無効にしますが、実行時の効果はありません	?? defaultValue または適切な null チェックを使います
構造的型付けの意外な挙動	{ a: 1, b: 2 } は { a: number } に代入できます	名目的型付けにはブランド型を使います

ブランド型／名目的型

// Prevent accidentally mixing types that are structurally identical
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function createUserId(id: string): UserId { return id as UserId; }

function getUser(id: UserId) { /* ... */ }

const userId = createUserId("u-123");
const orderId = "o-456" as OrderId;

getUser(userId);   // OK
getUser(orderId);  // Error: OrderId not assignable to UserId

実行時バリデーション（Zod 4）

import { z } from "zod";

// Define schema (Zod 4: string formats are top-level - z.email(), not z.string().email())
const UserSchema = z.object({
    id: z.number(),
    name: z.string().min(1),
    email: z.email(),
    role: z.enum(["admin", "user"]),
    settings: z.object({
        theme: z.enum(["light", "dark"]).default("light"),
    }).optional(),
});

// Infer type from schema
type User = z.infer<typeof UserSchema>;

// Validate
const user = UserSchema.parse(untrustedData);       // throws on invalid
const result = UserSchema.safeParse(untrustedData);  // returns { success, data/error }

知っておきたい Zod 4 の変更点（Zod 3 を学んだ方へ）：文字列フォーマットはトップレベルに移動しました（z.email()、z.uuid()、z.url()。z.string().email() のメソッド形式は非推奨です）。エラーのカスタマイズは単一の error パラメーターに統一されました（invalid_type_error／required_error は廃止）。解析は大幅に高速化され、ツリーシェイク可能な zod/mini エントリーポイントが追加されました。

リファレンスファイル

詳細なトピックについては、以下を読み込んでください。各ファイルは単独で利用できます。

リファレンス	読み込むタイミング
./references/type-system.md	高度な型、ブランド型、型レベルプログラミング、satisfies 演算子
./references/generics-patterns.md	ジェネリック制約、条件型、マップ型、テンプレートリテラル、再帰型
./references/utility-types.md	すべての組み込みユーティリティ型と使用例、カスタムユーティリティ型
./references/config-strict.md	tsconfig の詳細、strict モードへの移行、プロジェクト参照、モノレポの設定
./references/ts7-native-compiler.md	TS 7 ネイティブ（Go）コンパイラーの採用：JavaScript API がない場合、bin の曖昧さ、エコシステムの利用不可状況、ベンチマークに基づく採用可否判断
./references/ecosystem.md	Zod／Valibot、型安全な API クライアント、ORM の型、Vitest を使ったテスト

関連項目

• testing-ops - 複数言語にまたがるテスト戦略
• ci-cd-ops - TypeScript の CI パイプライン、CI での型チェック