Footnotes

  1. 날짜 및 시간 작업을 위한 Temporal API 공식 문서 ↩

  2. 날짜 및 시간을 사용하여 작업할 때의 문제를 논의하고 솔루션으로 Temporal API를 제안하는 블로그 게시물 ↩

  3. Date 개체, 날짜 형식, 시간대 및 날짜 라이브러리를 포함하여 JavaScript에서 날짜 작업에 대한 포괄적인 설명 ↩

  4. 타임존 작업의 기본 사항을 설명 ↩

#11

new Date(문자열) 이 모든 엔진에서 보장하는 건 2022-04-09T12:00:00 같은 ISO 형식뿐이다. 공백으로 가른 2022-04-09 12:00:00 은 구현 정의라 Safari 에서는 Invalid Date 가 됐다. 그런 형식은 date-fns 의 parse 에 형식 문자열을 명시해 읽는다.

-- new Date(문자열): 엔진이 보장하는 건 ISO 형식뿐
newDate :: Engine -> String -> Maybe Date
newDate _      s | isIso s = Just (parseIso s)       -- "2022-04-09T12:00:00"
newDate Safari _           = Nothing                 -- "2022-04-09 12:00:00" → Invalid Date
newDate e      s           = implementationDefined e s

-- 형식을 명시해 읽는다: isAfter(new Date(), parse(DATE, 'yyyy-MM-dd HH:mm:ss', new Date()))
#159

완전히 커스텀한 UI 가 필요하면 react-aria(Adobe 의 headless, 로직과 접근성만)로 직접 만든다. 기본 기능을 빨리 원하면 react-big-calendar(구글 캘린더 스타일, 날짜 라이브러리 선택 가능). 모던한 DX 와 가벼움을 원하면 Schedule-X(드래그·리사이즈, 레퍼런스 적음). 타임라인·리소스 뷰 같은 엔터프라이즈 기능이 필요하면 FullCalendar(플러그인 구조, 일부 유료, 번들 큼). 날짜 선택만이면 react-day-picker·dayzed·react-datepicker, headless 로는 use-lilius·h6s.

-- 캘린더 라이브러리: 상황으로 고른다 (위에서부터 매칭)
choose :: Need -> Library
choose FullyCustomUI = ReactAria          -- Adobe headless: 로직·접근성만, 일정 표시는 직접
choose QuickBasics   = ReactBigCalendar   -- 구글 캘린더 스타일, moment/date-fns/dayjs 선택 · 타입 아쉬움
choose ModernLight   = ScheduleX          -- React/Vue/Angular, 드래그·리사이즈 · 레퍼런스 적음
choose Enterprise    = FullCalendar       -- 플러그인, 타임라인·리소스 뷰 · 일부 유료, 번들 큼

-- 날짜 선택만: react-day-picker · dayzed · react-datepicker
-- 날짜 계산을 네이티브로 하려면: You-Dont-Need-Momentjs
-- headless: use-lilius · h6s — 찾기 어렵다, 갖다 써 보면 안다
#28

이번 달 1일과 말일 사이의 각 주 시작일을 eachWeekOfInterval 로 구하고, 주마다 그 시작일부터 6일 뒤까지를 eachDayOfInterval 로 펼치면 주 × 7 의 날짜 행렬이 된다. 첫 주와 마지막 주에는 앞뒤 달의 날짜도 들어온다.

-- 달력 행렬: 이번 달의 각 주 시작일 → 주마다 7일
matrix :: Day -> [[Day]]
matrix today = [ [w `addDays` i | i <- [0 .. 6]]       -- eachDayOfInterval { start = w, end = w + 6 }
               | w <- eachWeekOfInterval (startOfMonth today) (endOfMonth today) ]
-- 첫 주·마지막 주에는 앞뒤 달 날짜가 섞인다
#29

