TypeScriptのオブジェクト型: 省略可能・readonly プロパティ

TypeScriptのオブジェクト型は、オブジェクトが持つプロパティとそれぞれの型を並べたものです: { name: string; age: number }。プロパティを省略可能にするには ? を、再代入できないようにするには readonly を付けます。型はインラインで書くか、type や interface で名前を付けて再利用します。

// Inline object type
let point: { x: number; y: number } = { x: 3, y: 4 };

// Named object type with optional and readonly properties
type User = {
    readonly id: number;
    name: string;
    email?: string; // optional: may be missing
};

const ada: User = { id: 1, name: "Ada" };
const grace: User = { id: 2, name: "Grace", email: "grace@example.com" };

console.log(point.x + point.y);           // 7
console.log(ada.email ?? "no email");      // no email
console.log(grace.email?.toUpperCase());   // GRACE@EXAMPLE.COM

オブジェクト型の書き方

プロパティは ; か , で区切ります（どちらでもよく、; が一般的です）。改行だけでも区切れます。一度しか使わないパラメーターならインラインの型でかまいませんが、2回以上使うものには名前を付けましょう。

// Inline, in a parameter
function area(rect: { width: number; height: number }): number {
    return rect.width * rect.height;
}

// Named with a type alias
type Rect = { width: number; height: number };

// Named with an interface (the same shape)
interface RectShape {
    width: number;
    height: number;
}

type と interface はどちらもオブジェクトの形を同じように表せます。違い（宣言のマージ、ユニオン）は interface と type の違い のページで説明しています。

型が宣言していないプロパティにアクセスするとコンパイルエラーです: point.z は TS2339 Property 'z' does not exist on type '{ x: number; y: number; }'. になります。

省略可能なプロパティ

名前のあとに ? を付けると、そのプロパティは省略できるようになります。省略可能なプロパティを読むと T | undefined になるので、TypeScriptは使う前に値がない場合を処理させます。

type Profile = {
    name: string;
    nickname?: string;
    age?: number;
};

function greet(p: Profile): string {
    // p.nickname is string | undefined
    const shown = p.nickname ?? p.name;         // default with ??
    const ageText = p.age !== undefined ? ` (${p.age})` : ""; // or check
    return `Hi, ${shown}${ageText}`;
}

console.log(greet({ name: "Ada" }));                        // Hi, Ada
console.log(greet({ name: "Grace", nickname: "Amazing Grace", age: 85 }));
console.log("age" in { name: "Ada" });                      // false

チェックせずに省略可能なプロパティのメソッドを呼ぶとエラーです: p.nickname.toUpperCase() は TS18048 'p.nickname' is possibly 'undefined'. になります。結果が undefined でもかまわない場合はオプショナルチェーン（p.nickname?.toUpperCase()）を使います。

prop?: T と prop: T | undefined は同じではありません。前者はキーがなくてもよく、後者はキーが必須で、値が undefined でもかまわないという意味です:

type A = { note?: string };
type B = { note: string | undefined };

const a1: A = {};                    // fine: key left out
const b1: B = { note: undefined };   // fine: key present
// @ts-expect-error: Property 'note' is missing in type '{}' but required in type 'B'.
const b2: B = {};

console.log(a1, b1, b2); // {} { note: undefined } {}

readonly プロパティ

readonly は、オブジェクトを作ったあとでプロパティに再代入することを禁止します。これはコンパイル時だけのチェックで、しかも浅いものです。readonly プロパティに入っているオブジェクトや配列の中身は変更できます。

type Order = {
    readonly id: string;
    readonly items: string[];
    status: "open" | "paid";
};

const order: Order = { id: "A-17", items: ["tea"], status: "open" };

order.status = "paid"; // fine
// @ts-expect-error: Cannot assign to 'id' because it is a read-only property.
order.id = "B-2";
order.items.push("cake"); // allowed: readonly is shallow

console.log(order); // { id: 'B-2', items: [ 'tea', 'cake' ], status: 'paid' }

出力には両方の限界が表れています。id は実行時に本当に変わり（readonly だと知っていたのはコンパイラーだけです）、中の配列も変更されました。readonly の配列には readonly string[] を使い、すべてのプロパティを一度に readonly にするには Readonly<Order> を使います。

余剰プロパティチェック

オブジェクトリテラルを型付きの変数に直接代入したり、型付きのパラメーターにそのまま渡したりすると、TypeScriptは型が宣言していないプロパティを拒否します。新しく書いたリテラルの余分なプロパティは、ほとんどの場合タイプミスだからです。

// This does not compile: 'colour' is not a property of Options.
type Options = { color?: string; size?: number };

function draw(opts: Options) {
    console.log(opts.color ?? "black", opts.size ?? 1);
}

draw({ colour: "red", size: 2 });

index.ts(8,8): error TS2561: Object literal may only specify known properties, but 'colour' does not exist in type 'Options'. Did you mean to write 'color'?

コンパイラーが近い名前を見つけたので、エラーコードは TS2561 です。似た名前のない余分なプロパティなら TS2353 Object literal may only specify known properties, and 'z' does not exist in type 'Point'. になります。このチェックがなければタイプミスはそのままコンパイルされ、color は undefined になり、プログラムは黙って黒で描画するでしょう。チェックは新しく書いたリテラルにだけ適用されます。すでに変数に入っているオブジェクトは余分なプロパティを持っていてもかまいません。TypeScriptの型付けは構造的で、必要なプロパティを少なくとも持っていれば値は型に合うからです。

type Point = { x: number; y: number };

const point3d = { x: 1, y: 2, z: 3 };
const p: Point = point3d; // fine: point3d has x and y

function show(pt: Point) {
    console.log(pt.x, pt.y);
}
show(point3d); // 1 2

入れ子のオブジェクトとメソッド

オブジェクト型は入れ子にでき、メソッドはメソッド構文でも関数型のプロパティでも表せます。

type Company = {
    name: string;
    address: {
        city: string;
        zip?: string;
    };
    tags: string[];
    describe(): string;                  // method syntax
    rename: (newName: string) => void;   // function property
};

const acme: Company = {
    name: "Acme",
    address: { city: "Berlin" },
    tags: ["b2b"],
    describe() {
        return `${this.name} in ${this.address.city}`;
    },
    rename(newName) {
        this.name = newName;
    },
};

acme.rename("Acme GmbH");
console.log(acme.describe());               // Acme GmbH in Berlin
console.log(acme.address.zip ?? "no zip");  // no zip

type Address = Company["address"]; // reuse a nested type by indexing
const home: Address = { city: "Paris", zip: "75001" };
console.log(home);

深い形や再利用する形は、内側の型に名前を付けて（type Address = { ... }）参照するか、最後の数行のように外側の型からインデックスアクセス Company["address"] で取り出します。

object と {} と Object

似た名前の3つの型は意味が違います:

const a: object = { id: 1 };
const b: object = [1, 2];
const c: {} = 42;          // allowed: {} does not mean "empty object"
const d: {} = "text";      // allowed too

// @ts-expect-error: Type 'number' is not assignable to type 'object'.
const e: object = 42;

console.log(a, b, c, d, e);

{} は「空のオブジェクト」ではなく、「null でも undefined でもない」という意味です。キーのわからない任意のオブジェクトを受け付けるには Record<string, unknown> を使います。キーから値への対応表には、辞書のページで紹介しているインデックスシグネチャか Record を使います。たいていの場合は、3つのどれよりも具体的な形を書くほうが適しています。