2nd/10_Wiki/Topics/Architecture/readonly.md

---
id: wiki-2026-0508-readonly
title: TypeScript readonly
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [readonly, Readonly<T>, ReadonlyArray, as const]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [typescript, immutability, types]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: typescript
---

# TypeScript readonly

## 매 한 줄
> **"매 compile-time 매 immutability marker — runtime enforcement 의 X"**. 매 TS 의 의 의 mutation prevention 의 의 매 type-system level — `readonly` keyword, `Readonly<T>`, `ReadonlyArray<T>`, `as const` 매 4 가지 form. 매 runtime freeze 가 의 매 `Object.freeze` 의 의.

## 매 핵심

### 매 4 가지 form
- **Property modifier**: `interface User { readonly id: string }` — assign once.
- **Mapped type**: `Readonly<T>` — all props readonly (shallow).
- **Array variants**: `readonly T[]` 또는 `ReadonlyArray<T>` — no `.push`, `.pop`, etc.
- **`as const`**: literal narrowing + deep readonly tuple/object literal.

### 매 핵심 행동
- 매 compile-time only — JS runtime 의 의 effect 의 X.
- Variance: `T[]` is assignable to `readonly T[]` (covariant), but not vice-versa.
- Shallow: `Readonly<{ a: { b: 1 } }>` 매 a is readonly, a.b 의 X.

### 매 응용
1. Public API: function param 매 `readonly T[]` — caller 의 mutation 의 의 의 의.
2. Redux / Zustand state — 매 immutability invariant.
3. Config object — `as const` 매 literal type.
4. Tuple destructuring — `const point = [1, 2] as const`.
5. Discriminated union literals — `type Status = "ok" | "fail"` via `as const`.

## 💻 패턴

### Property `readonly`
```ts
interface User { readonly id: string; name: string }
const u: User = { id: "1", name: "A" };
u.name = "B";   // OK
u.id = "2";     // Error: cannot assign to 'id' because it is a read-only
```

### `Readonly<T>` mapped
```ts
type Frozen<T> = Readonly<T>;
const cfg: Frozen<{ host: string; port: number }> = { host: "x", port: 80 };
cfg.host = "y"; // Error
```

### Deep readonly
```ts
type DeepReadonly<T> = {
  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
};

const data: DeepReadonly<{ user: { id: number } }> = { user: { id: 1 } };
data.user.id = 2; // Error
```

### `readonly T[]` in API
```ts
function sum(xs: readonly number[]): number {
  // xs.push(1); // Error
  return xs.reduce((a, b) => a + b, 0);
}
sum([1, 2, 3]);                  // OK
sum(new Array(3).fill(0));       // OK
```

### `as const` (literal narrowing)
```ts
const ROLES = ["admin", "user", "guest"] as const;
type Role = typeof ROLES[number]; // "admin" | "user" | "guest"

const config = { host: "localhost", port: 80 } as const;
// type: { readonly host: "localhost"; readonly port: 80 }
```

### Tuple as const
```ts
function point() { return [1, 2] as const; } // [1, 2] 매 readonly tuple
const [x, y] = point();
```

### Combine with branded type
```ts
type ImmutableUser = Readonly<{ id: string & { __brand: "UserId" }; email: string }>;
```

### Runtime + type (Object.freeze + as const)
```ts
function deepFreeze<T>(o: T): Readonly<T> {
  Object.freeze(o);
  for (const k of Object.keys(o as object) as (keyof T)[]) {
    const v = o[k];
    if (v && typeof v === "object" && !Object.isFrozen(v)) deepFreeze(v);
  }
  return o;
}
const FROZEN = deepFreeze({ a: { b: 1 } });
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Public function param | `readonly T[]` |
| Config / constants | `as const` |
| Class field 매 once-set | `readonly` modifier |
| Runtime guarantee 필요 | `Object.freeze` (or Immer) |
| Deep immutability type | Custom `DeepReadonly<T>` |

**기본값**: 매 input param 매 `readonly`, 매 constants 매 `as const`. 매 runtime needed 시 Immer.

## 🔗 Graph
- 부모: [[TypeScript]] · [[Immutability]]
- 응용: [[Redux Toolkit]] · [[Zustand]] · [[Type-Level Programming]]
- Adjacent: [[Branded Types]] · [[Discriminated_Unions|Discriminated Unions]] · [[Variance]] · [[Mapped Types]]

## 🤖 LLM 활용
**언제**: API design (input param immutability), config typing, state management types.
**언제 X**: Runtime tamper-proof 필요 (use freeze), JS-only project.

## ❌ 안티패턴
- **`readonly` 가 deep 일 거라 가정**: 매 shallow only — `DeepReadonly` 사용.
- **`as` cast 으로 우회**: 매 escape hatch — type system 의 매 무용.
- **`Readonly<T>` + `ReadonlyArray<T>` 혼동**: object vs array, Mapped vs interface.
- **Mutating returned `readonly` array (via `as`)**: 매 compile pass 의 매 runtime corruption.
- **Class field `readonly` 의 매 setter 통한 mutation**: 매 readonly 가 매 init time 만.
- **Public API 매 `T[]` (mutable)**: 매 caller 의 의 mutation 가능 — 항상 `readonly T[]` 권장.

## 🧪 검증 / 중복
- Verified (TypeScript handbook, TC39 records & tuples proposal, MS TypeScript blog).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — readonly forms, as const, DeepReadonly pattern |