gamzamandu 님의 블로그

OpenAPI만 주면 API 요청 함수를 생성해준다고?

gamzamandu — Sun, 7 Jun 2026 13:46:53 +0900

[서론]

[1. 시간이 없다 시간이]

졸업작품전 프로젝트를 제출해야 하고 남은 시간은 한 달. 코엑스 전시 건으로 한 주가 지나갔으니 2주 정도의 개발시간이 남았다.

네이버 페이 비상장을 레퍼런스로 한 "교내 프로젝트를 상장시키는 증권거래소, 깃허브 활동 내역이 뉴스가 된다!"를 혼자 만들어야 한다. 증권 시장의 시스템(IPO, 공모청약, 주식거래, 유동성)의 기능을 구현해야 했기 때문에 만들어야 할 것들도 많고 그만큼 프론트엔드에 연결해야 할 API도 많다.

좌(부산소마고 증권거래소), 우(네이버 페이 비상장)

그것을 해결해줄 한 가지의 빛을 보았으니 그것이 Orval이다.

[본론]

[1. Orval이 뭐예요??]

Orval은 OpenAPI 스펙을 통해 Typscript로 API함수, 타입, 목데이터까지 생성해 주는 라이브러리이다. 노가다성으로 반복되는 CRUD API 보일러플레이트를 생성해 주며, 무려 React Query 훅까지 생성해 준다.

좌(OpenAPI 스펙)을 토대로 (우)보일러플레이트 코드를 생성하는 모습

[2. 본론 : 도입했을 때 어때]

[1. Pure UI 영역에 집중할 수 있다.]

Orval이 API 레이어를 책임져주다 보니, 컴포넌트 코드에는 오직 상태 관리와 가시적인 영역을 위한 코드만 남는다. API 호출 레이어가 자동 생성되면서, 컴포넌트에서는 UI와 상태 관리에 더 집중할 수 있다.

[2. 생산성이 압도적으로 올라간다.]

API 함수들을 직접 구현할 필요가 없어지다 보니 프론트의 주요 작업이 크게 날아간다. 직접 구현해야 할 영역은 낙관적 업데이트(그마저도 Orval의 함수로 구현하면 된다)와 SSE 정도다.

SSE나 WebSocket 같은 스트리밍 통신은 OpenAPI 표준으로 명확히 표현하기 어려워 Orval 측에서도 지원하지 않는 것 같다. Orval은 REST API 도구라고 생각하면 좋다.

[3. Orval에 종속되는 거 아니야?]

그렇지 않다. Orval은 "스펙 → 타입 + 훅" 변환기 한 단계일 뿐이고, 실질적인 제어권은 개발자한테 있다.

예를 들면 baseAPI를 오버라이딩해서 인프라 코드를 우리 손에 둘 수 있다. Orval은 기본적으로 단순 baseFetch만 쓰는데, config를 통해 이를 커스텀 함수로 교체할 수 있다.

// orval.config.ts
override: {
  mutator: { path: 'src/shared/api/index.ts', name: 'baseFetch' }
}

Orval이 코드를 생성할 때, 모든 fetch 호출부에 직접 fetch()를 박는 대신 이 경로의 baseFetch를 import해서 쓴다. 함수 위치와 이름만 정해주면 Orval이 그 시그니처에 맞춰 생성해 주는 식이다.

커스텀 훅이 필요하다면 생성된 훅을 컴포넌트에서 직접 쓰는 대신, 도메인 훅으로 한 번 더 감싸면 된다.

// src/features/admin-panel/model/useAdminStocksQuery.ts
export function usePendingStocksQuery() {
  return useListByStatusSuspense({ status: 'PENDING' }, { query: { refetchInterval: 30_000 } })
}

// src/features/stock-team/model/useAddTeamMember.ts
export function useAddTeamMember(ticker: string) {
  return useMutation({
    mutationFn: ({ userId, shareRatio }) => addTeamMember(ticker, { userId, shareRatio }),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: getGetMyStocksQueryKey() }),
  })
}

컴포넌트는 생성된 함수명과 시그니처를 직접 모른다. 도메인 훅 이름(usePendingStocksQuery, useAddTeamMember)만 안다. 생성기를 교체해도 도메인 훅 내부만 고치면 된다.

[4. Orval쓰면 API 코드 난잡한 거 아니야?]

그렇지 않다. 오히려 반대다. 내 프로젝트 백엔드의 API 엔드포인트는 총 124개였는데, 이것을 인간이 직접 관리하는 것이 더 불안할 수 있다. 사람이 124개의 API 함수를 직접 타이핑하다 보면 오탈자나 타입 실수가 섞여 들어오기 마련이다. Orval은 스펙에서 코드를 생성하기 때문에 오탈자가 끼어들 여지가 없고, 백엔드 구조가 그대로 매핑되기 때문에 별도로 파악할 필요도 없다.

Orval이 생성한 코드도 체계적으로 관리하기 위해 생성 모드를 세 가지로 지원한다.

single: 모든 API를 한 파일 또는 한 묶음으로 생성하는 방식
tags: 태그 기준으로 파일을 나누되, 비교적 덜 세분화된 구조로 생성
tags-split: 태그별로 디렉터리까지 분리해서 생성

내 프로젝트에서는 tags-split 모드를 사용했는데, 컨트롤러별 디렉터리로 격리된다.

src/api/
  ├── admin-stock-controller/
  ├── stock-controller/
  └── ...

백엔드 스펙 구조가 그대로 매핑되고, mode: 'tags-split' 옵션 하나만 바꾸면 구조 자체도 재배치할 수 있다.

[5. API가 변경되면 어떻게 마이그레이션 하는데?]

Orval의 API 함수는 백엔드의 OpenAPI에 따라 자동으로 생성된다. API 스펙이 변경되면 타입 에러가 발생하기 때문에, 컴파일 단계에서 빠르게 문제를 확인할 수 있다.

[6. 목데이터도 연결하기 편하다.]

Orval는 mock: true 옵션 하나로 MSW 기반 mock 핸들러와 샘플 데이터를 자동 생성해 준다.

[결론]

2주라는 시간 안에 124개의 API를 연결하면서도 UI 품질을 유지할 수 있었던 건 Orval 덕분이었다. 새로운 도구를 빠르게 도입해 실행력을 확보하면서도, Orval이 종속되지 않는 구조를 제공해준 덕분에 확장성을 잃지 않았다.

FSD와의 궁합도 좋았다. Orval이 생성한 코드는 src/api/에 격리되고, 인프라 코드인 baseFetch는 FSD의 shared 레이어에 자연스럽게 안착했다. features의 도메인 훅이 api를 참조하는 방향도 FSD의 단방향 의존성 원칙과 맞아떨어졌다. 자동생성 코드와 수동 코드의 경계가 구조적으로 명확하게 나뉘었다.

백엔드 스펙이 그대로 코드로 매핑되다 보니 프론트와 백엔드 사이의 간극도 줄어들 것 같다. 이 프로젝트는 내가 모든 영역을 담당했기 때문에 직접 체감하진 못했지만, 실제 협업 상황이라면 API 명세가 변경될 때마다 타입 에러로 즉시 드러나기 때문에 별도 커뮤니케이션 없이도 변경점을 빠르게 파악할 수 있을 것이다.

Orval은 단순히 코드를 줄여주는 도구라기보단, API 레이어라는 인프라 관심사를 위임함으로써 개발자가 진짜 집중해야 할 영역에 더 많은 시간을 쓸 수 있게 해주는 도구라고 느꼈다.

React Suspense는 Wakeable을 Throw한다.

gamzamandu — Sat, 2 May 2026 12:13:18 +0900

[서론]

1. [Suspense의 등장]

Suspense는 비동기 데이터를 다루는 보일러플레이트를 해결하기 위해 나왔다. 데이터를 받아오는 동안 로딩을 띄우고, 에러가 나오면 그에 맞는 UI를 띄우는 작업을 말이다. 아래 예시를 보자.

function UserProfile({ userId }) {
  const [user, setUser]       = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError]     = useState(null);

  useEffect(() => {
    setLoading(true);
    fetchUser(userId)
      .then(data  => { setUser(data);   setLoading(false); })
      .catch(err  => { setError(err);   setLoading(false); });
  }, [userId]);

  if (loading) return <Spinner />; // 핵심로직
  if (error)   return <ErrorCard error={error} />; // 핵심로직
  return <UserCard user={user} />; // 핵심로직
}

