05.1 形が同じなら同じ型として通る

名前は見ていない

TypeScript は型の名前を見ません。持っているプロパティの形だけを見ます。

type User = { name: string };
type Animal = { name: string };

const a: User = { name: "Alice" };
const b: Animal = a;              // 通る。形が同じだから

User と Animal はまったく別の意図で作った型ですが、形が同じなので互換です。

多い分には構わない

判定の基準は「受け取る側が要求するものを、渡す側が持っているか」です。余分に持っていても通ります。

type Named = { name: string };

const user = { name: "Alice", age: 30, email: "a@example.com" };
const n: Named = user;            // 通る。name を持っているから

関数も形で判定される

type Handler = (x: number) => void;

const f: Handler = (x) => console.log(x);          // OK
const g: Handler = () => console.log("hi");        // OK — 引数を使わなくてよい
const h: Handler = (x: number, y: number) => {};   // エラー — 引数が多い

引数は少ない分には構いません。JavaScript では、渡された引数を使わない関数は普通に書けるためです（[1,2,3].map(x => x * 2) のように、map が渡す2つ目・3つ目の引数を無視できます）。この扱いは 07. 関数の型 で詳しく見ます。

05.2 余剰プロパティチェック

直接書いたときだけ厳しくなる

前の節で「余分に持っていても通る」と書きましたが、例外があります。

type User = { name: string };

// ① 変数を経由する → 通る
const obj = { name: "Alice", age: 30 };
const a: User = obj;

// ② オブジェクトリテラルを直接書く → エラー
const b: User = { name: "Alice", age: 30 };
//                               ~~~~~~~
// error TS2353: Object literal may only specify known properties,
//               and 'age' does not exist in type 'User'.
//
// 訳: オブジェクト リテラルは既知のプロパティのみ指定できます。
//     'age' は型 'User' に存在しません。

同じ形なのに、①は通り、②はエラーになります。これが余剰プロパティチェックです。

なぜこの仕様があるか

意図的に余分な値を渡したいとき

type User = { name: string };

// ① 変数に入れてから渡す（最も素直）
const payload = { name: "Alice", age: 30 };
const a: User = payload;

// ② 型を union にする
type UserWithExtra = User & { age?: number };

// ③ インデックスシグネチャを足す
type Loose = { name: string; [key: string]: unknown };

as User で黙らせることもできますが、打ち間違いも一緒に通してしまいます（06）。

05.3 クラスも形で判定される

implements を書かなくても互換

interface Logger {
	log(message: string): void;
}

// implements を書いていない
class ConsoleLogger {
	log(message: string) {
		console.log(message);
	}
}

const l: Logger = new ConsoleLogger();     // 通る

class ConsoleLogger implements Logger {   // 書いておくと、ここで守られる
	log(message: string) { console.log(message); }
}

private があると形が変わる

クラスに private なメンバーがあると、同じ形でも互換になりません。

class A { private secret = 1; }
class B { private secret = 1; }

let a: A = new A();
let b: B = new B();
a = b;
//  ~
// error TS2322: Type 'B' is not assignable to type 'A'.
//   Types have separate declarations of a private property 'secret'.
//
// 訳: 型 'B' を型 'A' に割り当てることはできません。
//     プライベート プロパティ 'secret' の宣言が別々です。

private なメンバーは「そのクラスで宣言されたもの」として区別されます。これが、TypeScript で名前的な区別に最も近い挙動です。

05.4 意図的に区別する — ブランド型

形が同じだと混ざる

構造的型付けの弱点は、意味が違うのに形が同じ値を取り違えられることです。

type UserId = string;
type OrderId = string;

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

const orderId: OrderId = "order-123";
getUser(orderId);            // 通ってしまう。どちらも string だから

ブランド型で区別する

実体のないプロパティを足して、形を意図的にずらします。

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

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

const orderId = "order-123" as OrderId;
getUser(orderId);
//      ~~~~~~~
// error TS2345: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.
//
// 訳: 型 'OrderId' の引数を型 'UserId' のパラメーターに割り当てることはできません。

生成関数と組み合わせる

as を書く場所を1か所に閉じ込めると、検証も一緒に行えます。

// branded.ts
type UserId = string & { readonly __brand: "UserId" };

function toUserId(s: string): UserId {
	if (!s.startsWith("user-")) {
		throw new Error(`UserId の形式が不正です: ${s}`);
	}
	return s as UserId;
}

const id = toUserId("user-001");
console.log(id);

try {
	toUserId("order-123");
} catch (e) {
	console.log((e as Error).message);
}

$ npx tsx branded.ts
user-001
UserId の形式が不正です: order-123

この形は A2. 型レシピ集 にも収めています。