new Date() 나 Math.random() 을 컴포넌트 안에서 바로 부르면 테스트마다 결과가 달라진다. 기본 매개변수로 받으면 인자를 안 넘긴 프로덕션에서는 호출할 때마다 new Date() 가 평가되고, 테스트에서는 new Date(2023, 0, 1) 이나 () => 0.5 를 넘겨 결과를 고정한다. 날짜는 toLocaleDateString(“sv-SE”) 로 로컬 YYYY-MM-DD 를 만든다 — toISOString 은 UTC 라 KST 오전 9시 전엔 하루 밀린다.

-- 비순수 값(Date·Math.random)은 기본 매개변수로 받는다 — 기본값은 호출할 때마다 평가된다
dateInput :: Maybe Date -> IO Html
dateInput now = do
  d <- maybe newDate pure now                   -- { now = new Date() }
  pure (input "date" (localYmd d))              -- toLocaleDateString('sv-SE'); toISOString 은 UTC 라 하루 밀린다

random :: IO Double -> IO Html
random randomizer = div . show <$> randomizer   -- { randomizer = Math.random }

-- 테스트: 값을 넘겨 고정한다
-- dateInput (Just (Date 2023 0 1)) → "2023-01-01" · random (pure 0.5) → "0.5"
#314

beforeEach 에서 vi.useFakeTimers 로 Date 를 가짜로 바꾸고 vi.setSystemTime 으로 오늘을 2024-07-20 으로 고정한다. 그러면 isSameDate 는 같은 날짜에 true, 하루 전·후에 false 를 늘 같게 낸다. afterEach 에서 useRealTimers 로 되돌린다. vitest 와 jest 둘 다 내부적으로 @sinonjs/fake-timers 를 쓴다.

-- 오늘이 바뀌면 결과가 바뀌는 함수: 가짜 타이머로 "오늘" 을 고정한다
isSameDate :: Date -> Bool
isSameDate d = d == today          -- today 는 new Date() — 테스트에서는 setSystemTime 이 정한다

-- beforeEach: useFakeTimers >> setSystemTime "2024-07-20"
isSameDate "2024-07-20" == True
isSameDate "2024-07-19" == False
isSameDate "2024-07-21" == False
-- afterEach: useRealTimers · vitest·jest 둘 다 내부는 @sinonjs/fake-timers
#315

서버가 날짜를 사용자 시간대로 그리려면 요청에 시간대가 있어야 한다. proxy(Next 16, 예전 middleware)가 쿠키 user-timezone, 없으면 Vercel 의 x-vercel-ip-timezone, 없으면 UTC 를 골라 요청 헤더 x-user-timezone 으로 넘기고, 서버 컴포넌트가 headers() 로 읽어 그 시간대로 렌더한다. 응답 헤더로 넘기면 headers() 가 못 읽는다. 클라이언트는 Intl 로 실제 시간대를 알아내 쿠키에 1년 저장한다. 그래서 첫 방문만 IP 추정값이고 그 뒤로는 정확하며, 서버가 이미 맞게 그려서 깜빡임(FOUT)이 없다. 대안인 useSyncExternalStore 는 서버에서 UTC 로 그린 뒤 클라이언트에서 실제 시간대로 다시 그려 하이드레이션 에러는 없지만 깜빡인다.

-- RSC 에서 날짜를 사용자 시간대로: 시간대를 요청에 실어 서버에서 그린다
-- (Date 직렬화 · 서버/클라 시간대 불일치 · 하이드레이션 FOUT 을 한 번에)
timezone :: Request -> TimeZone
timezone r = fromMaybe "UTC" (cookie "user-timezone" r <|> header "x-vercel-ip-timezone" r)
                                                    -- request.geo 는 Next 15 에서 제거

proxy r = next r { headers = insert "x-user-timezone" (timezone r) (headers r) }
  -- proxy.js = Next 16 의 middleware. 응답이 아니라 요청 헤더라야 headers() 가 읽는다

userTimezone = cache (fromMaybe "UTC" . lookup "x-user-timezone" <$> headers)   -- 15 부터 async