마지막 핵심로직에 비해 그 위에 loading/error 관리 코드가 컴포넌트를 덮고 있다. 컴포넌트가 10개면 이 패턴을 10개를 만들어야 한다는 의미이다. Suspense는 이 상태관리의 책임을 외부로 위임하고 컴포넌트는 핵심로직에 집중할 수 있도록 하기 위해 만들어졌다.

2. [Suspense의 사용]

아래는 React 19 버전식 Suspense 예제이다. Suspense는 Children에 필요한 코드와 데이터를 로딩할 때까지 Fallback을 보여주게 된다. Children이 지연되면 가장 가까운 Boundery의 Suspense가 활성화된다. use()에 대해 궁금할 텐데 일단 여기선 비동기 작업(Promise)의 결과를 마치 동기 코드처럼 처리해주고 있다고 이해하라.

import { use } from "react";

function UserProfile({ userId }) {
  const user = use(fetchUser(userId));
  return <UserCard user={user} />;     // 핵심로직만!
}

function App() {
  return (
    <Suspense fallback={<Spinner />}>
      <ErrorBoundary fallback={<ErrorCard error={error} />}>
        <UserProfile userId={1} />
      </ErrorBoundary>
    </Suspense>
  );
}

의문이 생긴다. 어떻게 Suspense는 비동기 상태를 읽어들이는 것일까? 아무 비동기 상태나 되는 것인가?

그렇지 않다. React 공식문서에 따르면 “Suspense가 가능한 데이터만이 Suspense 컴포넌트를 활성화합니다.”라고 되어있다.
따라서 React 개발팀에서 정해둔 기준이 있는 것이다. ~~(코드는 마법이 아니다.)~~ 그 기준을 소개해보겠다.

[본론]

1. [동작원리에 대하여]

1.1. [Suspense는 Wakeable을 throw하는 것으로 통신한다]

Suspense는 하나의 통신에 기반한다. React 내부에서 Suspense가 비동기 요청과 통신하는 방법은 Wakeable을 throw하는 것이다.

컴포넌트가 아직 준비되지 않았을 때 Wakeable을 throw하면, React가 가로채서 가장 가까운 Suspense 경계의 fallback을 보여준다. 그리고 Wakeable이 resolve되면 children을 다시 렌더링한다.

무슨 말인지 모르겠을 테지만 일단 쭉 읽어보아라. 아무 비동기 요청이나 처리하는 마법은 없으니 Suspense가 처리할 요청을 React팀에서 정의한 것이다. 단순한 비동기 요청과는 차이를 둔 Wakeable 개념을 소개해보겠다.

[Thenable, Promise 그리고 Wakeable]

각 개념은 서로 계층적인 관계가 있다.

1. Thenable
Thenable은 JS에서 가장 넓은(loose한) 개념인데, `then()` 메서드를 가진 객체라고 생각하면 다.

{ then(onFulfill, onReject) { ... } } 구조를 가졌다면 모두 Thenable이다. 상태의 정의는 개발자의 몫이나, Promise와 호환을 보장하는 레벨이라고 이해하자.

2. Promise
Promise는 Thenable의 특수한 경우라 할 수 있겠다. Promise/A+ 스펙을 준수하는 객체이다. 상태(pending → fulfilled/rejected)가 한 번 정해지면 불변이고, then() 콜백은 항상 microtask 큐로 비동기 실행되는 엄격한 규칙을 따른다는 것이다.

3. Wakeable
Wakeable은 React가 Suspense 상태를 제어하기 위해 만든 Promise의 최소 인터페이스이다.
네이티브 Promise와는 달리, React가 비동기 요청의 주체에게 "지금 준비된 거야?"라고 질문(ping)할 수 있어야 한다.
Thenable과 Promise는 "언제 완료될지" React가 모르나, Wakeable은 React가 주도권을 가질 수 있도록 설계한 것이다.

Wakeable은 React에 전달만 되면 되기 때문에 가벼운 인터페이스를 유지한다. 이로 얻는 장점이 있는데:

성능: 네이티브 Promise는 스펙상 콜백을 항상 마이크로태스크 큐에 넣는다.
반면 React Flight 같이 성능이 중요한 영역에서 Wakeable(가짜 Promise)를 이용해서 비용을 줄일 수 있다.
유연성: 네이티브 Promise는 생성 시점에서 실행자가 즉시 실행된다. 반면 Wakeable은 커스텀하여 제어할 수 있다. React에게 주도권을 쥐어주기 위한 용도이니 훨씬 React에 유용하다.
가벼움: Wakeable은 ping을 할 수 있는 최소 인터페이스이다. reconciler가 throw된 객체에서 `then(onFulfill, onReject)` 콜백만 연결하면 된다. 나머지 Promise의 메서드는 신경 쓰지 않아도 된다.

이 설명을 들으면 "난 Suspense를 쓸 때 Wakeable한 Promise를 호출해서 쓰지 않았는데"라는 생각이 들 수도 있는데, React가 당신이 만든 Promise를 Wakeable 객체로 취급(duck typing)했기 때문이다. 이 과정에 대해 알아보자.

1.2. [React는 throw된 값이 Wakeable인지 판별한다]

React는 컴포넌트를 렌더링할 때 fiber 트리를 위에서 아래로 내려가며 하나씩 처리한다. 이 내려가는 과정을 begin phase라 부른다. Suspense를 만나면 그 안으로 들어가 children을 렌더링하기 시작한다. 이 상태에서 컴포넌트가 무언가를 throw하면 workloop의 try...catch가 이것을 잡는다. 그리고 이것이 Suspense를 위한 Wakeable인지, 진짜 에러인지 조사한다. throw는 원래 에러를 던지기 위해 만든 것이기 때문이다.

실제 코드를 보면 알 수 있다. React는 instanceof Promise로 판단하지 않는다. then이 붙어있으면 Wakeable로 취급한다.
반대로 then이 없는 것이 throw되면 에러로 취급해 ErrorBoundary 경로로 흘러간다.

// ReactFiberThrow.js
function throwException(root, returnFiber, sourceFiber, value, rootRenderLanes) {
  sourceFiber.flags |= Incomplete;

  if (
    value !== null &&
    typeof value === 'object' &&
    typeof value.then === 'function'   // ← 이 조건 하나가 전부
  ) {
    // Wakeable로 취급 → Suspense 처리 경로
    const wakeable = value;
    // ...
  } else {
    // 일반 에러 → ErrorBoundary 경로
  }
}

참고로 Duck Typing은 "오리처럼 걷고, 오리처럼 꽥꽥 소리를 낸다면 오리다"라는 의미이다. ~~개발자들은 귀여운 거 좋아한다.~~

Wakeable로 판별됐다. 지금 React는 Suspense 안쪽 깊은 곳, throw가 발생한 지점에 있다. 이제 이 throw를 처리할 Suspense를 찾아야 한다.

1.3. [가장 가까운 Suspense Boundary를 찾아 ShouldCapture를 세운다]

getNearestSuspenseBoundaryToCapture()가 throw가 발생한 fiber의 return 포인터를 타고 조상을 거슬러 올라가며 가장 가까운 Suspense fiber를 직접 찾아낸다. 이로 인해 여러 Suspense가 중첩되어 있어도 가장 안쪽 경계가 먼저 잡힌다. (여기서 fiber라는 개념이 생소할 수 있는데 React는 모든 것을 fiber로 표현한다고 생각하라. 당신이 만든 Component도 모두 Fiber화 되어있다. 부모-자식 컴포넌트는 fiber의 return 포인터로 연결되어 있다.)

Suspense fiber를 찾으면 그 fiber에 직접 ShouldCapture 플래그를 세운다. "이 Suspense가 이번 suspend를 처리해야 한다"는 접수 신호다. 바로 fallback을 렌더링하지 않는 이유가 있다. 지금은 아직 begin phase 도중이라 자식 평가가 끝나지 않은 상태다. 이 시점에 fallback 렌더링을 확정하면 불완전한 상태에서 진행하게 된다. 실제 확정은 이후 complete phase에서 이루어진다.

const suspenseBoundary = getNearestSuspenseBoundaryToCapture(returnFiber);

if (suspenseBoundary !== null) {
  markSuspenseBoundaryShouldCapture(
    suspenseBoundary, returnFiber, sourceFiber, root, rootRenderLanes
  );
}

1.4. [Wakeable이 끝나면 알려줄 리스너를 등록한다]

