[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,102 +2,175 @@
|
||||
id: wiki-2026-0508-dom-요소-조작-및-타입-좁히기
|
||||
title: DOM 요소 조작 및 타입 좁히기
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [P-Reinforce-AUTO-3A0CD0]
|
||||
aliases: [DOM Manipulation, Type Narrowing, querySelector Typing]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 0.9
|
||||
tags: [auto-reinforced]
|
||||
verification_status: applied
|
||||
tags: [typescript, dom, web, type-narrowing]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-20
|
||||
github_commit: "[P-Reinforce] Continuous Worker - DOM 요소 조작 및 타입 좁히기"
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
language: typescript
|
||||
framework: dom
|
||||
---
|
||||
|
||||
# [[DOM 요소 조작 및 타입 좁히기]]
|
||||
# DOM 요소 조작 및 타입 좁히기
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> DOM 요소 조작 시에는 타입스크립트의 타입 좁히기(Type Narrowing) 기술을 통해 타입 안정성을 확보하는 것이 중요합니다. 타입 좁히기란 코드 흐름 분석을 사용하여 포괄적인 타입(유니온 타입 등)을 구체적인 단일 타입으로 줄여나가는 과정입니다 [1-3]. DOM 요소를 다루거나 구조가 명확하지 않은 데이터를 처리할 때, 타입 단언(`as`), 사용자 정의 타입 가드, `typeof` 및 `instanceof` 연산자 등을 활용하여 안전하게 타입을 좁혀 조작할 수 있습니다 [4-6].
|
||||
## 매 한 줄
|
||||
> **"매 DOM API 의 untyped boundary 의 TypeScript narrowing 의 적용"**. 매 `querySelector` 의 default `Element | null` 위 의 generic + instanceof + assertion. 2026 의 strict null checks + satisfies + lib.dom.d.ts 의 mainstream type ergonomics.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
**DOM 요소 조작 시 타입 단언(`as`)의 활용**
|
||||
* DOM 요소로 작업하며 타입을 좁혀야 할 때, 타입 단언(`as`) 연산자가 주로 활용됩니다 [5].
|
||||
* 타입 단언은 런타임 검증을 마쳤거나 DOM 조작과 같이 불가피한 상황에서 컴파일러에게 특정 타입임을 강제할 때 사용합니다 [5, 7]. 하지만 개발자가 잘못 판단할 경우 컴파일러가 에러를 잡지 못해 런타임 오류로 이어질 수 있으므로 사용에 매우 주의해야 합니다 [7, 8].
|
||||
## 매 핵심
|
||||
|
||||
**DOM 요소 삽입과 브랜디드 타입(Branded Types)을 통한 보안**
|
||||
* 사용자의 입력값을 DOM의 `innerHTML` 등에 직접 추가하는 것은 XSS 공격에 노출될 수 있는 위험한 방식입니다 [9].
|
||||
* 이를 방어하기 위해 브랜디드 문자열 타입(Branded String Types)을 사용하여, 데이터가 DOM에 추가되기 전에 반드시 정제(Sanitized) 과정을 거쳤음을 타입 시스템 차원에서 강제할 수 있습니다 [9].
|
||||
* 또한, 유효하지 않은 잉여 속성(예: 'hello')을 DOM 객체로 전달할 경우 React와 같은 라이브러리에서는 경고를 발생시킬 수 있으므로 정확한 타입 지정이 중요합니다 [10].
|
||||
### 매 Type narrowing tools
|
||||
- **Generic param**: `querySelector<HTMLInputElement>(...)` — runtime check 의 X, 매 assertion 만.
|
||||
- **`instanceof`**: 매 runtime check + narrow.
|
||||
- **Type guard function**: `function isInput(el): el is HTMLInputElement`.
|
||||
- **Discriminated property**: `el.tagName === 'INPUT'` (의 narrow X — manual cast 필요).
|
||||
|
||||
**타입 좁히기(Type Narrowing)의 주요 기법**
|
||||
* **`typeof` 및 `instanceof` 연산자:** `typeof`를 사용해 "string", "number", "boolean" 등의 원시 타입을 확인하거나, `instanceof`를 사용해 생성자 프로토타입의 인스턴스인지를 확인하여 타입을 좁힙니다 [4, 6].
|
||||
* **`in` 연산자 및 판별 속성(Discriminant Property):** 객체 내에 특정 속성이 존재하는지 `in` 키워드로 확인하거나, 식별 가능한 유니온([[Discriminated Unions]]) 패턴에서 공통 리터럴 타입 필드(예: `kind` 또는 `type`)를 `switch` 문으로 비교하여 해당 블록 내의 타입을 안전하게 좁힙니다 [1, 3, 4, 11].
|
||||
* **타입 서술어(Type Predicates):** 반환 타입에 `is` 키워드를 사용하여(예: `value is Positive`), 함수가 `true`를 반환할 때 조건문 내부에서 매개변수가 특정 타입으로 좁혀지도록 타입 시스템에 알립니다 [6, 12].
|
||||
* **단언 함수(Assertion Functions):** 입력된 값이 기대한 타입이 아닐 경우 에러를 던지도록 작성된 함수입니다. 이 함수를 통과한 이후의 코드는 해당 값이 특정 타입이 확실함을 타입 시스템이 인지하여 타입을 좁히게 됩니다 [13, 14].
|
||||
### 매 Null safety
|
||||
- `querySelector` 의 `null` 의 always 가능 — 매 explicit check.
|
||||
- `getElementById` 의 same — `HTMLElement | null`.
|
||||
- `as!` non-null assertion 의 last resort — 매 prefer guard.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
|
||||
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.
|
||||
### 매 응용
|
||||
1. Form value 추출 + validation.
|
||||
2. Dynamic widget hydration (서버 HTML 위 의 JS enhance).
|
||||
3. Custom element / Web Component 의 typed access.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- **Related Topics:** Type Narrowing, Type Assertions, [[Discriminated Unions]], Branded Types
|
||||
- **Projects/Contexts:** 안전한 DOM 조작 및 데이터 정제, React 컴포넌트 Props 처리
|
||||
- **Contradictions/Notes:** 타입 단언(`as`)은 DOM 요소를 다루며 타입을 좁힐 때 유용하고 흔하게 사용되지만 [5], 런타임 동작에는 영향을 주지 않으므로 타입 에러를 우회하여 잘못된 코드를 통과시킬 위험이 있습니다. 따라서 가능한 한 `satisfies`나 사용자 정의 타입 가드 등 더 안전한 방식을 우선적으로 고려하는 것이 좋습니다 [7, 8, 15].
|
||||
## 💻 패턴
|
||||
|
||||
---
|
||||
*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
|
||||
### querySelector with generic
|
||||
```typescript
|
||||
// 매 generic 의 assertion 만 — 매 null 의 still 가능
|
||||
const input = document.querySelector<HTMLInputElement>('#email');
|
||||
if (!input) throw new Error('email input missing');
|
||||
input.value; // 매 narrowed to HTMLInputElement
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### instanceof guard
|
||||
```typescript
|
||||
const el = document.getElementById('email');
|
||||
if (el instanceof HTMLInputElement) {
|
||||
el.value = 'test@example.com'; // 매 narrowed
|
||||
} else {
|
||||
throw new Error('not an input');
|
||||
}
|
||||
```
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Custom type guard
|
||||
```typescript
|
||||
function isInput(el: Element | null): el is HTMLInputElement {
|
||||
return el instanceof HTMLInputElement;
|
||||
}
|
||||
function getValue(selector: string): string {
|
||||
const el = document.querySelector(selector);
|
||||
if (!isInput(el)) throw new Error(`${selector} is not input`);
|
||||
return el.value;
|
||||
}
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Helper: assertElement
|
||||
```typescript
|
||||
function $<T extends HTMLElement>(
|
||||
selector: string,
|
||||
ctor: new () => T = HTMLElement as new () => T,
|
||||
root: ParentNode = document,
|
||||
): T {
|
||||
const el = root.querySelector(selector);
|
||||
if (!el) throw new Error(`Missing: ${selector}`);
|
||||
if (!(el instanceof ctor)) throw new Error(`Wrong type: ${selector}`);
|
||||
return el as T;
|
||||
}
|
||||
const form = $('#login', HTMLFormElement);
|
||||
const email = $('input[name=email]', HTMLInputElement, form);
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### Form data — typed
|
||||
```typescript
|
||||
function getFormData<T extends Record<string, string>>(form: HTMLFormElement): T {
|
||||
const fd = new FormData(form);
|
||||
return Object.fromEntries(fd.entries()) as T;
|
||||
}
|
||||
type LoginForm = { email: string; password: string };
|
||||
const data = getFormData<LoginForm>(form);
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### Event delegation with narrowing
|
||||
```typescript
|
||||
document.addEventListener('click', (e) => {
|
||||
const target = e.target;
|
||||
if (!(target instanceof HTMLElement)) return;
|
||||
const btn = target.closest<HTMLButtonElement>('button[data-action]');
|
||||
if (!btn) return;
|
||||
switch (btn.dataset.action) {
|
||||
case 'save': return save();
|
||||
case 'delete': return remove(btn.dataset.id!);
|
||||
default: throw new Error(`Unknown action: ${btn.dataset.action}`);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### Custom element typing
|
||||
```typescript
|
||||
class MyToggle extends HTMLElement {
|
||||
toggle() { this.toggleAttribute('open'); }
|
||||
}
|
||||
customElements.define('my-toggle', MyToggle);
|
||||
|
||||
declare global {
|
||||
interface HTMLElementTagNameMap { 'my-toggle': MyToggle; }
|
||||
}
|
||||
const t = document.querySelector('my-toggle'); // 매 typed as MyToggle | null
|
||||
t?.toggle();
|
||||
```
|
||||
|
||||
### satisfies for config (2026 idiom)
|
||||
```typescript
|
||||
const handlers = {
|
||||
'#save': (el: HTMLButtonElement) => el.addEventListener('click', save),
|
||||
'#email': (el: HTMLInputElement) => el.addEventListener('blur', validate),
|
||||
} satisfies Record<string, (el: HTMLElement) => void>;
|
||||
```
|
||||
|
||||
## 매 결정 기준
|
||||
| 상황 | Pattern |
|
||||
|---|---|
|
||||
| Single fetch + null OK | `querySelector<T>` + null check |
|
||||
| Strict invariant | `$()` helper with ctor |
|
||||
| Multiple element types | instanceof in switch |
|
||||
| Reusable check | Custom type guard |
|
||||
| Event handler | `target instanceof HTMLElement` |
|
||||
| Custom element | HTMLElementTagNameMap augment |
|
||||
|
||||
**기본값**: assertElement helper + instanceof + custom guards. `as` casts 의 last resort 만.
|
||||
|
||||
## 🔗 Graph
|
||||
- 부모: [[TypeScript]] · [[DOM]]
|
||||
- 변형: [[Discriminated_Unions]] · [[Type_Guards]]
|
||||
- 응용: [[DOM_요소_조작]] · [[Web_Components]] · [[Form_Validation]]
|
||||
- Adjacent: [[strictNullChecks]] · [[Generic_Constraints]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
**언제**: helper 작성, type guard 추출, refactor untyped jQuery → typed TS.
|
||||
**언제 X**: 매 framework (React/Vue/Svelte) 안 — 매 framework type 의 사용.
|
||||
|
||||
## ❌ 안티패턴
|
||||
- **`as HTMLInputElement` everywhere**: runtime mismatch 의 silent.
|
||||
- **`!` non-null assertion 남발**: 매 null check 의 미루기 — runtime crash.
|
||||
- **`any` for events**: 매 `Event` subclass 의 사용.
|
||||
- **`getElementById` raw return 사용**: null check skip.
|
||||
- **innerHTML with user input**: 매 XSS — `textContent` / DOMPurify 의 사용.
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
- Verified (TypeScript handbook, lib.dom.d.ts, MDN DOM docs).
|
||||
- 신뢰도 A.
|
||||
|
||||
## 🕓 Changelog
|
||||
| 날짜 | 변경 |
|
||||
|---|---|
|
||||
| 2026-05-08 | Phase 1 |
|
||||
| 2026-05-10 | Manual cleanup — generic/instanceof/guard/helper patterns for typed DOM |
|
||||
|
||||
Reference in New Issue
Block a user