이 편에서 만드는 파일

이 편은 개념 편이라 새로 만드는 파일이 없습니다. 이미 갖고 있는 expense-tracker/ 프로젝트를 열어 점검만 합니다. 새 폴더 준비와 버전 업그레이드는 02편에서 진행합니다.

개념 정리

typescript_fundamentals에서 여기까지 왔다

expense-tracker는 18편에 걸쳐 아래 순서로 만들어졌습니다.

지금 expense-tracker는 거래를 추가·수정·삭제·필터·정렬할 수 있고, 카테고리별 합계와 예산 경고를 보여주며, npm run verify가 타입 검사·테스트·빌드를 모두 통과하는 상태입니다.

지금까지 쓴 도구와 이번 과목에서 배울 도구의 차이

지금까지 쓴 Partial, Pick, Record, ReturnType 같은 유틸리티 타입은 이미 만들어진 도구를 가져다 쓰는 수준이었습니다. 이번 과목은 그 도구들이 내부적으로 어떻게 만들어지는지, 그리고 필요할 때 직접 만드는 방법을 다룹니다. 조건부 타입으로 타입을 조건에 따라 분기하고, infer로 타입 안에서 다른 타입을 뽑아내고, 템플릿 리터럴 타입으로 문자열 집합을 만들고, 매핑된 타입으로 키 이름 자체를 바꾸는 것까지가 여기서 말하는 타입 레벨 프로그래밍입니다. expense-tracker에 새 화면을 추가하는 대신, 코드 자체의 타입을 더 정확하게 다듬는 데 집중합니다.

런타임-컴파일타임 간극

13편에서 seedRaw as Transaction[]라는 코드를 썼습니다. 이 단언은 컴파일러에게 “이 값은 Transaction[] 모양이다”라고 알려줄 뿐, JSON 파일의 실제 내용이 정말 그런 모양인지는 전혀 검사하지 않습니다. 카테고리 값에 오타가 있어도 npx tsc --noEmit은 통과했습니다. API 응답이나 폼 입력처럼 프로그램 바깥에서 들어오는 값은 전부 같은 문제를 갖습니다. 컴파일타임 타입은 코드를 작성할 때만 보장되고, 런타임에 실제로 들어온 값이 그 모양인지는 별도로 검사해야 합니다. 이 틈을 수동으로 메우는 방법(타입 가드, assertion 함수)과 zod처럼 스키마 하나로 메우는 방법을 12·13편에서 같은 문제로 두 번 풀어보며 비교합니다.

이번 과목 결과물 미리보기

expense-tracker에 아래 세 가지가 새로 생깁니다.

expense-tracker/src/
├── lib/
│   ├── types/     (+, 조건부·매핑·재귀 타입, 브랜디드 ID, pipe 유틸)
│   └── api/       (+, 라우트 타입·엔드포인트 설정·요청 함수·API 클라이언트)
└── schemas/       (+, zod 스키마 — API 응답 검증과 폼 검증을 공유)

lib/types/는 03편부터, lib/api/는 04편부터, schemas/는 13편부터 채워집니다. 완성되면 이 세 폴더가 서로 맞물려, 실제로 값이 들어오는 지점(API 응답, 폼 제출)마다 타입과 검증이 같은 스키마를 공유하게 됩니다.

실습

npm install
npm run verify

> tsc --noEmit
> vitest run
 ✓ tests/createTransaction.test.ts (1)
 ✓ tests/storage.test.ts (2)
 ✓ tests/stats.test.ts (3)
> vite build
✓ built in 401ms

expense-tracker/src/
├── main.ts
├── models/          (expense.ts, index.ts)
├── services/         (storage.ts, stats.ts, createTransaction.ts, budgetRules.ts, index.ts)
├── ui/                (transactionForm.ts, transactionList.ts, statsPanel.ts)
├── lib/               (parsing.ts, signedAmount.ts, arrayUtils.ts, dom.ts)
├── data/              (seedTransactions.json)
└── types/             (date-format-lib.d.ts)

npx tsc --version
npm ls vite vitest

npm run dev

확인

• npm run verify의 세 단계(typecheck, test, build)가 모두 통과한다.
• 브라우저에서 거래 추가·수정·삭제·필터·정렬·카테고리별 합계·예산 경고·최근 거래 표시가 모두 정상 동작한다.
• npx tsc --version이 7.0.0대 버전을 출력한다(정확한 패치 버전은 02편에서 맞춘다).

직접 해보기

1. src/data/seedTransactions.json의 category 값 하나를 존재하지 않는 문자열로 잠시 바꾼 뒤 npm run verify를 실행해, 13편에서 확인했던 것처럼 타입 검사는 여전히 통과하는지 다시 확인하고 원래대로 되돌립니다.
2. src/services/index.ts를 열어 지금 내보내는 값과 타입의 목록을 적어보고, 이번 과목에서 lib/api가 완성되면 이 배럴에 무엇이 더 늘어날지 예상해봅니다.

자주 하는 실수

확인 문제

참고 자료

• TypeScript Handbook — Conditional Types 
• Zod — 공식 문서