Suspense가 처리할 요청이 예약됐다. 이제 언제 그 요청이 끝날지 알아야 한다. React가 주기적으로 상태를 확인하는 것이 아니라, Promise 측에서 상태를 알려주는 구조다. 옵저버 패턴이다.

이를 위해 두 개의 리스너를 등록한다. ping은 "스케줄링할 작업이 생겼다는 신호"를 보내는 것이고, retry는 "이 특정한 Suspense가 대상이라는 정보"다. React가 <언제를 결정하는 스케줄링 레이어>와 <어디를 결정하는 렌더링 타겟 레이어>를 명확히 나누었기 때문이다.

스케줄링 레이어는 우선순위에 따라 렌더링 순서를 조정할 뿐이다. 대상이 작업 순서에 오면 그때 타겟 레이어를 확인하여 무엇을 해야 할지 정보를 확인한다.

if (suspenseBoundary.mode & ConcurrentMode) {
  attachPingListener(root, wakeable, rootRenderLanes);  // 언제
}
attachRetryListener(suspenseBoundary, root, wakeable);  // 어디

[ping]
attachPingListener()의 역할은 React 스케줄러에게 "이 root에서 대기 중이던 Suspense 작업이 끝났으니, 해당 lanes 우선순위로 리렌더링을 스케줄링해라"라는 신호를 보낸다.

코드를 보면 알 수 있는 한 가지 사실은 Cache가 있다. 한번 Listen한 Wakeable를 중복 등록하지 않게 WeakMap을 만들어놨다.

function attachPingListener(root, wakeable, lanes) {
  let pingCache = root.pingCache;
  // ... (WeakMap으로 중복 방지)

  const ping = pingSuspendedRoot.bind(null, root, wakeable, lanes);
  wakeable.then(ping, ping); // resolve든 reject든 ping 호출
}

여기서 주목할 점은 resolve callback과 reject callback 모두 ping으로 설정해둔 점이다. Suspense의 관점에서는 성공했건 실패했건 중요하지 않다. "Promise가 끝나면 다시 렌더링을 시도해야 한다"는 것이다. 성공인지 실패인지는 다음 렌더링의 역할이다.

[retry]
ping이 "언제 다시 시작할지"라면, retry는 "어디서부터 다시 시작할지"다. 1.3에서 ShouldCapture를 세운 Suspense fiber를 retry가 기억해둔다. Promise가 resolve된 이후 실제로 동작하는데, 자세한 동작은 1.6에서 다루겠다.

Wakeable 판별, Boundary 탐색, ShouldCapture 세팅, 리스너 등록이 모두 끝났다. 지금까지가 전부 begin phase 도중 일어난 일이다. React가 children을 렌더링하러 내려가다가 throw가 터졌고, 그 자리에서 처리할 수 있는 것들을 해뒀다. 이제 begin phase에서 할 수 없었던 것, 즉 경로 정리와 fallback 렌더링 확정을 위해 complete phase로 넘어가야 한다.

1.5. [ShouldCapture를 DidCapture로 전환하고 fallback을 렌더링한다]

begin phase에서 내려가던 렌더링이 throw로 중단됐다. 이제 complete phase가 시작된다. React는 begin phase에서 내려간 경로를 올라오며 마무리하는데, throw가 발생했으니 정상적인 완료가 아니다. workloop는 completeUnitOfWork를 호출하고, 이것이 Stack Unwinding의 시작이다.

1. [Stack Unwinding]

completeUnitOfWork는 throw가 발생한 fiber부터 위로 올라가며 경로상의 모든 fiber에 Incomplete를 마킹한다. "이 작업은 중단되었음. 자식이 다 못 그려졌기 때문."이라는 표시다. 이 과정에서 미완성 노드들이 실제 DOM에 반영되는 것을 막을 수 있다.

올라오다가 1.3에서 ShouldCapture를 세워둔 Suspense fiber에 도달한다. 이것이 Suspense의 complete phase다. 이 순간 ShouldCapture를 DidCapture로 전환하고 멈춘다.

ShouldCapture가 "throw 잡았어, 내가 처리할게"라는 접수 신호였다면, DidCapture는 "경로 정리까지 다 끝났어, 이제 fallback 렌더링해도 돼"라는 수습 완료 신호다. ShouldCapture는 begin phase 도중 세워진 것이라 자식 평가가 끝나지 않은 불완전한 상태였다. DidCapture는 complete phase에서 경로를 전부 정리한 뒤 세워지는 것이라 이제 안전하게 fallback 렌더링을 확정할 수 있다.

2. [fallback 렌더링]

workloop는 반환된 Suspense부터 다시 begin phase를 시작한다. DidCapture 플래그를 확인하고, children 대신 fallback 브랜치로 진입한다.

const didSuspend = (workInProgress.flags & DidCapture) !== 0;

if (didSuspend) {
  return mountSuspenseFallbackChildren(...); // fallback 렌더링
} else {
  return mountSuspensePrimaryChildren(...);  // children 렌더링
}

DidCapture는 일회용이다. fallback을 렌더링하고 나면 제거된다. 이후 retry로 재렌더링이 트리거될 때 DidCapture가 없으므로 children 브랜치로 정상 진입한다.

[children은 fiber 트리에서 사라지지 않는다]
fallback이 화면에 나타나는 동안 children은 DOM에서 제거되지만 fiber 트리에서는 살아있다. Suspense는 내부적으로 children을 Offscreen 컴포넌트로 감싸서 숨긴 채로 유지한다. 마치 `display: none`처럼 화면에서만 안 보이는 것이지, 존재 자체가 사라진 게 아니다.

1.6. [Promise가 resolve되면 retry가 children을 다시 렌더링한다]

이제 fallback이 화면에 나타났다. Promise가 resolve되면 ping이 스케줄러를 깨우고, 스케줄러가 적절한 시점에 렌더링을 다시 시작한다. 이때 1.4에서 등록해둔 retry가 "어디서부터 다시 시작할지"를 알려준다. React는 root 전체를 처음부터 다시 렌더링하지 않는다. retry가 가리키는 Suspense fiber부터 reconciling을 재시작한다.

이 재시도에서 children 컴포넌트가 다시 실행된다. 이번엔 캐시에 데이터가 있으므로 throw 없이 정상적으로 값을 반환한다. DidCapture가 없으므로 children 브랜치로 정상 진입하고, DOM에서 fallback이 제거되고 children이 나타난다.

자 여기까지 Suspense의 동작원리에 대해 알아보았다. 이제 서론에서 간단히 설명했던 Suspense의 사용에 동작원리를 더해보자.

2. [동작원리로 알아보는 Suspense 사용법]

2.1. [서론의 코드가 동작하는 이유]

서론에서 이런 코드를 소개하였다.

import { use } from "react";

function UserProfile({ userId }) {
  const user = use(fetchUser(userId));
  return <UserCard user={user} />;     // 핵심로직만!
}

function App() {
  return (
    <Suspense fallback={<Spinner />}>
      <ErrorBoundary fallback={<ErrorCard error={error} />}>
        <UserProfile userId={1} />
      </ErrorBoundary>
    </Suspense>
  );
}

use()에 대해 자세히 소개해보겠다.

앞서 Wakeable은 React가 비동기 요청의 주도권을 갖기 위해 설계한 인터페이스라고 했다. 그런데 개발자 입장에서 Wakeable을 직접 다루려면 pending인지 확인하고, pending이면 throw하고, resolve됐으면 값을 꺼내는 분기 처리를 매번 직접 작성해야 한다.

그 주도권을 개발자가 편하게 쓸 수 있도록 React 19에서 공식 API로 노출한 것이 use()다.

use()는 Promise를 받아서 아직 pending이면 throw하고, resolve됐으면 값을 반환한다.

function use(promise) {
  if (promise.status === 'pending')  throw promise;        // → Suspense로
  if (promise.status === 'rejected') throw promise.reason; // → ErrorBoundary로
  return promise.value;                                    // → 정상 반환
}

자 이제 이걸 알았으면, 동작을 전개해 보자.

fetchUser(userId)가 pending Promise를 반환하면 use()가 그것을 throw한다. 1.2번에서 봤듯이 React는 throw된 값에 then이 붙어있으면 Wakeable로 판별한다. Promise는 then을 가지고 있으니 당연히 Wakeable로 취급된다. React는 가장 가까운 Suspense 경계의 fallback을 보여준다.

fetchUser가 resolve되면 ping과 retry가 React를 깨운다. 컴포넌트가 다시 실행되고 이번엔 use()가 resolved된 값, 즉 유저 데이터를 반환한다. user 변수에 담기고, 비로소 <UserCard user={user} />가 화면에 나타난다.

