TypeScriptのユーティリティ型一覧（サンプル付き）

ユーティリティ型は、ある型を別の型に変える、TypeScriptに組み込まれたジェネリックな型です。すべてのフィールドを省略可能にした2つ目の User 型を書く代わりに Partial<User> と書き、3つのフィールドをコピーする代わりに Pick<User, "id" | "name"> と書きます。グローバルなので、インポートは要りません。

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
}

type UserPatch = Partial<User>;                 // every field optional
type UserCard = Pick<User, "id" | "name">;      // only id and name
type PublicUser = Omit<User, "password">;       // everything but password
type UsersById = Record<number, PublicUser>;    // an object keyed by id

const patch: UserPatch = { email: "new@example.com" };
const card: UserCard = { id: 1, name: "Ada" };
const users: UsersById = {
  1: { id: 1, name: "Ada", email: "ada@example.com" },
};

console.log(patch, card, users[1].email);
// { email: 'new@example.com' } { id: 1, name: 'Ada' } ada@example.com

User が変われば、派生した4つの型もすべてそれに従います。TypeScriptの標準ライブラリ（lib.es5.d.ts）は22個のユーティリティ型を宣言しています。以下のセクションでは、扱う型の種類ごとにすべてを並べ、詳しいページがあるものにはリンクを付けています。

オブジェクト型: Partial、Required、Readonly、Pick、Omit、Record

interface Config {
  host: string;
  port?: number;
  debug?: boolean;
}

const defaults: Required<Omit<Config, "host">> = { port: 8080, debug: false };

function withDefaults(config: Config): Readonly<Required<Config>> {
  return { ...defaults, ...config };
}

const cfg = withDefaults({ host: "localhost", debug: true });
console.log(cfg); // { port: 8080, debug: true, host: 'localhost' }
// cfg.port = 1 would be error TS2540: Cannot assign to 'port' because it is a read-only property.

Required<T> は Partial<T> の逆です。Partial のページで両方を扱っていて、このようなスプレッドが通してしまう明示的な undefined についても説明しています。

ユニオン型: Exclude、Extract、NonNullable

type Status = "draft" | "review" | "published" | "archived";

type Live = Exclude<Status, "draft" | "archived">; // "review" | "published"
type Mixed = string | number | (() => void);
type Callable = Extract<Mixed, (...args: never[]) => unknown>; // () => void

function lookup(id: number): string | undefined {
  return id === 1 ? "Ada" : undefined;
}
type Found = NonNullable<ReturnType<typeof lookup>>; // string

const s: Live = "review";
const run: Callable = () => console.log("called");
const found: Found = lookup(1) ?? "nobody";
run();
console.log(s, found); // review Ada

この3つはオブジェクトではなくユニオン型に対して働きます。オブジェクト型とそのキーの一覧を受け取る Pick や Omit との大きな違いはそこです。

関数とクラスの型: Parameters、ReturnType など

function createOrder(customer: string, items: string[], express = false) {
  return { customer, items, express, total: items.length * 10 };
}

type OrderArgs = Parameters<typeof createOrder>; // [customer: string, items: string[], express?: boolean | undefined]
type Order = ReturnType<typeof createOrder>;     // { customer: string; items: string[]; express: boolean; total: number }

const args: OrderArgs = ["Ada", ["book", "pen"]];
const order: Order = createOrder(...args);
console.log(order.total, order.express); // 20 false

class Point {
  constructor(public x: number, public y: number) {}
}
const coords: ConstructorParameters<typeof Point> = [3, 4];
const p: InstanceType<typeof Point> = new Point(...coords);
console.log(p); // Point { x: 3, y: 4 }

これらのユーティリティは型を受け取り、createOrder は値なので、typeof createOrder が必要です。クラスも同じで、typeof Point はコンストラクターの型ですが、型としての普通の Point はすでにインスタンスの型を意味します。

NoInfer は、ジェネリクスがどこから型を得るかを制御します:

function pickColor<C extends string>(colors: C[], fallback: NoInfer<C>): C {
  return colors[0] ?? fallback;
}

console.log(pickColor(["red", "green"], "green")); // red
// @ts-expect-error: "blue" is not "red" | "green"
pickColor(["red", "green"], "blue");

NoInfer がなければ、TypeScriptは両方の引数から C を推論して "red" | "green" | "blue" に広げてしまうので、フォールバックの打ち間違いが受け入れられてしまいます。

文字列の型: Uppercase、Lowercase、Capitalize、Uncapitalize

この4つはTypeScriptで書かれているのではなくコンパイラーに組み込まれていて、イベントハンドラー名を作る `on${Capitalize<E>}` のように、テンプレートリテラル型 の中でいちばん役に立ちます。

Promise: Awaited

async function fetchUser(id: number) {
  return { id, name: "Ada" };
}

type Pending = ReturnType<typeof fetchUser>;           // Promise<{ id: number; name: string }>
type User = Awaited<ReturnType<typeof fetchUser>>;      // { id: number; name: string }

async function main() {
  const user: User = await fetchUser(1);
  const all: User[] = await Promise.all([fetchUser(2), fetchUser(3)]);
  console.log(user.name, all.map((u) => u.id)); // Ada [ 2, 3 ]
}
main();

Awaited<ReturnType<typeof fn>> は、async 関数の結果の型を別に宣言せずに名前を付ける標準的な方法です。

ユーティリティ型を組み合わせる

ユーティリティ型は入れ子にできます。覚えておく価値があるほどよく出てくる組み合わせがいくつかあります:

interface Post {
  id: number;
  title: string;
  body: string;
  tags: string[];
}

// Create: everything except the server-generated id
type NewPost = Omit<Post, "id">;
// Update: id required, everything else optional
type PostUpdate = Pick<Post, "id"> & Partial<Omit<Post, "id">>;
// A lookup table of read-only summaries
type PostIndex = Record<number, Readonly<Pick<Post, "id" | "title">>>;

const created: NewPost = { title: "Hello", body: "...", tags: [] };
const update: PostUpdate = { id: 1, title: "Hello again" };
const index: PostIndex = { 2: { id: 2, title: "Idea" } };
console.log(created.title, update, index[2]);
// Hello { id: 1, title: 'Hello again' } { id: 2, title: 'Idea' }

入れ子のユーティリティ型は内側から読みます。Readonly<Pick<Post, "id" | "title">> は、まず2つのプロパティを残し、それから読み取り専用にします。同じ部品で、一部のキーだけを省略可能にする PartialBy ヘルパーも作れます。Partial のページで書き出しています。

ユーティリティ型は実行時に何もしない

ユーティリティ型はすべて、コードのコンパイル時に消去されます。Omit<User, "password"> と型付けされた値でも、元のオブジェクトが password を持っていれば、実行時にはそれを持ったままです:

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

const full: User = { name: "Ada", password: "hunter2" };

const leaky: Omit<User, "password"> = full; // allowed: extra properties are fine
console.log(JSON.stringify(leaky)); // {"name":"Ada","password":"hunter2"}

const { password, ...safe } = full;          // this actually removes it
console.log(JSON.stringify(safe));  // {"name":"Ada"}

型が制限するのは、コードが読んでよいものだけです。データからフィールドを取り除くには最後の数行のように分割代入で取り除き、実行時に変更を止めるには Readonly ではなく Object.freeze を使いましょう。組み込みの型は1行のマップ型や条件型なので、同じ道具で自分の型も書けます。