[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -1,141 +1,153 @@
|
||||
---
|
||||
id: wiki-2026-0508-readonly
|
||||
title: readonly
|
||||
title: TypeScript readonly
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: []
|
||||
aliases: [readonly, Readonly<T>, ReadonlyArray, as const]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.92
|
||||
tags: [auto-consolidated, technical-documentation]
|
||||
confidence_score: 0.9
|
||||
verification_status: applied
|
||||
tags: [typescript, immutability, types]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-05-08
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: typescript
|
||||
---
|
||||
|
||||
# [[Readonly 유틸리티 타입|Readonly 유틸리티 타입]]
|
||||
# TypeScript readonly
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> Readonly 유틸리티 타입(`Readonly<T>`)은 TypeScript에서 특정 객체 타입의 모든 속성에 `readonly` 수식어를 추가하여 초기화 이후 값을 재할당할 수 없도록 변환하는 기능입니다[1, 2]. 이는 런타임 성능 저하 없이 컴파일 타임에만 엄격하게 불변성을 강제하여, 의도치 않은 데이터 변형으로 인한 버그를 사전에 차단합니다[3, 4]. 단, 최상위 속성에만 적용되는 얕은(shallow) 불변성만을 제공하므로, 중첩된 객체를 완전히 동결하려면 재귀적인 형태의 딥 리드온리(Deep Readonly) 패턴이 별도로 필요합니다[5, 6].
|
||||
## 매 한 줄
|
||||
> **"매 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` 의 의.
|
||||
|
||||
---
|
||||
## 매 핵심
|
||||
|
||||
> `readonly`는 TypeScript에서 객체의 속성이나 배열, 튜플이 초기화된 이후에 수정되지 않도록 방지하는 수식어이자 유틸리티 타입입니다 [1-3]. 변수의 재할당을 막는 `const`와 달리 객체 내부 구조의 불변성을 제어하며, 런타임 오버헤드 없이 컴파일 타임에 오류를 잡아내어 코드의 안정성과 예측 가능성을 높입니다 [2, 4, 5].
|
||||
### 매 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.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **기본 작동 원리와 문법:**
|
||||
`Readonly<T>`는 주어진 타입 `T`의 모든 프로퍼티를 읽기 전용으로 매핑합니다[1, 2]. 설정이나 API 응답, 상태 관리 리듀서 등 앱 내내 값이 유지되어야 하는 객체를 보호할 때 주로 사용됩니다[7, 8]. TypeScript 코드가 컴파일된 후에는 관련 어노테이션이 모두 사라지므로 실행 시점(Runtime)에는 어떠한 오버헤드도 발생시키지 않습니다[3, 9].
|
||||
### 매 핵심 행동
|
||||
- 매 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.
|
||||
|
||||
- **유사 개념과의 차이점:**
|
||||
- **`const`와의 차이:** `const`는 변수 자체의 재할당을 막지만 참조된 객체의 내부 속성 변경은 막지 못합니다. 반면 `readonly`는 변수 바인딩이 아닌 객체 속성이나 배열 요소 자체의 변경을 제한합니다[10, 11].
|
||||
- **`Object.freeze()`와의 차이:** `Object.freeze()`는 런타임에 객체를 동결하며 실행 성능에 비용을 청구하지만, `readonly`는 컴파일 타임에 타입 시스템을 통해서만 수정을 금지합니다[4, 12].
|
||||
### 매 응용
|
||||
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`.
|
||||
|
||||
- **배열에서의 활용:**
|
||||
객체뿐만 아니라 배열에도 `ReadonlyArray<T>` 또는 `readonly T[]` 형태로 사용할 수 있습니다[13, 14]. 이렇게 선언된 배열은 요소의 재할당이 불가능할 뿐만 아니라, `push()`, `pop()` 등 원본을 수정하는 메서드가 타입 정의에서 완전히 제거됩니다[15, 16].
|
||||
## 💻 패턴
|
||||
|
||||
- **한계점 및 우회 취약점 (Gotcha):**
|
||||
- **얕은 불변성(Shallow Immutability):** `Readonly<T>`는 1단계 깊이의 속성에만 작용합니다. 객체 내부의 중첩된 객체 속성은 여전히 수정이 가능하며, 이를 해결하기 위해서는 매핑된 타입과 조건부 타입을 결합한 커스텀 `[[DeepReadonly|DeepReadonly]]<T>` 유틸리티를 구현해야 합니다[5, 6, 17].
|
||||
- **에일리어싱(Aliasing) 문제:** `readonly` 타입의 데이터를, 수정 가능한 타입(mutable)을 매개변수로 받는 함수에 전달할 경우 타입 호환성 규칙에 의해 통과될 수 있습니다. 이로 인해 함수 내부에서 원본 데이터가 변경되는 우회 돌연변이가 발생할 수 있습니다[18, 19].
|
||||
|
||||
---
|
||||
|
||||
* **작동 방식 및 성능:**
|
||||
`readonly`는 전적으로 컴파일 타임에만 동작하는 기능으로, 컴파일 후 생성된 [[JavaScript|JavaScript]] 코드에서는 흔적이 사라집니다 [2, 6]. 따라서 성능에 어떠한 런타임 오버헤드도 주지 않으면서 속성의 불변성을 강제할 수 있습니다 [2, 5, 6].
|
||||
|
||||
* **객체 및 클래스에서의 활용:**
|
||||
인터페이스나 타입 별칭, 클래스의 속성에 `readonly`를 지정할 수 있습니다. 클래스에서는 선언 시점이나 생성자(constructor) 내부에서만 초기화가 가능하며, 그 이후에 값을 수정하려고 시도하면 컴파일러가 에러를 발생시킵니다 [7, 8]. 이는 시스템의 고유 식별자(ID)나 환경 설정 값처럼 생명 주기 동안 변하지 않아야 하는 데이터를 보호할 때 유용합니다 [7, 9].
|
||||
|
||||
* **배열과 튜플의 보호:**
|
||||
배열을 `readonly T[]` 또는 `ReadonlyArray<T>`로 선언하면 `push`, `pop`, 요소 직접 재할당 등 배열을 변이시키는 모든 메서드와 작업이 타입 시스템에서 제거되어 안전하게 보호됩니다 [10-12]. 튜플 역시 각 위치의 값을 고정하기 위해 `readonly`를 적용할 수 있습니다 [10].
|
||||
|
||||
* **const 및 Object.freeze()와의 비교:**
|
||||
* `const`: 런타임에 변수 자체의 재할당을 방지하지만, 참조된 객체 내부 속성의 변경은 막지 못합니다 [4, 13, 14].
|
||||
* `Object.freeze()`: 런타임에 객체의 얕은 수정을 차단하며 성능 비용이 발생합니다 [5, 14, 15].
|
||||
* `readonly`: 컴파일 타임에 객체/배열 내부 속성의 변경을 타입 레벨에서 차단하여, 실행 전 코드 작성 단계에서 안전을 보장합니다 [4, 5, 14].
|
||||
|
||||
* **얕은 불변성(Shallow Immutability)의 한계:**
|
||||
기본적인 `readonly` 수식어나 `Readonly<T>` 유틸리티 타입은 최상위 레벨의 속성에만 얕게 적용됩니다 [16-18]. 즉, 중첩된 내부 객체는 여전히 수정될 수 있습니다 [17, 18]. 완벽한 깊은 불변성을 원한다면 재귀적으로 속성을 잠그는 커스텀 `[[DeepReadonly|DeepReadonly]]` 유틸리티 타입을 별도로 구현해야 합니다 [17-19].
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.
|
||||
|
||||
---
|
||||
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** [[불변성 (Immutability)|불변성(Immutability]], 매핑된 타입(Mapped Types), [[DeepReadonly|DeepReadonly]]
|
||||
- **Projects/Contexts:** 변경 불가한 외부 API 응답 데이터 모델링, 상태 관리 시스템(Redux 리듀서 등)의 데이터 무결성 보장, 그리고 애플리케이션의 전역 환경 설정(Configuration) 객체 보호 맥락에서 광범위하게 쓰입니다[8, 17].
|
||||
- **Contradictions/Notes:** TypeScript의 에일리어싱 한계로 인해 `readonly` 데이터가 `mutable` 타입을 요구하는 함수로 전달되어 내부에서 값이 변경될 위험이 존재하므로, 완전한 불변성을 지키려면 함수 시그니처 전반에 걸쳐 읽기 전용 파라미터를 강제하거나 데이터의 복사본을 넘기는 설계가 필요합니다[18, 19]. 또한, 모든 `readonly` 속성을 다시 수정 가능하게 되돌려야 할 때는 `Mutable`이라는 커스텀 헬퍼 타입을 만들어 매핑 수식어를 제거(`-readonly`)하는 방식으로 해결할 수 있습니다[6].
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-18*
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
- **Related Topics:** const, Object.freeze(), ReadonlyArray, [[DeepReadonly|DeepReadonly]], Utility Types
|
||||
- **Projects/Contexts:** [[State|State]] [[Management|Management]], Configuration Objects, API Responses
|
||||
- **Contradictions/Notes:** `readonly`는 데이터 변경을 막는 훌륭한 타입 제어 장치지만, 컴파일러는 `readonly` 데이터를 변경 가능(mutable)한 매개변수를 받는 함수에 전달하는 것(Aliasing)을 허용하므로 이로 인한 우회적 변이(mutation)가 발생할 수 있다는 구조적 맹점을 주의해야 합니다 [20, 21].
|
||||
|
||||
---
|
||||
*Last updated: 2026-04-18*
|
||||
|
||||
---
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
### 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
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### `Readonly<T>` mapped
|
||||
```ts
|
||||
type Frozen<T> = Readonly<T>;
|
||||
const cfg: Frozen<{ host: string; port: number }> = { host: "x", port: 80 };
|
||||
cfg.host = "y"; // Error
|
||||
```
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Deep readonly
|
||||
```ts
|
||||
type DeepReadonly<T> = {
|
||||
readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
|
||||
};
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
const data: DeepReadonly<{ user: { id: number } }> = { user: { id: 1 } };
|
||||
data.user.id = 2; // Error
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### `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
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### `as const` (literal narrowing)
|
||||
```ts
|
||||
const ROLES = ["admin", "user", "guest"] as const;
|
||||
type Role = typeof ROLES[number]; // "admin" | "user" | "guest"
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
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]]
|
||||
- 변형: [[const]] · [[Object.freeze]] · [[Immer]]
|
||||
- 응용: [[Redux Toolkit]] · [[Zustand]] · [[Type-Level Programming]]
|
||||
- Adjacent: [[Branded Types]] · [[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 |
|
||||
|
||||
Reference in New Issue
Block a user