서론의 코드가 동작한 이유는 use()가 pending/resolved/rejected 분기를 처리하고 Wakeable를 throw했기에 가능한 일이다.

예제 코드에는 사실 한 가지 문제가 있다. fetchUser(userId)가 컴포넌트 안에서 호출되고 있으니, 렌더링 때마다 Promise가 생긴다.

무한루프가 발생하는 것이다. 이것을 해결하고 넘어가 보자.

2.2. [무한루프를 막는 방법]

해결책은 단순하다. 렌더링마다 새 Promise를 만들지 않으면 된다. 같은 요청에 대해서는 항상 같은 Promise 객체를 반환해야 한다.

가장 간단한 방법은 Promise를 컴포넌트 바깥에서 만드는 것이다.

const userPromise = fetchUser(1); // 컴포넌트 바깥에서 한 번만 생성

function UserProfile() {
  const user = use(userPromise); // 항상 같은 Promise
  return <UserCard user={user} />;
}

그러나 이 방식은 userId가 바뀔 때 대응이 안 된다. 임시방편으로 useMemo로 개선할 수 있다.

function UserProfile({ userId }) {
  const userPromise = useMemo(() => fetchUser(userId), [userId]);
  const user = use(userPromise);
  return <UserCard user={user} />;
}

userId가 같으면 같은 Promise를 유지하고, 바뀌면 새로 만든다. 무한루프는 막힌다.
여기서 useMemo를 임시방편이라고 소개한 두 가지 이유가 있는데,

1. React는 캐싱의 영속을 보장하지 않는다.
React useMemo 공식 문서에 "You may rely on useMemo as a performance optimization, not as a semantic guarantee."라고 적혀있다. 즉, React는 메모리 확보를 위해 언제든 useMemo에 저장된 값을 삭제할 수 있도록 설계되어 있다. React 설계 원칙상 useMemo는 값의 유지를 보장(Guarantee)하지 않으므로, 비동기 데이터의 무결성을 담보하기에는 구조적으로 위험하다.

2. useMemo가 컴포넌트 생명주기에 완전히 종속되어 있음. 확장의 어려움.
그러나 useMemo는 컴포넌트 인스턴스에 묶여있다. 컴포넌트가 언마운트되면 캐시가 사라지고, 다른 컴포넌트에서 같은 userId로 요청하면 새로 fetch한다. 거기에 "오래된 데이터를 다시 가져오고 싶다"는 요구사항이 생기는 순간 직접 구현해야 할 것들이 폭발적으로 늘어난다. stale 처리, 탭 포커스시 재검증, 네트워크 재연결시 갱신... 결국 직접 구현하다 보면 TanStack Query를 다시 만들게 된다.

그래서 실무에서는 useSuspenseQuery를 쓴다. queryKey를 기반으로 Promise를 컴포넌트 외부의 QueryClient에 캐싱하고, stale 처리와 재검증까지 알아서 해준다.

import { useSuspenseQuery } from '@tanstack/react-query';

function UserProfile({ userId }) {
  const { data: user } = useSuspenseQuery({
    queryKey: ['user', userId], // 이 키로 Promise를 캐싱
    queryFn: () => fetchUser(userId),
  });
  return <UserCard user={user} />;
}

data가 항상 정의되어 있음이 보장된다. 로딩 상태는 Suspense가, 에러 상태는 ErrorBoundary가 처리하기 때문이다. 서론에서 보여준 보일러플레이트 문제를 라이브러리 수준에서 완전히 해결한 것이다.

2.3. [Suspense를 트리거하는 다른 방법들]

지금까지는 use()로 Promise를 throw해서 Suspense를 트리거했다. 서론에서 "Suspense는 Children에 필요한 코드와 데이터를 로딩할 때까지 Fallback을 보여주게 된다."라고 말했는데 데이터를 기다리는 방법은 알아봤으니, 이제 코드를 기다리는 방법이다.

React가 처음부터 공식 지원한 방식, React.lazy다.

import { lazy, Suspense } from 'react';

// 이 컴포넌트의 코드는 실제로 렌더링될 때까지 로드되지 않음
const HeavyEditor = lazy(() => import('./HeavyEditor'));

function App() {
  return (
    <Suspense fallback={<div>에디터 로딩 중...</div>}>
      <HeavyEditor />
    </Suspense>
  );
}

React.lazy의 동작은 use()와 동일한 개념이다. 그전에 import()에 대해 짚고 넘어가자.

import()는 JavaScript 언어 표준(ES2020)에 추가된 문법인데, 평소에 쓰는 static import와 달리 함수처럼 호출하고 Promise를 반환한다. 번들러(Webpack, Vite)는 import() 구문을 보고 해당 파일을 별도 청크로 분리한다.

static import → 빌드 타임에 하나의 번들로 합쳐짐
import() → 런타임에 필요할 때 별도 파일로 요청

React.lazy는 이 import()가 반환하는 Promise를 받아서 Wakeable로 throw하는 래퍼다. 컴포넌트 코드가 아직 로드되지 않았으면 Promise를 throw한다. React가 이것을 Wakeable로 판별하고, 가장 가까운 Suspense 경계의 fallback을 보여준다. 다운로드가 완료되면 ping과 retry가 React를 깨우고 컴포넌트를 렌더링한다.

여기서도 알 수 있듯이 Suspense는 하나의 통신에 기반하고, 방식은 Wakeable을 throw하는 것이다.

[결론]

어떻게 Suspense는 비동기 상태를 읽어 들이는 것일까? 아무 비동기 상태나 되는 것인가? 아무 비동기 상태나 되는 것이 아니다. Suspense는 Wakeable을 throw하는 것 하나에 기반한다. use()든, React.lazy든, TanStack Query의 useSuspenseQuery든 결국 내부에서 하는 일은 같다. Wakeable을 throw하고, React가 그것을 잡아 fallback을 보여주고, resolve되면 다시 렌더링한다.

JS 배열을 순회하는 함수들의 내부구조를 뜯어보자

gamzamandu — Wed, 29 Apr 2026 23:58:14 +0900

[서론]

전제

JS 코드는 그냥 실행되지 않는다. 브라우저와 Node.js 환경에서 JS는 V8 엔진 위에서 동작한다. V8은 JS 코드를 단순히 해석하는 데 그치지 않고, 실행 중에 코드를 분석하고 최적화한다. 같은 코드라도 V8이 어떻게 판단하느냐에 따라 실행 속도가 달라진다.

이 글은 그 최적화 방식을 따라가며 forEach, map, filter, reduce의 내부구조를 이해하는 것을 목표로 한다. 이 네 가지 함수는 배열 전체를 순회하며 콜백을 실행한다는 공통 구조를 가지면서도, 내부에서 하는 일이 각자 다르다. Elements Kind가 무엇인지, 이터레이터 메서드가 왜 이런 형태로 설계됐는지, 그리고 각 함수가 내부에서 실제로 어떻게 다르게 동작하는지를 다룬다.

여기서 다루는 내용은 V8 엔진 기준이다.

SpiderMonkey(Firefox), JavaScriptCore(Safari) 같은 다른 엔진은 내부 구현이 다를 수 있다. 다만 배열을 효율적으로 처리하기 위한 핵심 원리는 엔진을 막론하고 유사하다.

[본론]

내부구조를 다루기 앞서, 아래 문제를 보자.

100,000개 요소로 완전히 채워진 배열에서, 동일한 더하기 연산 x+1을 map()과 forEach()로 실행할 때 어느 쪽이 더 빠를까?

const arr = Array(100000).fill(0);

arr.map(x => x+1); 
arr.forEach(x => x+1);

forEach 방식이 18.907ms, Map 방식이 41.168ms로 forEach가 약 2배 정도 더 빠르다. 내부적으로 어떤 차이가 있길래 이런 문제가 발생할까?

1. [Elements Kind]

V8은 배열을 연산할 때 단순히 인덱스를 조회하는 것이 아니라, 배열의 요소들이 어떤 종류들인지 파악하는 Element Kind 과정을 거친다. 이 작업을 잘 이해하면 특정 상황에서 배열의 처리 속도가 달라지는 이유를 알 수 있다.

[배열은 6가지 조합으로 분류된다.]

V8은 배열을 두 가지 축으로 분류한다.

- 첫번째 축은 배열에 구멍(Hole)이 있는지 여부이다. 구멍이 없으면 Packed, 있으면 Holey이다.

