TypeScriptの型エイリアス（type）: 使い方と例

型エイリアスは型に名前を付けます。type Name = ... と書くと、それ以降、型が期待される場所ならどこでも Name を使えます。インターフェースと違い、エイリアスはオブジェクトの形だけでなく、どんな型にも名前を付けられます。

type UserId = string;                         // a primitive
type Point = { x: number; y: number };        // an object shape
type Status = "active" | "banned";            // a union of literals
type Pair = [string, number];                 // a tuple
type Formatter = (value: number) => string;   // a function

const id: UserId = "u_42";
const start: Point = { x: 0, y: 0 };
const current: Status = "active";
const entry: Pair = ["score", 90];
const money: Formatter = (v) => `$${v.toFixed(2)}`;

console.log(id, start, current, entry, money(3.5));
// u_42 { x: 0, y: 0 } active [ 'score', 90 ] $3.50

エイリアスはコンパイル時にしか存在しません。出力されるJavaScriptには、これらの type の行は1つも含まれません。

構文

type Name = SomeType;
type Name<T> = SomeTypeUsing<T>;       // generic
export type Name = SomeType;           // exported from a module

名前は慣習では PascalCase です。右辺はどんな型の式でもよく、エイリアスはほかのエイリアスや自分自身も使えます（下の再帰的な型を参照）。型はコンパイル時にチェックされ、const や let のように順番に実行されるわけではないので、エイリアスは宣言の行より上も含め、宣言されたスコープ全体で使えます。

オブジェクト型

オブジェクトの形なら、エイリアスとインターフェースはほとんど同じように書きます。エイリアスは = を使い、ふつうはセミコロンで終えます。

type User = {
  id: number;
  name: string;
  email?: string;           // optional
  readonly createdAt: string; // cannot be reassigned
};

type Admin = User & { permissions: string[] }; // extend with an intersection

const root: Admin = {
  id: 1,
  name: "root",
  createdAt: "2024-03-15",
  permissions: ["*"],
};

console.log(`${root.name} can do ${root.permissions.join(", ")}`); // root can do *

エイリアスでは extends を使えず、交差型 & がその役割を果たします。余分なプロパティのチェック、省略可能なプロパティと readonly プロパティは、インターフェースとまったく同じように動きます。オブジェクトの形にどちらを選ぶかは、interface と type のページで扱います。

ユニオン型、タプル、関数

これらはエイリアスでしか名前を付けられないもので、type が存在する主な理由です。ユニオン型のエイリアスは選択肢を並べ、タプルのエイリアスは配列の長さと要素の型を固定し、関数のエイリアスはシグネチャを表します。

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number };

type Span = [start: number, end: number]; // labeled tuple elements

type Transform = (shape: Shape, factor: number) => Shape;

const scale: Transform = (shape, factor) =>
  shape.kind === "circle"
    ? { kind: "circle", radius: shape.radius * factor }
    : { kind: "rect", width: shape.width * factor, height: shape.height * factor };

const r: Span = [10, 20];
console.log(scale({ kind: "circle", radius: 2 }, 3)); // { kind: 'circle', radius: 6 }
console.log(r[1] - r[0]);                              // 10

scale の引数には型注釈が要りません。Transform エイリアスが型を与えています。タプルの構文は タプル で、ユニオン型の絞り込みはユニオン型のページで説明しています。

ジェネリックな型エイリアス

型パラメーターを使うと、1つのエイリアスがさまざまな型に対応します。関数の引数と同じく、デフォルトを持てます。

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0
    ? { ok: true, value: n }
    : { ok: false, error: `not an age: ${text}` };
}

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? `age ${r.value}` : r.error);
}
// age 36
// not an age: abc

Result<number> はデフォルトの E = string を使います。type Nullable<T> = T | null や type Dict<T> = Record<string, T> のような小さなジェネリックエイリアスは、実際のコードでよく使われます。組み込みのユーティリティ型（Partial<T>、Pick<T, K>、ReturnType<F>）も、標準ライブラリで宣言されたジェネリックエイリアスです。

エイリアスは名前であって新しい型ではない

エイリアスは別個の型を作りません。右辺の型の2つ目の名前で、コンパイラーは両者を同一として扱います。string の2つのエイリアスは完全に交換可能です:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: UserId and OrderId are both just string

これはエラーなしに cancelling u_42 を出力します。エイリアスでは防げないバグです。それでもエイリアスは読む人の助けになります（OrderId と型付けされた引数は string より多くを語ります）が、2つの ID の取り違えをコンパイルエラーにしたいなら、string & { readonly __brand: "OrderId" } のようなブランド型を使いましょう。

再帰的な型エイリアス

エイリアスは自分自身を参照できます。木構造、ネストしたリスト、JSONはこの方法で表します:

type Json =
  | string
  | number
  | boolean
  | null
  | Json[]
  | { [key: string]: Json };

type TreeNode = {
  value: number;
  children: TreeNode[];
};

function sum(node: TreeNode): number {
  return node.value + node.children.reduce((total, child) => total + sum(child), 0);
}

const tree: TreeNode = {
  value: 1,
  children: [
    { value: 2, children: [] },
    { value: 3, children: [{ value: 4, children: [] }] },
  ],
};

const payload: Json = { ok: true, items: [1, "two", null], meta: { page: 1 } };

console.log(sum(tree));               // 10
console.log(JSON.stringify(payload)); // {"ok":true,"items":[1,"two",null],"meta":{"page":1}}

Json エイリアスは、JSONで表現できない値を拒否します。{ when: new Date() } や { f: undefined } を Json に代入するとコンパイルエラー（TS2322）です。

値から型を作る: typeof

値がすでにあるなら、型を書き出す代わりにその型に名前を付けられます。typeof 型演算子は変数の型を読み取り、ほかの演算子と組み合わせられます:

const defaults = { retries: 3, verbose: false, level: "info" };

type Options = typeof defaults;
// { retries: number; verbose: boolean; level: string }

type OptionKey = keyof typeof defaults;
// "retries" | "verbose" | "level"

function start(port: number) {
  return { port, startedAt: new Date() };
}
type Server = ReturnType<typeof start>;
// { port: number; startedAt: Date }

値が唯一の情報源のままになります。defaults にプロパティを追加すれば Options もそれに従います。詳しくは typeof を参照してください。

エイリアスの export と import

エイリアスは値と同じように export、import します。import type を使うと型だけをインポートすることが明示され、そのインポートは必ずJavaScriptの出力から取り除かれます:

// shapes.ts
export type Point = { x: number; y: number };
export type Shape = { kind: "circle"; center: Point; radius: number };

// main.ts
import type { Point, Shape } from "./shapes.js";

const p: Point = { x: 1, y: 2 };