TypeScriptのreadonly: プロパティ、Readonly<T>、配列

readonly は、オブジェクトを作るときに一度だけ設定でき、再代入できないプロパティを示します。Readonly<T> はそれを型のすべてのプロパティに適用し、readonly T[] は配列に同じことをします:

interface Point {
  readonly x: number;
  readonly y: number;
}

const origin: Point = { x: 0, y: 0 };
// @ts-expect-error: Cannot assign to 'x' because it is a read-only property
origin.x = 5;

const config: Readonly<{ host: string; port: number }> = { host: "localhost", port: 8080 };
const ports: readonly number[] = [80, 443];

console.log(config.host, ports.length); // localhost 2
console.log(origin);                    // { x: 5, y: 0 }

最後の行は、readonly についていちばん大事な事実を示しています。コンパイラーがチェックするもので、実行時に強制されるものではありません。代入はコンパイルエラーでした（ここでは @ts-expect-error で抑えています）が、出力されたJavaScriptはそれでも実行しました。抑制がなければファイルはコンパイルできず、readonly が役目を果たすのはそこです。

readonly プロパティ

インターフェース、型リテラル、クラスで、プロパティ名の前に readonly を付けます。プロパティは初期化できますが、再代入はできません:

class Invoice {
  readonly id: string;
  readonly createdAt = "2024-03-15";
  total = 0;

  constructor(id: string) {
    this.id = id; // allowed: the constructor may initialize readonly fields
  }

  add(amount: number) {
    this.total += amount; // fine: total is not readonly
    // this.id = "x" would be error TS2540: Cannot assign to 'id' because it is a read-only property.
  }
}

const inv = new Invoice("INV-7");
inv.add(19.5);
console.log(inv); // Invoice { id: 'INV-7', createdAt: '2024-03-15', total: 19.5 }

クラスでは、readonly のフィールドは宣言時かコンストラクターの中でだけ代入でき、それ以外の場所ではできません。いちばん短い書き方はパラメータープロパティ constructor(readonly id: string) {} で、フィールドの宣言と代入を一度に行います。フィールドとコンストラクター全般については クラスのページ で扱っています。

Readonly<T>: すべてのプロパティを一度に

Readonly<T> は、T のすべてのプロパティを readonly にするユーティリティ型です。アプリケーションの状態のように、受け渡しはするが変更してはいけない値に便利です:

interface State {
  user: string;
  cart: string[];
  total: number;
}

function addItem(state: Readonly<State>, item: string, price: number): State {
  // state.total += price would be error TS2540
  return { ...state, cart: [...state.cart, item], total: state.total + price };
}

const s0: State = { user: "ada", cart: [], total: 0 };
const s1 = addItem(s0, "book", 12);
const s2 = addItem(s1, "pen", 2);

console.log(s0.cart, s2); // [] { user: 'ada', cart: [ 'book', 'pen' ], total: 14 }

関数のシグネチャが、addItem は古い状態を変更するのではなく新しい状態を返すことを読む人に伝え、コンパイラーは関数にその約束を守らせます。Readonly<T> はマップ型 { readonly [P in keyof T]: T[P] } として定義されています。

readonly 配列: readonly T[] と ReadonlyArray<T>

readonly number[] と ReadonlyArray<number> は同じ型です。変更するメソッド（push、pop、shift、splice、sort、reverse、fill など）をすべて取り除き、インデックスへの代入を禁止します。変更しないメソッドは残り、普通の配列を返します:

const scores: readonly number[] = [42, 7, 19];

const doubled = scores.map((s) => s * 2);        // number[] (a new, mutable array)
const sorted = [...scores].sort((a, b) => a - b); // copy first, then sort the copy
const top = scores.slice(0, 2);

// @ts-expect-error: Property 'push' does not exist on type 'readonly number[]'
scores.push(1);

console.log(doubled, sorted, top); // [ 84, 14, 38 ] [ 7, 19, 42 ] [ 42, 7 ]
console.log(scores);               // [ 42, 7, 19, 1 ]  (push ran: types are erased)

引数として readonly T[] を受け取ることは、呼び出し側の配列を変更しないという約束です。つまずきやすいのは逆方向です。readonly 配列は、普通の T[] を受け取る関数には渡せません。その関数が配列を変更するかもしれないからです。

// This does not compile: a readonly array cannot go where a mutable one is expected
function sum(values: number[]): number {
  return values.reduce((a, b) => a + b, 0);
}