- 두번째 축은 요소의 타입이다. 작은 정수면 SMI(Small Integer), 부동소수점이면 Double, 그 외 문자열은 Elements로 분류된다.

첫 번째 축(2개), 두 번째 축(3개)의 조합으로 배열은 6가지로 분류된다.

[1, 2, 3]        // PACKED_SMI_ELEMENTS
[1.1, 2.2, 3.3]  // PACKED_DOUBLE_ELEMENTS
[1, 'a', {}]     // PACKED_ELEMENTS

[1, , 3]         // HOLEY_SMI_ELEMENTS
[1.1, , 3.3]     // HOLEY_DOUBLE_ELEMENTS
[1, , 'a']       // HOLEY_ELEMENTS

V8이 이렇게 분류한데는 이유가 있을 것이다. 그 이유를 설명하겠다.

[첫 번째 축, Packed와 Holey]

첫 번째 축에 소개된 Hole에 대한 개념을 다루겠다. 아래 코드를 보자.

두 배열을 모두 arr [1]으로 읽으면 undefined가 나온다. 겉보기엔 모두 undefined로 동일해 보인다.

const holey         = [1, , 3];       // hole
const withUndefined = [1, undefined, 3]; // 명시적 undefined

in 연산자로 "1번 인덱스에 값이 존재하는가"를 물어보면 대답이 달라진다. 대답은 "holey에서는 값 자체가 존재하지 않는다"이다.

1 in holey          // false — 인덱스 1에 값 자체가 없음
1 in withUndefined  // true  — 인덱스 1에 undefined라는 값이 있음

왜 같은 인덱스인데 []와 in의 결과가 다른 걸까.

in은 <이 인덱스에 값이 존재하는가>라는 물음이다.

hole은 그 자리에 값을 할당한 적이 없으니 false, 명시적으로 undefined를 넣은 건 값이 존재하니 true다.

arr[1]은 <값을 달라>는 요청이다.

V8은 인덱스 1을 확인하고, 없으면 프로토타입 체인을 타고 올라가고, 거기도 없으면 undefined를 반환한다. hole이든 명시적 undefined든 최종적으로 undefined가 나오니 구분이 안 된다.

여기서 hole의 정체가 드러난다. hole은 "undefined가 저장된 셀"이 아니라 "값 자체가 할당되지 않은 셀"이다.

이 차이가 V8에게 중요한 이유는, hole이 있는 배열을 순회할 때 JS 스펙상 각 인덱스마다 HasProperty 체크를 수행해야 하기 때문이다. 값이 없으면 프로토타입 체인을 타고 올라가 찾아봐야 한다는 보장을 지켜야 한다. V8은 이 가능성을 배제할 수 없다.

~~(프로토타입에 대한 설명은 다음에 자세히 다뤄보겠다.)~~

반면 Packed 배열은 모든 인덱스에 값이 보장되므로 HasProperty 체크 자체가 필요 없다.

그래서 V8은 Packed와 Holey를 구분한다. hole이 없는 배열에서 불필요한 탐색 비용을 없애기 위해서다.

[두 번째 축, 요소의 타입]

앞서 설명했듯 V8은 요소의 타입을 세 가지로 구분하고 있다.

1. SMI(Small Integer)는 작은 정수이다. V8은 이 범위의 정수를 포인터 안에 직접 집어넣는다. 별도의 힙 할당이 없고, 읽는 순간 정수값이 나올 수 있다.

2. Double은 부동 소수점이다. 배열 내부에서 64bit Float로 저장된다. 힙 할당은 없으나 SMI보다 두 배의 메모리 공간을 차지한다.

3. Element는 그 외의 모든 것이다. 문자열, 객체가 여기에 속한다. SMI과 Double과는 다르게, 각 요소를 가리키는 포인터를 저장한다. (실제 값은 힙 어딘가에 존재) 따라서 읽을 때마다 포인터를 따라가는 간접 참조가 요구된다.

이 차이가 실제 성능에 영향을 미치는지 의문이 든다면 아래 사례를 확인해 보자.

먼저, 같은 배열을 ForEach로 순회했을 때 비용이다.

[SMI] forEach → 0.758ms
[Double] forEach → 1.183ms
[Elements] forEach → 0.687ms

별 차이가 없을 수 있다. map으로 바꿨을 때는?

[SMI] map → 2.131ms
[Double] map → 5.302ms
[Elements] map → 1.948ms

Double이 갑자기 튀어 오른다. forEach와 대비했을 때 4.5배 차이이다. 이유는 Map은 결과 배열을 새로 만들기 때문이다.

100,000개의 배열을 초기화할 때 SMI보다 두 배의 메모리를 쓰게 된다.

V8이 타입을 세 가지로 구분하는 이유가 바로 여기에 있다. 각 타입에 맞는 메모리 레이아웃을 선택해서 읽기 비용을 줄이는 것이다.

2. [Elements Kind의 특징]

이를 통해 V8은 Kind가 구체적일수록 더 공격적으로 최적화하게 된다. 예로 PACKED_SMI_ELEMENTS은 모든 요소가 정수임이 보장되므로 타입 체크를 건너뛰고 연속된 메모리를 직접 읽는다. HOLEY_ELEMENTS는 매 인덱스마다 구멍이 있는지를 확인하고, 구멍이면 HasProperty 체크를 실행한다.

그럼 이 Elements Kind는 어느 시점에 결정이 될까? Kind는 배열이 생성되는 순간 결정된다. 이후 요소가 추가되거나 변경될 때 재평가한다.

const a = [1, 2, 3];       // 생성 시점에 PACKED_SMI_ELEMENTS
const b = [1, 2, 'hello']; // 생성 시점에 PACKED_ELEMENTS
const c = [];              // 생성 시점에 PACKED_SMI_ELEMENTS (비어있어도)

중요한 점은 이 전환은 단방향이다. pop()으로 요소를 제거해서 배열이 다시 정수만 남아도 Kind는 되돌아오지 않는다.

const a = [1, 2, 3];  // PACKED_SMI_ELEMENTS
a.push(1.5);           // PACKED_DOUBLE_ELEMENTS
a.push('x');           // PACKED_ELEMENTS
a.pop(); a.pop();      // 다시 [1, 2, 3]이 됐지만 — 여전히 PACKED_ELEMENTS

V8은 Kind를 되돌리기 위해 배열 전체를 다시 스캔하느니, Kind를 유지하는 편이 낫다고 판단한다.

그럼 아래 arr의 Elements Kind는 어떻게 평가될까? 0으로 꽉 찬 정수 배열이니 PACKED_SMI_ELEMENTS이지 않을까?

const arr = Array(100000).fill(0);

정답은 HOLEY_SMI_ELEMENTS이다. Array(n)은 크기만 지정된 빈 배열을 만드는 순간 Holey로 출발하기 때문에, 이후 fill(0)으로 값을 전부 채워도 떠나간 Kind는 되돌아오지 않는다. 매정한 놈이다.

Elements Kind를 정리하자면

1. V8은 배열의 hole 여부, 요소의 타입으로 배열을 6가지 종류로 분류한다.

2. 분류된 6가지 종류로 연산의 차이를 주어, 최적화를 진행한다.

3. Kind는 배열이 생성되는 순간 결정되고, 요소가 추가/변경될 때 재평가된다. 단, 이 전환은 단방향이라 한 번 강등되면 되돌아오지 않는다.

하지만 이것만으로 도입부의 질문이 완전히 설명된 것은 아니다. 이 파트에서는 배열이 어떻게 분류되는 것인지 설명한 것이다.

말했듯이 Array(100000).fill(0)은 HOLEY_SMI 배열이다. 이 배열을 순회하는 어느 함수든 HasProperty 비용을 치르게 된다.

이제 이 분류 위에서 각 함수가 어떻게 다르게 동작하는지 알아볼 필요가 있다.

3. [이터레이터]

본론으로 들어가기 전에 한 가지 질문을 먼저 던져야 한다. forEach, map, filter, reduce는 왜 이런 형태로 설계됐을까?

JS가 이 네 함수를 도입하기 전, 배열 순회는 전부 for 루프였다.

const data = [1, 2, 3, 4, 5];

// 짝수만 골라서 2배로 — for 루프
const result = [];
for (let i = 0; i < data.length; i++) {
  if (data[i] % 2 === 0) {
    result.push(data[i] * 2);
  }
}

