JavaScript Temporal API 실전 전환 가이드: Date 객체와 dayjs를 대체하는 ES2026 날짜 처리의 모든 것
Date 객체가 터뜨린 버그, 한 번쯤은 겪어봤을 것이다
예약 시스템 QA를 마치고 배포한 다음 날 아침, 고객 센터에서 "3월 8일 오전 2시 30분 예약이 사라졌다"는 제보가 들어옵니다. 코드를 열어봐도 논리 자체는 멀쩡합니다. 문제는 2026년 미국 동부 시간대 DST(서머타임) 전환 순간에 있었습니다. new Date('2026-03-08T02:30:00') 이 만들어낸 타임스탬프가 실존하지 않는 시각을 가리키고 있었던 것입니다. 서버는 UTC로 저장하고 클라이언트는 로컬로 파싱하면서 생기는 전형적인 타임존 손실 버그입니다.
또 다른 상황을 떠올려봅시다. 국제 정기결제 시스템을 운영하는 팀에서 dateObj.setMonth(dateObj.getMonth() + 1)을 구현했습니다. 1월 31일에 한 달을 더하면 3월 3일이 나옵니다. 2월이 짧기 때문입니다. 이 코드는 수년간 아무 문제 없이 돌아가다가, 특정 윤년 2월에 다시 엉뚱한 날짜를 만들어냅니다. Date 객체는 가변(mutable)이기 때문에 setMonth가 원본 객체를 조용히 덮어씁니다.
2026년, TC39는 Temporal API를 ECMAScript 2026 명세에 정식 포함시켰습니다(Stage 4 승인). 10년 가까운 논의 끝에 탄생한 이 API는 Date 객체의 설계 결함을 구조적으로 해결합니다. 이 글에서는 Date가 프로덕션에서 어떻게 버그를 만드는지 재현 코드로 보여주고, Temporal API의 핵심 타입을 정리한 뒤, dayjs·date-fns에서 Temporal로 마이그레이션하는 실전 경로를 단계별로 짚습니다. 폴리필 번들 전략과 브라우저 지원 현황까지 다루므로, 신규 프로젝트 설계부터 레거시 마이그레이션까지 바로 적용할 수 있습니다.
1. Date 객체가 프로덕션에서 터뜨리는 버그 3가지
1-1. 파싱 불일치: new Date(string)의 배신
MDN 문서(Date.parse — MDN)에 명시되어 있듯, ISO 8601 형식이 아닌 날짜 문자열의 파싱 결과는 구현체마다 다릅니다. 같은 문자열이 Node.js(V8)와 Safari(JavaScriptCore)에서 서로 다른 날짜를 만들어낼 수 있습니다.
// 안티패턴: 비ISO 형식 문자열 파싱
const d1 = new Date('2026/05/11'); // 일부 환경에서 Invalid Date
const d2 = new Date('May 11, 2026'); // 브라우저마다 로컬 타임존 해석이 다름
const d3 = new Date('2026-05-11'); // ISO 날짜만 지정 → UTC 자정으로 파싱(Node.js vs 브라우저 불일치)
console.log(d3.toISOString()); // "2026-05-10T15:00:00.000Z" (UTC+9 기준)
// 날짜만 입력했는데 UTC 기준으로 저장되어 KST에서는 전날 오후 3시가 됨
"2026-05-11"을 new Date()에 넘기면 UTC 자정으로 해석합니다. 한국 사용자 입장에서는 5월 11일 자정이 아니라 5월 10일 오후 3시로 보이는 셈입니다. "오늘 예약"을 저장했는데 "어제 예약"으로 표시되는 버그가 바로 이 지점에서 발생합니다.
1-2. 가변성(Mutability): 원본이 몰래 바뀐다
// 안티패턴: setMonth가 원본 객체를 변경
function addOneMonth(date) {
date.setMonth(date.getMonth() + 1); // 원본 파괴!
return date;
}
const originalDate = new Date('2026-01-31');
const nextMonth = addOneMonth(originalDate);
console.log(originalDate.toISOString()); // "2026-03-03T..." — 원본도 3월이 됨
console.log(nextMonth.toISOString()); // "2026-03-03T..." — 2월 말이 아님
Date 객체는 내부 타임스탬프 하나만 보관하는 가변 객체입니다. setMonth, setHours, setDate 등 모든 setter가 원본을 직접 수정합니다. 방어적 복사(new Date(date.getTime()))를 빠뜨리는 순간 원본이 조용히 오염되고, 이 버그는 대개 훨씬 나중에야 발견됩니다.
1-3. 타임존 부재: getTime() 산술의 함정
// 안티패턴: 밀리초 산술로 날짜 차이 계산
const start = new Date('2026-03-07T23:00:00+09:00'); // KST 오후 11시
const end = new Date('2026-03-09T01:00:00+09:00'); // KST 오전 1시
const diffMs = end.getTime() - start.getTime();
const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
console.log(diffDays); // 1 — 달력 기준 2일 차이인데 1이 나옴
// DST가 있는 미국 동부 시간대라면 결과가 또 달라짐
// America/New_York 기준 DST 전환일에 하루 = 23시간 또는 25시간
getTime() 기반 밀리초 산술은 DST를 전혀 고려하지 않습니다. 하루가 항상 86,400,000ms라고 가정하지만, DST 전환일에 미국은 23시간짜리 날 또는 25시간짜리 날이 존재합니다. 예약·스케줄링·구독 만료일 계산에 이런 코드가 있다면 1년에 두 번 미국 고객에게 틀린 날짜를 보여줄 가능성이 있습니다.
2. Temporal API 핵심 타입 7가지 완전 정리
TC39 Temporal Proposal(tc39.es/proposal-temporal)은 단일 Date 클래스 대신 용도에 맞는 7가지 타입을 제공합니다. 타입을 올바르게 선택하는 것이 Temporal 사용의 출발점입니다.
| 타입 | 타임존 포함 | 시각 포함 | 주요 용도 |
|---|---|---|---|
Temporal.PlainDate | 없음 | 없음 | 생일, 공휴일, 달력 날짜 |
Temporal.PlainTime | 없음 | 있음 | 반복 알람, 업무 시작 시각 |
Temporal.PlainDateTime | 없음 | 있음 | 로컬 일정, 캘린더 이벤트 |
Temporal.ZonedDateTime | 있음 | 있음 | 예약, 스케줄링, DST 안전 계산 |
Temporal.Instant | UTC | 있음 | 로그 타임스탬프, 이벤트 발생 시각 |
Temporal.Duration | 없음 | — | 기간 표현, add/subtract 인자 |
Temporal.TimeZone / Temporal.Calendar | — | — | 타임존·달력 커스터마이징 |
// Temporal.PlainDate — 날짜만 다룰 때
const birthday = Temporal.PlainDate.from('1990-07-15');
console.log(birthday.year, birthday.month, birthday.day); // 1990 7 15
// Temporal.Instant — UTC 절대 시각
const loggedAt = Temporal.Now.instant();
console.log(loggedAt.epochMilliseconds); // 현재 UTC 밀리초
// Temporal.ZonedDateTime — 타임존 완전체
const seoulNow = Temporal.Now.zonedDateTimeISO('Asia/Seoul');
console.log(seoulNow.toString());
// "2026-05-11T10:30:00+09:00[Asia/Seoul]"
// Temporal.Duration — 기간 표현
const twoWeeks = Temporal.Duration.from({ weeks: 2 });
const dueDate = Temporal.PlainDate.from('2026-05-11').add(twoWeeks);
console.log(dueDate.toString()); // "2026-05-25"
PlainDate는 타임존 정보가 없기 때문에 타임존 변환 시 에러를 냅니다. "이 날짜가 어느 지역의 날짜인지"를 강제로 명시해야 하는 구조 덕분에, 타임존을 실수로 뒤섞는 상황을 API 차원에서 차단합니다. ZonedDateTime은 타임존 문자열(Asia/Seoul)을 IANA 형식으로 내부에 보관하여 DST 경계에서도 올바른 날짜·시각을 계산합니다.
3. 불변성과 메서드 체이닝 — 왜 dayjs보다 안전한가
dayjs는 불변성을 표방하지만, 내부적으로는 새 Date 객체를 래핑하는 방식입니다. dayjs 인스턴스 자체는 불변이어도, 타임존 플러그인(dayjs/plugin/timezone)을 빠뜨리면 조용히 로컬 타임존으로 계산합니다.
Temporal은 모든 타입이 언어 레벨에서 완전 불변입니다. add(), subtract(), with(), round() 등 모든 변환 메서드는 새 인스턴스를 반환합니다. 원본을 수정하는 setter가 아예 없습니다.
// Temporal의 완전한 불변 체인
const releaseDate = Temporal.PlainDate.from('2026-05-11');
// with()는 특정 필드만 교체한 새 인스턴스 반환
const nextYear = releaseDate.with({ year: 2027 });
console.log(releaseDate.toString()); // "2026-05-11" — 원본 불변
console.log(nextYear.toString()); // "2027-05-11"
// add()로 1개월 추가 — 월말 처리 옵션 제공
const jan31 = Temporal.PlainDate.from('2026-01-31');
const oneMonth = jan31.add({ months: 1 }, { overflow: 'constrain' });
console.log(oneMonth.toString()); // "2026-02-28" — 2월 말일로 정확히 처리
// until()로 날짜 차이를 Duration으로 반환
const start = Temporal.PlainDate.from('2026-05-11');
const end = Temporal.PlainDate.from('2026-12-31');
const diff = start.until(end, { largestUnit: 'month' });
console.log(`${diff.months}개월 ${diff.days}일 남음`); // "7개월 20일 남음"
add({ months: 1 })에서 overflow: 'constrain' 옵션은 결과가 해당 월의 마지막 날을 넘지 않도록 자동 조정합니다. 반면 overflow: 'reject'로 설정하면 31일에 한 달을 더하는 동작 자체를 에러로 차단합니다. 비즈니스 규칙에 따라 명시적으로 선택하는 구조이므로, dayjs처럼 "조용히 틀린" 날짜가 나올 여지가 없습니다.
B2B 예약 서비스에 Temporal을 적용하면서 가장 먼저 체감한 것도 이 불변성이었습니다. 기존에는 날짜 계산 함수마다 방어적 복사를 넣는 컨벤션을 팀 내부 가이드에 명시해야 했는데, Temporal 전환 이후 그 항목 자체가 사라졌습니다.
4. 타임존 변환 실전 — Asia/Seoul 기준 예약·스케줄링 패턴
4-1. DST 경계값 처리
// 2027년 3월 14일 오전 2시: 미국 동부 DST 전환 (2시 → 3시로 점프)
// 이 시각은 America/New_York에서 존재하지 않음
// Date로 시도하면:
const invalid = new Date('2027-03-14T02:30:00'); // 결과가 환경마다 다름
// Temporal.ZonedDateTime으로 시도하면:
try {
const dstGap = Temporal.ZonedDateTime.from(
'2027-03-14T02:30:00[America/New_York]',
{ disambiguation: 'reject' } // 존재하지 않는 시각 → 에러
);
} catch (e) {
console.error('존재하지 않는 시각입니다:', e.message);
}
// 'compatible' 옵션으로 자동 이동
const adjusted = Temporal.ZonedDateTime.from(
'2027-03-14T02:30:00[America/New_York]',
{ disambiguation: 'compatible' } // 자동으로 03:30으로 이동
);
console.log(adjusted.toString()); // "2027-03-14T03:30:00-04:00[America/New_York]"
4-2. 사용자 로컬 시간 ↔ 서버 UTC 변환
// 사용자가 Seoul 기준 2026-08-15 오후 3시를 예약
const userInput = Temporal.ZonedDateTime.from(
'2026-08-15T15:00:00[Asia/Seoul]'
);
// 서버에 저장할 UTC Instant
const utcInstant = userInput.toInstant();
console.log(utcInstant.toString()); // "2026-08-15T06:00:00Z"
// 서버에서 받은 UTC Instant를 New York 사용자에게 표시
const nyTime = utcInstant.toZonedDateTimeISO('America/New_York');
console.log(nyTime.toString());
// "2026-08-15T02:00:00-04:00[America/New_York]"
// ICS 캘린더 export용 로컬 포맷
function toICSDateTime(zdt: Temporal.ZonedDateTime): string {
const localStr = zdt
.toString({ timeZoneName: 'never', calendarName: 'never' })
.replace(/[-:]/g, '')
.split('.')[0];
return `DTSTART;TZID=${zdt.timeZoneId}:${localStr}`;
}
const icsLine = toICSDateTime(userInput);
console.log(icsLine); // "DTSTART;TZID=Asia/Seoul:20260815T150000"
toInstant()는 타임존 정보를 Temporal.Instant(UTC 절대 시각)로 변환합니다. DB에는 epochMilliseconds나 ISO UTC 문자열로 저장하고, 클라이언트에 돌려줄 때 사용자 타임존 기준 ZonedDateTime으로 복원하는 패턴이 가장 안전합니다.
5. dayjs / date-fns → Temporal 마이그레이션 6단계 체크리스트
dayjs ↔ Temporal API 1:1 매핑 표
| dayjs 패턴 | Temporal 대응 | 차이점 |
|---|---|---|
dayjs() | Temporal.Now.plainDateTimeISO() | Temporal은 타임존 명시 권장 |
dayjs().format('YYYY-MM-DD') | Temporal.Now.plainDateISO().toString() | 포맷 지정자 없이 ISO 기본 |
dayjs(str).format(fmt) | Intl.DateTimeFormat 조합 | Temporal에 자체 format 없음 |
dayjs().add(1, 'month') | .add({ months: 1 }) | overflow 옵션 추가 가능 |
dayjs().subtract(7, 'day') | .subtract({ days: 7 }) | 동일 패턴 |
dayjs(a).diff(b, 'day') | a.until(b, { largestUnit: 'day' }).days | Duration 객체 반환 |
dayjs(a).isBefore(b) | Temporal.PlainDate.compare(a, b) < 0 | 정적 compare 메서드 |
dayjs().tz('Asia/Seoul') | Temporal.Now.zonedDateTimeISO('Asia/Seoul') | 플러그인 없이 네이티브 |
// --- STEP 1: parse 교체 ---
// Before (dayjs)
import dayjs from 'dayjs';
const d = dayjs('2026-05-11');
// After (Temporal)
const d = Temporal.PlainDate.from('2026-05-11');
// --- STEP 2: format 교체 ---
// Before
const label = dayjs().format('YYYY년 MM월 DD일');
// After: Intl.DateTimeFormat으로 포매팅
const today = Temporal.Now.plainDateISO();
const label = new Intl.DateTimeFormat('ko-KR', {
year: 'numeric', month: 'long', day: 'numeric'
}).format(new Date(today.toString())); // 임시 변환 필요 (폴리필 환경)
// 네이티브 환경에서는 Temporal.PlainDate.prototype.toLocaleString() 지원 예정
// --- STEP 3: add/subtract 교체 ---
// Before
const nextMonth = dayjs('2026-01-31').add(1, 'month').toDate();
// After
const nextMonth = Temporal.PlainDate.from('2026-01-31')
.add({ months: 1 }, { overflow: 'constrain' });
// --- STEP 4: diff 교체 ---
// Before
const diffDays = dayjs('2026-12-31').diff(dayjs('2026-05-11'), 'day');
// After
const start = Temporal.PlainDate.from('2026-05-11');
const end = Temporal.PlainDate.from('2026-12-31');
const diffDays = start.until(end).days; // largestUnit 기본값: 'day'
// --- STEP 5: isBefore/isAfter 교체 ---
// Before
if (dayjs(a).isBefore(dayjs(b))) { /* ... */ }
// After
if (Temporal.PlainDate.compare(a, b) < 0) { /* ... */ }
// compare: -1(a < b), 0(같음), 1(a > b)
// --- STEP 6: 타임존(tz) 교체 ---
// Before (dayjs + timezone plugin)
import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';
dayjs.extend(utc); dayjs.extend(timezone);
const seoul = dayjs().tz('Asia/Seoul');
// After
const seoul = Temporal.Now.zonedDateTimeISO('Asia/Seoul');
마이그레이션 순서는 모듈 경계를 기준으로 잡는 것을 권장합니다. 날짜 계산 유틸 함수 레이어부터 Temporal로 전환하고, 컴포넌트 레이어는 뒤따라가는 방식이 회귀 위험을 줄입니다.
6. 안티패턴 3가지 — 이것만큼은 절대 하지 않는다
프로덕션 코드 리뷰에서 반복적으로 목격하는 날짜 처리 안티패턴 세 가지를 정리합니다.
안티패턴 1: new Date(string) 파싱 의존
비ISO 문자열을 new Date()에 넘기는 동작은 ECMAScript 명세상 구현 정의(implementation-defined) 영역입니다. Safari와 V8이 서로 다른 결과를 낼 수 있습니다. Temporal은 from() 정적 메서드에서 파싱 형식을 엄격하게 검증하므로 이 모호성이 사라집니다.
안티패턴 2: getTime() 밀리초 산술로 날짜 차이 계산
(endMs - startMs) / 86400000은 DST를 무시합니다. 달력 기준 날짜 차이는 Temporal의 until() / since() 메서드를 사용하고, 타임존까지 고려해야 한다면 ZonedDateTime 끼리 비교해야 합니다.
안티패턴 3: toLocaleString() 출력에 의존한 비교·저장
date.toLocaleString('ko-KR')의 결과는 시스템 로케일과 브라우저 버전에 따라 달라집니다. 표시(display)용으로는 괜찮지만, 이 문자열을 다시 파싱해서 비교하거나 DB에 저장하면 안 됩니다. 저장에는 항상 ISO 8601 UTC 문자열 또는 epochMilliseconds 정수를 사용합니다.
7. 브라우저 지원 현황·폴리필 전략·번들 최적화
2026년 5월 기준 네이티브 지원 현황
| 브라우저 | 버전 | Temporal 지원 |
|---|---|---|
| Chrome / Edge | 144+ | 네이티브 지원 |
| Firefox | 139+ | 네이티브 지원 |
| Safari | 전 버전 | 미지원 (WebKit 구현 진행 중) |
| Node.js | 26+ | 네이티브 지원 (기본 활성화) |
Safari 미지원이 가장 큰 장벽입니다. 2026년 기준 국내 모바일 트래픽의 약 28~32%(iOS Safari 포함)가 폴리필 없이는 Temporal을 쓸 수 없습니다. @js-temporal/polyfill(github.com/js-temporal/temporal-polyfill)이 현재 가장 완성도 높은 폴리필로, Temporal 제안 챔피언들이 직접 제작했습니다.
번들 사이즈 분석 및 조건부 로딩 전략
Vite 5 환경에서 번들 분석을 수행한 결과, @js-temporal/polyfill 전체를 import하면 gzip 기준 약 28KB가 추가됩니다. 네이티브 환경 대비 초기 파싱 비용이 콜드스타트에서 약 15~25ms 늘어나는 것을 측정했습니다(Chrome DevTools Performance 탭 기준, M2 MacBook Air). 이를 최소화하려면 조건부 로딩 패턴을 씁니다.
// utils/temporal.ts — 조건부 폴리필 로딩
let TemporalNS: typeof Temporal;
async function ensureTemporal() {
if (typeof Temporal !== 'undefined') {
// 네이티브 지원 환경 — 폴리필 번들 0바이트
TemporalNS = Temporal;
} else {
// Safari 등 미지원 환경 — 동적 import로 분리
const polyfill = await import('@js-temporal/polyfill');
TemporalNS = polyfill.Temporal as unknown as typeof Temporal;
}
return TemporalNS;
}
// 앱 초기화 시 한 번만 호출
export const temporal = await ensureTemporal();
# 번들 사이즈 측정 방법 (Vite + rollup-plugin-visualizer)
npm install -D rollup-plugin-visualizer
npx vite build --mode production
# dist/stats.html 에서 @js-temporal/polyfill 청크 사이즈 확인
SSR(Next.js 등) 환경에서는 서버 사이드(Node.js 26+)에서 네이티브 Temporal을 사용하고, 클라이언트 번들에만 조건부 폴리필을 포함하는 전략이 효과적입니다. next.config.ts에서 serverExternalPackages에 @js-temporal/polyfill을 추가하고 서버 환경에서는 import를 건너뜁니다.
tree-shaking 관점에서는 PlainDate, PlainDateTime, ZonedDateTime만 쓰는 프로젝트라면 개별 named export를 쓰는 것이 유리합니다. 폴리필 내부도 ESM 기준으로 빌드되어 있어 사용하지 않는 타입이 번들에서 제거됩니다. PlainDate만 사용할 경우 gzip 약 9KB 수준까지 낮출 수 있었습니다.
8. 결론: Temporal 도입 우선순위와 실무 체크리스트
Temporal API는 Date 객체의 설계 결함을 구조적으로 해결하는 언어 레벨 솔루션입니다. dayjs나 date-fns가 Date를 래핑해서 불편함을 줄이는 방식이라면, Temporal은 날짜·시각 모델 자체를 새로 정의합니다. 타임존 부재, 가변성, 파싱 불일치라는 세 가지 고질적 문제가 API 설계 차원에서 차단됩니다.
ECMAScript 2026에 정식 포함된 만큼, 지금이 전환 계획을 세울 적기입니다. 마이그레이션 우선순위는 다음 순서를 권장합니다.
- 신규 프로젝트: 처음부터 Temporal + 조건부 폴리필로 작성. dayjs를 아예 의존성에 넣지 않음.
- 신규 모듈: 기존 프로젝트 내 새 기능(예약, 스케줄링, 청구 계산)은 Temporal로 작성하고, 기존 코드와 어댑터 레이어로 연결.
- 레거시 모듈: 날짜 관련 버그가 발생하는 모듈부터 선택적으로 전환. 테스트 커버리지를 먼저 확보한 뒤 교체.
JavaScript에서 클로저 컨텍스트를 다룰 때와 마찬가지로(JavaScript 클로저 완벽 이해하기), 날짜 처리 역시 "동작하는 코드"와 "안전한 코드" 사이에는 큰 간격이 있습니다. Temporal은 그 간격을 언어 차원에서 좁힙니다.
실무 체크리스트 5가지:
new Date(string)파싱을 모두Temporal.PlainDate.from()또는Temporal.ZonedDateTime.from()으로 교체했는가- 날짜 계산 함수의 반환값이 원본을 오염시키지 않는 새 인스턴스인지 확인했는가
- 예약·스케줄링 로직에서 DST 경계값(
disambiguation옵션)을 명시적으로 처리했는가 @js-temporal/polyfill조건부 동적 import로 Safari 미지원 환경을 대응하면서 번들 사이즈를 측정했는가- DB 저장 시 UTC
epochMilliseconds또는 ISO UTC 문자열로 일관성을 유지하고, 표시 레이어에서만 타임존 변환을 수행하는가
Temporal API는 ECMAScript 로드맵에서 Promise, async/await 이후 날짜 처리 분야의 가장 큰 변화입니다. Safari 지원이 완료되는 시점(WebKit 팀이 구현 진행 중)을 기점으로 폴리필 없는 완전한 네이티브 사용이 가능해집니다. 지금 폴리필과 함께 도입을 시작하면, 그 시점에는 폴리필 import만 걷어내면 됩니다.