TypeScriptの交差型（&）: 型を組み合わせる

A & B と書く交差型は、A であると同時に B でもある値を表します。オブジェクト型なら、値は両方のプロパティをすべて持つということです。プロパティを書き直さずに既存の型を組み合わせる方法です。

type Person = { name: string; email: string };
type Employee = { employeeId: number; team: string };

type Staff = Person & Employee; // has all four properties

const ada: Staff = { name: "Ada", email: "ada@example.com", employeeId: 7, team: "compilers" };

function badge(s: Staff): string {
  return `${s.name} (#${s.employeeId}, ${s.team})`;
}

console.log(badge(ada)); // Ada (#7, compilers)

// @ts-expect-error: Type '{ name: string; email: string; employeeId: number; }' is not assignable to type 'Staff'.
const partial: Staff = { name: "Alan", email: "alan@example.com", employeeId: 8 };

2つ目のオブジェクトは team を省いているので、コンパイルエラー TS2322 になり、メッセージの次の行には Property 'team' is missing ... but required in type 'Employee' と書かれています。Staff の値は、Person や Employee が期待される場所ならどこにでも渡せます。

オブジェクト型を組み合わせる

& は、型エイリアス、インターフェース、インラインのオブジェクト型をどう混ぜても使え、ジェネリクスの型パラメーターにも使えます。置き換えが難しいのはこの最後のケースです。受け取ったオブジェクトが何であれプロパティを追加する関数を、正確に表現できます。

function withMeta<T extends object>(obj: T, author: string): T & { author: string; savedAt: string } {
  return { ...obj, author, savedAt: "2024-03-15T10:30:00.000Z" };
}

const note = withMeta({ title: "Draft", words: 120 }, "ada");
// type: { title: string; words: number } & { author: string; savedAt: string }

console.log(note.title, note.words, note.author); // Draft 120 ada
console.log(note.savedAt);                         // 2024-03-15T10:30:00.000Z

呼び出し側は、渡したものの正確な型（title、words）に、追加された2つのプロパティを加えた型を受け取ります。インターフェースは型パラメーターを拡張できないので、interface ... extends では「T が何であれ、それにこれらを加えたもの」を表現できません。

衝突するプロパティは never になる

両側が同じプロパティを宣言していると、そのプロパティの型は2つの型の交差型になります。その2つの型に共通の値がなければ、プロパティは never になり、値を作ろうとするまでコンパイラーは何も言いません:

// This does not compile: id cannot be a string and a number at once
type WithStringId = { id: string; name: string };
type WithNumberId = { id: number };

type Account = WithStringId & WithNumberId; // no error on this line

const r: Account = { id: "u1", name: "Ada" };
console.log(r);

index.ts(7,22): error TS2322: Type 'string' is not assignable to type 'never'.

エラーは原因となった型ではなくオブジェクトを指すので、この種のバグは原因をたどるのに時間がかかります。エディターで r.id にカーソルを合わせると、型が never だとわかります。type Shape = { kind: "circle" } & { kind: "square" } のように衝突するプロパティがリテラルのタグなら、TypeScriptはさらに進んで交差型全体を never に縮約します。そうした値のプロパティを読むと、理由が説明されます: Property 'kind' does not exist on type 'never'. The intersection 'Shape' was reduced to 'never' because property 'kind' has conflicting types in some constituents.

interface ... extends なら、同じ衝突を宣言の位置でエラー TS2430 として捕まえます。これが2つの主な実用上の違いで、interface と type のページで並べて比較しています。

重なりがあればプロパティが狭まる

2つのプロパティの型に重なりがあれば、結果はその重なりになります。これはエラーではなく、便利な性質です:

type Editable = { id: string | number; tags: string[] };
type Stored = { id: string; createdAt: string };

type Doc = Editable & Stored; // id: (string | number) & string, which is string

const doc: Doc = { id: "d1", tags: ["draft"], createdAt: "2024-03-15" };
console.log(doc.id.toUpperCase()); // D1: id is a string, so string methods are allowed

type Letters = "a" | "b" | "c";
type Later = "b" | "c" | "d";
type Both = Letters & Later; // "b" | "c": what the two unions have in common

const shared: Both[] = ["b", "c"];
console.log(shared); // [ 'b', 'c' ]

後半は、& がユニオン型に何をするかを示しています。両側に共通するメンバーを残します。型を値の集合として考えると、これは予想どおりの結果です。A | B は2つの集合の和集合、A & B はその共通部分で、何もない共通部分が never です。

交差型とユニオン型

名前は集合論から来ていて、オブジェクトのプロパティに当てはめると逆に感じられます:

オブジェクト型の交差型がより多くのプロパティを持つのは、まさに許す値が少ないから、つまりすべてを持つオブジェクトだけを許すからです。

交差型と extends

いくつかのオブジェクト型のエイリアスを組み合わせるなら、& が慣用的で問題ありません。多くの部品から作る型や公開APIの型なら、extends のほうがエラーが早く出て、型チェックも軽くなります。

プリミティブとの交差型: ブランド化

プリミティブとオブジェクト型の交差型は never になりません。string & { readonly __brand: "UserId" } は、コンパイル時だけの目印を追加で持つ文字列です。本物の文字列はそのプロパティを持たず、それこそが狙いです。ブランドを意図的にアサーションするコードだけがそれを作れるので、UserId が期待される場所に普通の string や OrderId を渡せなくなります。この手法には専用のページがあります: ブランド型。