이 코드에는 두 가지 관심사가 섞여 있다. i++, i < data.length 같은 순회 로직과, % 2 === 0, * 2 같은 비즈니스 로직이다.
코드가 길어질수록 이 둘이 뒤엉켜 읽기 어려워진다. 그리고 매번 개발자가 직접 순회를 제어해야 하므로 off-by-one 에러 같은 실수도 생긴다.

ES5에서 forEach, map, filter, reduce가 도입된 건 이 문제를 해결하기 위해서다. 핵심 아이디어는 순회 제어권을 개발자에서 V8런타임으로 위임하는 것이다.

아래 예시를 보자. 개발자는 "무엇을 할지"만 콜백으로 넘긴다. "어떻게 순회할지"는 V8런타임이 책임진다.
이 패턴을 내부 이터레이터라고 한다. 소비자(콜백)가 순회를 제어하지 않고, 함수 내부에서 순회가 이루어진다.

data.filter(x => x % 2 === 0).map(x => x * 2);

(반대 개념인 외부 이터레이터는 ES6의 Symbol.iterator와 for...of다. 소비자가 직접 next()를 호출하며 순회를 제어한다.)

내부 이터레이터 방식이 단순히 가독성만 높이는 게 아니다. 순회 제어권이 함수 안에 있으므로, 앞서 다룬 Elements Kind 같은 배열 상태를 함수가 직접 활용해 최적화할 수 있다

이제 네 함수의 내부를 뜯어볼 준비가 됐다.

4. [각 함수의 내부구조]

forEach, map, filter, reduce는 배열의 이터레이터 메서드다. 배열을 순회하면서 각 요소에 콜백을 실행한다는 공통점이 있지만, 순회 외에 각자가 하는 일이 다르다.

먼저 네 함수의 순회 비용을 나란히 놓아보자. 배열은 도입부와 동일한 Array(100000).fill(0)이다.

forEach          → 0.732ms
map              → 2.078ms
filter(전부통과) → 5.157ms
filter(전부탈락) → 0.734ms
reduce           → 0.650ms

수치가 제각각이다. 같은 HOLEY_SMI 배열을 순회하는데 왜 이렇게 다를까. 각 함수가 순회 외에 무엇을 더 하는지가 다르기 때문이다.

[forEach]

forEach는 각 인덱스에서 콜백을 실행하고 끝이다. 결과를 저장하지 않고, 새 배열도 만들지 않는다. 반환값은 항상 undefined다.
네 함수 중 순수 순회 비용에 가장 가깝다.

[map]

forEach와 구조가 거의 같지만 한 가지가 다르다. 결과를 담을 배열을 새로 만들어야 한다.

const result = new Array(len);       // ① 결과 배열 미리 할당
for (let k = 0; k < len; k++) {
  if (k in arr) {
    result[k] = fn(arr[k], k, arr); // ② 콜백 실행 + 결과 저장
  }
}
return result;

빈 배열 100,000개짜리를 할당하는 비용만 약 1.3ms다. forEach(0.732ms)와 map(2.078ms)의 차이가 거기서 온다.
이것이 도입부 질문의 완전한 답이다.

Elements Kind → HOLEY_SMI 배열이라 매 인덱스마다 HasProperty 체크가 붙는다
내부 동작 → map은 거기에 결과 배열 할당 비용이 얹힌다

forEach가 빠른 이유는 HOLEY 체크를 덜 해서가 아니다. 둘 다 똑같이 체크한다. map이 느린 건 결과 배열을 새로 만들기 때문이다.

여기서 Elements Kind가 다시 개입한다. map이 만드는 결과 배열의 Kind는 입력 배열의 Kind를 따른다. SMI 배열을 순회하면 결과도 SMI 배열로 할당되고, Double 배열을 순회하면 결과도 Double 배열로 할당된다. Double은 요소 하나당 SMI의 두 배 메모리를 쓰기 때문에, 100,000개짜리 결과 배열을 만드는 비용도 두 배로 뛴다. 앞서 측정한 [Double] map → 5.302ms가 [SMI] map → 2.131ms의 두 배를 넘는 이유가 여기에 있다. forEach는 결과 배열을 만들지 않으로 [Double] forEach → 1.183ms에서 이 차이가 나타나지 않는다.

[filter]

filter가 유독 느린 이유는 결과 배열의 최종 크기를 순회 전에 알 수 없다는 데 있다. map은 입력과 출력 크기가 항상 같으니 미리 할당할 수 있다. filter는 불가능하다.

V8은 이 문제를 이렇게 해결한다. 일단 원본과 같은 크기로 결과 배열을 할당하고, 조건을 통과한 것만 채운 뒤, 마지막에 실제 크기로 줄인다.

filter(전부 통과) → 5.157ms   ← 원본 크기 할당 + 전체 복사
filter(전부 탈락) → 0.734ms   ← 원본 크기 할당 + 복사 없음

전부 통과시킬 때가 가장 느리다. 반대로 전부 탈락시키면 복사 비용이 없어 forEach 수준으로 내려간다. filter는 결과가 적을수록 빠르다.

filter에는 한 가지 특성이 더 있다. map과 달리 hole을 제거한다.

const holey = [1, , 3, , 5];

holey.map(x => x);        // [1, empty, 3, empty, 5] — hole 유지
holey.filter(x => true);  // [1, 3, 5]               — hole 사라짐

map은 hole을 만나면 그 자리를 비워두고 결과 배열에도 그대로 전파한다. filter는 조건을 통과한 요소만 순서대로 쌓으므로 hole이 결과에 포함될 수 없다. filter의 결과 배열은 항상 PACKED로 출발한다.

앞서 Elements Kind의 전환은 단방향이라고 했다. 한 번 HOLEY가 되면 되돌아오지 않는다고. filter는 그 원칙의 실용적인 우회로다. HOLEY 배열을 의도치 않게 들고 있다면 filter(x => x != null) 한 번으로 hole을 걷어내고 PACKED 배열을 새로 얻을 수 있다.

[reduce]

reduce의 순회 비용은 forEach와 거의 같다. 새 배열을 만들지 않고, 반환값은 누산기 하나뿐이다.

reduce는 누산기를 어떻게 쓰냐에 따라 비용이 크게 달라진다.

number 누산기는 타입이 처음부터 끝까지 고정된다. V8 입장에서는 누산기가 사실상 PACKED_SMI나 PACKED_DOUBLE처럼 동작하는 셈이다. 타입이 보장되니 콜백 안의 연산을 타입 특화 코드로 컴파일할 수 있고, 매 iteration마다 타입 체크를 건너뛴다.

array 누산기에 push를 쓰는 건 매 iteration마다 배열 쓰기 연산이 추가된다. spread로 새 배열을 만드는 건 매 iteration마다 배열 전체를 복사하는 O(n²) 패턴이다.

[결론 : V8최적화의 산물]

지금까지 살펴본 것처럼, forEach, map, filter, reduce는 배열을 순회한다는 공통점 아래에서 각자 다른 구조로 동작한다.

V8은 배열을 Elements Kind로 분류해 순회 경로를 결정한다. 같은 코드라도 배열이 어떻게 생성됐는지, 어떤 타입의 요소를 담고 있는지에 따라 V8이 선택하는 실행 경로가 달라진다. 그 위에서 각 함수는 순회 외에 하는 일이 다르다. map은 결과 배열을 만들고, filter는 크기를 모른 채 할당하고 줄이고, reduce는 누산기 하나만 들고 돈다. forEach는 그 모든 비용이 없다.

TSC는 Type Narrowing을 어떻게 처리하는 걸까

gamzamandu — Tue, 28 Apr 2026 17:40:05 +0900

[서론 : TSC에 대한 소개 그리고 Type Narrowing]

TSC는 무엇인가?

TSC는 TypeScript Complier로, TypesScript 코드를 JavaScript로 변환해 주는 컴파일러이다. TSC는 타입 검사를 통해 코드 안정성을 보장하면서도 런타임에서 실행 가능한 JS 코드를 생성한다. TSC는 tsconfig.json를 기반으로 소스 파일들의 의존성 그래프를 구축하고 전체 컴파일 콘텍스트를 관리하는 Program을 실행하게 된다.

TSC는 크게 소스코드를 키워드/연산자 단위로 토큰화하는 Scanner, 토큰화된 SyntaxKind를 AST(추상구문트리)로 변환하는 Parser, AST Node를 토대로 타입정보(선언과 참조)를 매핑하는 Binder, 이렇게 만들어진 Symbol Table을 토대로 타입 일치 여부를 검사하는 Type Checker, 마지막으로 JS소스와 .d.ts 파일을 생성하는 Emitter 단계로 나뉜다.