const prices: readonly number[] = [3, 4, 5];
console.log(sum(prices));

index.ts(7,17): error TS4104: The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.

sum は何も変更しないので、readonly number[] を受け取るように変えれば直ります。配列を読むだけの関数は常に readonly の型を受け取るようにしましょう。そうすれば両方の種類を受け付けられます。自分が管理していない関数なら、コピーを渡します: sum([...prices])。

ReadonlyMap と ReadonlySet

Map と Set にも readonly 版があります。ReadonlyMap<K, V> は get、has、size、forEach とイテレーターを持ちますが、set、delete、clear はありません。ReadonlySet<T> には add、delete、clear がありません:

const prices: ReadonlyMap<string, number> = new Map([
  ["tea", 2.5],
  ["coffee", 3.2],
]);
const admins: ReadonlySet<string> = new Set(["ada"]);

console.log(prices.get("tea"), prices.size, admins.has("ada")); // 2.5 2 true

// @ts-expect-error: Property 'set' does not exist on type 'ReadonlyMap<string, number>'
prices.set("juice", 4);

クラスは、private な変更可能な Map を持ち、ReadonlyMap と型付けした getter で公開することがよくあります。外のコードはデータを読めますが、その参照を通して変更することはできません。

readonly は浅い

readonly と Readonly<T> が守るのはプロパティそのものだけで、それが指すオブジェクトや配列は守りません:

interface Team {
  readonly name: string;
  readonly members: string[];
  readonly lead: { name: string };
}

const team: Readonly<Team> = { name: "Core", members: ["ada"], lead: { name: "ada" } };

team.members.push("linus"); // allowed: the array itself is not readonly
team.lead.name = "linus";   // allowed: only the lead property is readonly
// team.members = [] would be error TS2540

console.log(team); // { name: 'Core', members: [ 'ada', 'linus' ], lead: { name: 'linus' } }

type DeepReadonly<T> = T extends (...args: any[]) => unknown ? T
  : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
  : T;

const frozenTeam: DeepReadonly<Team> = team;
// @ts-expect-error: Property 'push' does not exist on type 'readonly string[]'
frozenTeam.members.push("grace");

DeepReadonly<T> はネストしたすべてのオブジェクト型に自分自身を適用し、配列の型に対するマップ型は readonly 配列を作るので、members は readonly string[] になります。それでもこれは型のレベルの約束で、実行時の保護ではありません。

コンパイル時だけ: 別の参照を通した変更

readonly の型が制御するのは、1つの参照ができることです。同じオブジェクトへの、readonly なしで型付けされた別の参照からは変更でき、TypeScriptは readonly の型を変更可能な型に代入することさえ許します:

interface Settings {
  readonly theme: string;
}

const settings: Settings = { theme: "dark" };
const mutable: { theme: string } = settings; // allowed, no error
mutable.theme = "light";

console.log(settings.theme); // light

// Runtime protection needs Object.freeze
const locked = Object.freeze({ theme: "dark" }); // typed Readonly<{ theme: "dark" }>
try {
  (locked as { theme: string }).theme = "light";
} catch (e) {
  console.log((e as Error).name); // TypeError
}
console.log(locked.theme); // dark

mutable = settings という代入がコンパイルできるのは、2つのオブジェクト型が互換かをチェックするとき、TypeScriptが readonly プロパティを考慮しないからです。TypeScriptのハンドブックはこのことをはっきり書いていて、そのため readonly プロパティは別名を通して変わりうると注意しています。readonly 配列は違います。上の TS4104 エラーがまさにそのチェックです。Object.freeze は実行時の変更を本当に防ぎます。出力されるコードは strict モードで動き、凍結されたプロパティに書き込むと TypeError が投げられます。readonly と同じく、Object.freeze も浅いものです。

readonly、const、as const、Object.freeze

リテラルに as const を付けると、すべての階層ですべてのプロパティが readonly になり、リテラル型も保たれます。深く readonly な値を得るいちばん簡単な方法であることが多いです:

const theme = { mode: "dark", sizes: [12, 14] } as const;
// { readonly mode: "dark"; readonly sizes: readonly [12, 14] }

const と readonly は別の疑問に答えます。const は名前が別のものを指すのを止め、readonly はプロパティが変わるのを止めます。const のオブジェクトのプロパティも、readonly でなければ再代入できます。