-- 클라이언트: 실제 시간대를 쿠키에 (1년)
useEffect (setCookie "user-timezone" (resolvedTimeZone intl) { path = "/", maxAge = 31536000 }) []
-- 첫 방문은 IP 추정, 그 뒤는 정확. 서버가 맞게 그려서 FOUT 없음

-- 대안: useSyncExternalStore — getServerSnapshot = "UTC", getSnapshot = 실제
--   서버 렌더·하이드레이션에만 서버 값을 쓰고 다시 그린다: 하이드레이션 에러는 없지만 FOUT
#509

2025-10-28(화)이 든 주를 구한다. startOf(isoWeek) 는 ISO 8601 이라 월요일 10-27 부터 일요일 11-02 까지다 — 캘린더 UI 에 주로 쓴다. startOf(week) 는 로케일을 따라 기본 en·ko 에선 일요일 10-26 부터, en-gb 에선 월요일부터다. 시작일에 0~6일을 더해 7개를 만든다.

-- 특정 날짜가 든 주의 7일
weekDays :: Bool -> Date -> [Date]                -- iso 기본값 True: getWeekDays(date) 는 월~일
weekDays iso d = [start `addDays` i | i <- [0..6]]
  where start = startOf (if iso then IsoWeek else Week) d
-- IsoWeek: ISO 8601, 월요일 시작 (캘린더 UI 에 주로) — dayjs.extend(isoWeek) 필요
-- Week:    로케일을 따른다 — 기본 en·ko 는 일요일, en-gb 는 월요일

weekDays True "2025-10-28" == ["2025-10-27", …, "2025-11-02"]
#513

getDay 는 로컬 시간 기준 요일을 0(일)~6(토)으로 준다. new Date(2024, 11, 25) 는 월이 0 부터라 12월 25일 로컬 자정이고 수요일(3)이다. new Date(“2024-12-25”) 처럼 날짜만 쓴 문자열은 UTC 자정으로 읽혀, UTC 보다 느린 시간대(미국 등)에선 로컬로 24일 저녁이라 화요일(2)이 나온다. 요일 이름은 [일, 월, 화, 수, 목, 금, 토] 배열에 getDay 로 꺼낸다.

-- 로컬 시간 기준 요일 (0 = 일, 6 = 토)
getDay :: Date -> Int

getDay (local 2024 11 25) == 3          -- 수요일. 월은 0 부터
getDay (parse "2024-12-25") == 2        -- UTC 보다 느린 시간대(미국 등)에서
  -- 날짜만 쓴 문자열은 UTC 자정, 날짜+시각은 로컬로 읽는다

dayName d = ["일", "월", "화", "수", "목", "금", "토"] !! getDay d
#519

목표 시각 “18:30:00” 을 오늘 날짜에 맞춘 Date 로 만들고 지금을 뺀다. Date 끼리 빼면 숫자 문맥이라 둘 다 밀리초 타임스탬프가 되어 차가 밀리초로 나온다. 음수면 이미 지났으니 null. 아니면 3,600,000 으로 나눠 시, 60,000 으로 나눈 나머지 60 이 분, 1,000 으로 나눈 나머지 60 이 초다. 예: 16:14:30 에 부르면 2시간 15분 30초.

-- 지금부터 목표 시각("18:30:00")까지 남은 시간
remaining :: Time -> Time -> Maybe (Int, Int, Int)
remaining now target
  | diff < 0  = Nothing                                     -- 이미 지났다
  | otherwise = Just ( diff `div` 3600000 `mod` 24
                     , diff `div` 60000   `mod` 60
                     , diff `div` 1000    `mod` 60 )
  where diff = target - now   -- Date − Date: 숫자 문맥이라 둘 다 타임스탬프(ms)가 된다
                              -- target 은 오늘 날짜에 setHours h m s

remaining (today 16 14 30) (today 18 30 0) == Just (2, 15, 30)
#531