Type Narrowing는 무엇인가?

먼저 Type Narrowing에 대해 간략하게 소개한다면, TypeScript에서 타입 내로잉(Narrowing)은 유니언 타입(union type)처럼 여러 가능한 타입 중 하나로 범위를 좁혀 더 구체적인 타입으로 만드는 과정이라고 할 수 있다.

function processInput(input: string | number) {
  if (typeof input === "string") {
    // input은 이제 string 타입으로 좁혀짐
    return input.toUpperCase();
  } else {
    // input은 이제 number 타입으로 좁혀짐
    return input.toFixed(2);
  }
}

위 예시를 보면 ProcessInput의 인자인 input은 string과 number를 가질 수 있는 union type이다. typeof, in, instanceof 같은 type guard를 통해 string과 number를 구분하며 타입이 자동으로 좁혀진다. (이래서 타입 좁히기라고 부른다.)

본문의 요지는 이것이다. TSC에서 Type Narrowing는 어떻게 처리하는 것일까?

Type의 유효성을 검증하고, 필요한 경우 더 구체적인 타입으로 좁혀나가는(Narrowing) 작업이 수행되는 곳은 Type Checker 단계이다.

Type Checker 단계에서 타입을 검사하는 방법을 더 파보도록 하자.

[본론 : TSC는 Type Narrowing을 어떻게 처리하는 걸까]

간단한 Type Narrowing을 다루는 소스코드를 Type Checker 과정까지 전개해보겠다.

let x: string | number = 123;
if (typeof x === 'string') {
  x.toUpperCase();
}

1. [Scanner & Parser]

앞서 설명했듯이, 소스코드는 Scanner 단계에서 토큰 단위로 분해되고 Parser 단계에서 AST(추상구문트리)로 변환된다.

AST는 소스코드에서 세미콜론이나 괄호 같은 사소한 문법 요소는 생략해 핵심 구조만 남겨 해석을 유연하게 할 수 있게 도와준다.

TypeScript의 AST로 변환한다면 다음과 같아진다.

2. [Binder]

자, 이제 Binder에서 AST의 정보를 토대로 Symbol Table를 생성해 보겠다.

AST Node를 순회하면서 VariableDeclaration(변수선언) 노드를 발견한다. 해당 노드의 Identifier("x") 식별자의 이름을 마주한다.

현재 스코프에 식별자의 이름을 키로 한 메타데이터를 Symbol Table 안에 구성하게 된다. 이 정보를 토대로 Checker가 x의 타입은 string | number였군. 이렇게 알 수 있는 것이다.

이제 중요한 지점이 나온다. 그럼 <Type Narrowing은 어떻게 이루어지는 것인가?>

이런 제어 흐름을 바뀌는 지점들을 저장하기 위해, 실행 경로를 분석하여 각 지점의 타입을 추론하는 Control Flow Analysis(과정을 제어 흐름 분석)이라고 한다. 이 과정 덕분에 TSC가 타입이 분기되는 지점에서도 빈틈없이 타입을 추적할 수 있는 것이다.

다시 TSC를 전개하러 가보자.

Binder는 AST를 조회하다가 if문, typeof, instanceof 같은 타입의 범위를 좁히는 지점을 만나면 Flow Graph를 생성하게 된다.

이렇게 Flow Node가 구성되는 것이다.

좀 더 복잡적인 상황에 대한 Flow Node가 궁금하다면 참고하라.

조건문	IfStatement	test 조건의 true/false 분기 생성.
조건 연산자	ConditionalExpression	? : 삼항 연산자. 분기 생성.
반복문	WhileStatement, ForStatement	루프 진입/탈출 시 타입 재계산 필요.
논리 연산자	BinaryExpression	&&, \|\| 연산자. 단락 평가(Short-circuit)로 인한 타입 내로잉.
타입 가드	BinaryExpression	typeof, instanceof 비교식. Flow Node의 핵심.
분기점	SwitchStatement	case 별로 타입 흐름 분기.

3. [Checker]

자 이제 코드의 구조를 위한 Symbol Table과 타입의 흐름을 위한 Flow Node가 구성되었다. 이것을 Checker가 해석만 하면 될 일이다.

Checker가 AST를 다시 순회하며 타입 검사를 수행할 때, 각 노드에서 다음과 같은 과정을 거친다.

1. [근본 타입 확인]
Checker는 현재 방문 중인 식별자(x)를 만났을 때, Symbol Table을 조회하여 x가 string | number로 정의되어 있다는 기본 정보를 먼저 확보한다.

2. [타입 내로잉]
Checker가 if (typeof x === 'string') 블록 안으로 들어간다. (이때 Checker는 Flow Graph를 참조한다.)
Flow Graph는 해당 블록이 typeof x === 'string' 조건이 true인 경로임을 알려준다. Checker는 이 정보를 바탕으로, Symbol Table에 있던 원래 타입(string | number)을 해당 블록 안에서만 string으로 좁힌다.

3. [타입 안전성 검증]
이제 블록 내부의 x.toUpperCase()를 만난다.
Checker는 좁혀진 타입(string)을 기준으로 .toUpperCase() 메서드가 존재하는지 검사한다.

string 타입에는 해당 메서드가 존재하므로, 타입 체커는 이를 "안전함"으로 통과시킨다. 만약 블록 밖에서 호출했다면, 여전히 string | number로 남아있어 에러를 뱉었을 것.

[결론 : Type Narrowing이 가능한 건 Control Flow Analysis 덕분]

지금까지 살펴본 것처럼, 다양한 분기 조건에서도 타입을 정확하게 추론하는 이유는 제어 흐름 분석(Control Flow Analysis, CFA) 덕분이다.

TSC는 Binder를 통해 변수의 선언과 범위를 담은 Symbol Table을 구축하고, 코드의 실행 경로마다 타입이 어떻게 변하는지 추적하는 Flow Graph를 설계하고 Type Checker가 이 두 가지를 결합한 것이다.

사실 이 과정을 통해 Type Narrowing 뿐만 아니라. Type Assertion이 어떻게 동작하는지도 이해할 수 있다.

프로젝트 API 호출수를 최대 80% 줄인 이야기

gamzamandu — Mon, 27 Apr 2026 15:07:00 +0900

[서론 : 프로젝트에 대한 소개]

해당 프로젝트는 "납득 가능한 외래어 순화 인공지능 서비스"라고 설명할 수 있겠다.

AI시대가 되면서 우리나라에는 외래어가 물밀듯이 들어오고 있다. 최근 설문에 따르면 "신문·방송에서 사용하는 말의 의미를 몰라 곤란하다”는 응답이 89%에 달할 만큼 외래어 사용이 증가하고 있다. 국민들의 알 권리가 저하되기 때문에 정부에서는 신문이나 공문서에서 우리말 사용을 지향하는 "공공언어" 사용을 권장한다. 그러나 "공공언어"를 만드는 주체인 국립국어원이 제안한 다듬은 말은 "다듬은 말이 맥락에 맞지 않아 사용하기 힘들다.", "다듬은 말이 납득이 되지 않는다."라는 반응으로 사용되지 않는다.

이러한 문제점을 기술로 해결할 수 없을까하는 고민에서 프로젝트는 시작되었다. 사용자들의 다듬은 말에 대한 선호도를 수집한 뒤 그것을 인공지능이 판단하여 순화어를 제안하는 아이디어이다.

본문에서는 프로젝트의 기술적인 어려움에 대한 해결과정을 다루고 있다.
해당 인공지능에 대한 연구가 궁금하다면 팀의 AI 책임자인 권민재 군이 쓴 논문을 구경해 주시길 바란다.

https://www.dbpia.co.kr/journal/articleDetail?nodeId=NODE12579655

인공지능 기반 외래어 감지 및 순화어 추천 | DBpia

권민재 | 한국정보기술진흥원 학술지 | 2026.3

www.dbpia.co.kr

[본론]

0. 무슨 일을 담당했는가

해당 프로젝트에서 나는 기획, PM, 디자인, 프론트, 데이터 수집 쪽을 담당하였고, 본 글에서는 <순화 API 호출을 줄이는 과정>에서의 트러블슈팅을 다룬다. 먼저 프론트 화면에서 수행해야 할 과정은 다음과 같다.

<문서편집과 문서의 외래어를 순화해주는 화면>

1. 문서편집기의 외래어는 하이라이트된다.
2. 오른쪽 사이드바에는 감지된 외래어와 그 외래어에 대한 다듬은 말이 추천된다.
3. 다듬은 말에 대한 제안을 승인하면 문서편집기에서 그 단어가 다듬을 말로 변경된다

