---
id: wiki-2026-0508-dom-요소-조작-및-타입-좁히기
title: DOM 요소 조작 및 타입 좁히기
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [DOM Manipulation, Type Narrowing, querySelector Typing]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [typescript, dom, web, type-narrowing]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: dom
---

# DOM 요소 조작 및 타입 좁히기

## 매 한 줄
> **"매 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.

## 매 핵심

### 매 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 필요).

### 매 Null safety
- `querySelector` 의 `null` 의 always 가능 — 매 explicit check.
- `getElementById` 의 same — `HTMLElement | null`.
- `as!` non-null assertion 의 last resort — 매 prefer guard.

### 매 응용
1. Form value 추출 + validation.
2. Dynamic widget hydration (서버 HTML 위 의 JS enhance).
3. Custom element / Web Component 의 typed access.

## 💻 패턴

### 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
```

### 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');
}
```

### 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;
}
```

### 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);
```

### 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);
```

### 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}`);
  }
});
```

### 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]]
- 응용: [[DOM 요소 조작]] · [[Web_Components]]

## 🤖 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 |