2nd/10_Wiki/Topics/Programming & Language/DOM 요소 조작 및 타입 좁히기.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

// 매 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

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

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

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

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

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

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)

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