1. API 호출이 멈추질 않는다.

먼저 초안은 문서에디터가 수정되면 순화 요청을 보내는 것이다.

useEffect(()=>{
	순화API호출(documentContent)
},[documentContent])

당연히 이렇게 하면 한 글자 수정할 때마다 순화 요청이 날아가는 참극이 발생할 것이기에 "디바운스" 도입을 선택했다.

디바운스(Debounce)는 프로그래밍에서 연속적으로 발생하는 이벤트를 그룹화해 불필요한 호출을 방지하는 기술이다.

2. useEffect를 활용하여 디바운스를 구현해 보자.

useEffect는 컴포넌트 렌더링 후 부수적인 효과를 실행하는 Hook인데, 내부적으로는 React가 Fiber 노드의 updateQueue에 Effect를 저장해 두고, DOM 커밋 단계 이후 다음 이벤트 루프에서 실행된다. 이 함수는 하나의 useEffect 버전이 존재해야 하므로 새로운 버전의 변경이 호출되면, 이전 버전의 useEffect는 제거된다. 이때 제거된 useEffect에는 제거될 때 액션을 취할 수 있는데, 여러분들이 잘 아는 Clean-up이다. 단순히 컴포넌트가 Unmount 될 때 트리거된다고 생각할 수 있지만, 모든 것이 React Fiber로 이루어진 React세계의 관점에서는 Component가 unmount 되면서 (Component를 React에 등록한 Fiber의 UpdateQueue로 등록되어 있던) useEffect 인스턴스가 자체가 unmount 되기 때문에 Clean-up이 동작하는 것이지 Component의 unmount만 관심사로 둔 것이 아니다.

이걸 활용하면 디바운스를 쉽게 구현할 수 있다.

useEffect(() => {
  const timeout = setTimeout(() => {
    순화API호출(documentContent);
  }, 3000);

  return () => clearTimeout(timeout);
}, [documentContent]);

문서가 변경되면 useEffect 안에서는 setTimeout으로 3000ms 뒤에 콜백함수가 실행된다. 여기서 새로 변경이 되면 기존 useEffect 인스턴스는 Clean-up을 통해 setTimeout이 해제됨으로 실행되지 않는다. 결론적으로 언제나 3000ms 후 아무 변경도 하지 않아야 API가 호출되는 디바운스를 만들 수 있다.

여기서 3000ms로 잡은 이유는 Google Docs나 Notion 같은 문서편집기가 대게 2~3초의 디바운스를 적용하는 데에서 착안했다.
~~써봤을 때도 가장 좋다.~~

3. 아직도 불필요한 API 호출은 존재한다.

디바운스를 도입했음에도 아직 불필요한 호출은 존재한다. 말하자면 이런 상황이다.

"수많은 문장들 중에 한 문장만 수정했는데, 변경하지 않은 문장들까지 순화 요청이 되고 있어요."

뭐? 변경이 안 됐는데 요청에 포함되고 있다고? 변경을 추적해야겠군. 뭐? 변경을 추적한다고? 이거 완전 Git이잖아.

버전 관리의 정수 Git

4. 변경점만 찾아내는 코드를 만들어보자.

변경점을 찾아내기 위해서는 먼저 변경의 단위를 정의하는 것이 필요할 것이다. Git이 파일 단위로 변경사항을 추적하듯, 이 시스템에서도 문장을 추적의 기본 단위로 삼았다. 고맙게도 문서편집기 구현에 사용한 CKEditor 같은 경우는 내용을 블록 단위로 분리하는 구조를 가지고 있다. 해당 블록을 변경의 단위로 삼았다.

예를 들면 h1으로 쓴 블록과 p로 쓴 블록이 분리되어 있기 때문에 해당 블록을 한 문장의 단위로 가정하겠다는 것이다.

변경의 단위를 정했겠다. 이제 버전을 관리해야 할 것이다. 버전 관리는 간단하게 2-State구조를 채택했다. 전 버전과 현재 버전만 관리하겠다는 것이다. 버전 비교를 위해서 좋은 방법도 많겠지만 "deep-diff" 라이브러리를 활용했다. diff(lhs, rhs) 한 번으로 문장이 변경됐는지, 생성됐는지, 제거됐는지, 유지됐는지 알 수 있다.

[
  {
    "kind": "E",
    "path": ["title"],
    "lhs": "오늘은 날씨가 좋아",
    "rhs": "오늘은 날씨가 흐려"
  },
  {
    "kind": "N"       // 새로 추가
    "path": ["newField"],
    "rhs": "추가된 필드"
  }
]

5. 이전 버전의 응답이 지연돼서, 현재 버전과 충돌이 난다.

아직 문서편집기의 최적화는 끝나지 않았다. 상황은 다음과 같다.

v1에서 요청을 보낸다. 그동안 문서가 수집되어, v2 버전에서 요청이 호출되었다.
그런데 v1의 응답값이 이제야 돌아오고 있다! v2의 수정사항과 충돌이 났다.

비교적 간단한 문제이다. 응답값이 버전에 대한 정보를 같이 반환해 주면 된다.

이 "순화 응답은 v1를 지칭하고 있습니다."
음 현재는 v3이기 때문에 v1는 적용하지 않고 폐기해야겠군.

6. 유저가 대용량 텍스트를 복붙 하면 어떻게 될 것인가?

디바운스를 통해 장기적인 편집의 요청을 최소화했다. 하지만 단기적인 상황에서는 어떻게 할 것인가? 유저가 1000자의 텍스트를 복사/붙여 넣기를 한다면? 뭐라도 최적화하고 싶다.

우리 서비스의 순화 프로세스는 다음과 같다. 서버로부터 응답이 돌아올 때까지 유저 화면상에는 스피너가 돌고 있을 뿐이다.

[순화 요청이 필요함] --[서버로 전송]-> [외래어 감지] -> [외래어가 감지된 문장만 순화 AI 적용] -> [반환]

좋은 아이디어가 떠올랐다. 외래어 감지를 클라이언트 측에서 실행시키자.

우리 팀의 외래어 감지 모델은 LSTM 경량 모델이다. (이것도 어떻게 했는지 궁금하다면 여길 구경하길 바란다.)

외래어 감지 모델은 클라이언트 측으로 이전시키면

- 클라이언트 입장: 외래어가 감지되며 화면상에 붉은 하이라이트 먼저 표시되며 몇 초 후에 순화어가 반환됨.

- 서버 입장: 외래어가 감지된 문장들만 서버에 오기 때문에 훨씬 좋음.

따라서 서버의 LSTM(TensorFlow.py)을 클라이언트 단에서 TenserFlow.js로 실행하였다.

(모델을 Tensor Flow SavedModel로 변환 후 tfjs_converter 사용한 뒤 브라우저에서 호출했습니다.)

여담) 외래어 감지 모델은 정말 경량 모델이라 실행되지 않는 컴퓨터는 없을 것이긴 하나,
클라이언트 환경을 체크해서 외래어 감지 모델의 실행을 백엔드 측에서 실행해 주는 Fail-Safe 대안을 마련해 두는 것도 좋을 것 같다.

7. 개선된 성능을 측정해 보자.

이론상 개선된다는 것을 알았지만, 개선된 버전이 얼마나 효율적으로 API를 줄였는지 측정하고 싶다. 현업의 개발자라면 A/B테스트를 통해서 실제 시나리오를 검증하고 정량화할 수 있으나, 사용자가 없는 가난한 개발자라면 실제상황을 재현해야 할 것이다.

목표는 A상황과 B상황 모두 동일한 상황에서 API 호출수를 측정하고 싶다. 인간이 아무리 노력한들 똑같은 문서 편집을 두 번 재현하는 능력은 무리이다.

"클라이언트의 클릭, 입력 이벤트를 모조리 기록할 수 없을까?"

감사하게도 이미 이것을 한 개발자가 있다. 클라이언트의 텍스트 입력과 같은 사용자 행동을 JSON으로 저장해 주고 실행까지 해주는

rety 라이브러리가 있다. 이것을 이용해 문서편집 시나리오 10개 정도를 저장하고 개선 전 버전(디바운스까지 적용)과 개선 후 버전(모든 개선 적용)에 실행시켰다. 대용량 텍스트 복사/붙여 넣기 같은 상황을 제외한 나머지 시나리오에서 모두 60% 이상의 감소를 이끌어냈다.