@plott/webkit-time0.4.0

날짜와 시각을 계산하는 패키지입니다. 읽는 사람은 «오늘»·하루 범위·시작 날짜를 다루는 프론트엔드 개발자입니다. 화면에 글자로 쓰는 일(형식)은 @plott/webkit-format 이 합니다.

런타임 의존성이 없습니다(브라우저·Node 의 Intl 만 씁니다. /kr 의 공휴일 표도 코드에 들어 있습니다). 서버·브라우저·proxy 어디서나 씁니다.

값 세 가지

DateOnly·TimeOfDay 는 표식이 붙은 문자열 타입입니다. parseDateOnly·parseTimeOfDay(틀리면 null) 또는 dateOnly·timeOfDay(틀리면 던짐)를 거친 값만 이 타입이 됩니다.

진입점

붙이기

import { countDaysInclusive, diffDays, inZone, parseDateOnly, parseInstant, type DateOnly } from "@plott/webkit-time";
declare const api: { json(path: string, init: { query: Record<string, string> }): unknown };declare const res: { startDate: string; endDate: string; paidAt: string };declare const start7: DateOnly;declare const end7: DateOnly;
const zone = inZone("Europe/Paris");const today = zone.today();const { start, end } = zone.dayRange(today);api.json("/orders", { query: { from: zone.toOffsetIso(start), to: zone.toOffsetIso(end) } });
const startDate = parseDateOnly(res.startDate);const endDate = parseDateOnly(res.endDate);const days = diffDays(startDate!, endDate!);const inclusive = countDaysInclusive(start7, end7);
const paidAt = parseInstant(res.paidAt, { offsetless: "UTC" });

• zone.today() 는 그 시간대의 오늘(DateOnly)입니다. zone.dayRange(today) 는 [오늘 00:00, 내일 00:00) 의 순간이고 end 는 범위에 들어가지 않습니다.
• diffDays 는 끝 날을 세지 않는 날 수, countDaysInclusive 는 양 끝을 넣은 날 수입니다(7일 = 1일~7일).
• 오프셋 없이 오는 서버 값(Java LocalDateTime)은 서버가 어느 시간대로 쓰는지 offsetless 로 적어서 읽습니다.

inZone("Asia/Tokyo") 처럼 시간대 하나로 같은 함수 묶음을 만듭니다. 서울은 @plott/webkit-time/kr 의 kst 입니다. 함수 하나만 쓸 때는 today(zone)·dateIn(instant, zone)·dayRangeIn(date, zone) 처럼 시간대를 인자로 넘깁니다.

클라이언트 컴포넌트의 오늘

import type { ReactElement } from "react";import { inZone, type DateOnly } from "@plott/webkit-time";
declare function Calendar(props: { today: DateOnly }): ReactElement;
const zone = inZone("Europe/Paris");
export default function Page() {  return <Calendar today={zone.today()} />;}

"use client";import type { ReactElement } from "react";import type { DateOnly } from "@plott/webkit-time";import { useToday } from "@plott/webkit-time/react";
export function Calendar(props: { today: DateOnly }): ReactElement {  const today = useToday("Europe/Paris", props.today);  return <time>{today}</time>;}

서버 컴포넌트가 정한 오늘을 두 번째 인자로 넘기면 첫 그림이 서버와 같고, 자정을 넘기면 값이 바뀝니다.

useToday(zone, initial, { frozen: true }) 는 initial 을 그대로 돌려주고 시계를 읽지 않으며 타이머와 탭 구독도 걸지 않습니다. 서버 스냅샷·테스트·문서 화면에서 «오늘» 을 고정할 때 씁니다.

카운트다운

import { useNow } from "@plott/webkit-time/react";
export function Countdown(props: { serverNow: number }) {  const now = useNow(props.serverNow, { intervalMs: 1000 });  return <span>{now}</span>;}

useToday(기본 60초)·useNow(기본 1초)는 간격마다, 탭이 다시 보일 때(visibilitychange), 뒤로 가기 캐시(bfcache)에서 되살아날 때(pageshow) 다시 읽습니다. now 옵션은 테스트용 시계이고 렌더마다 새 함수를 넘겨도 효과를 다시 걸지 않습니다.

바깥과 주고받기 — /interop

/interop 의 변환 함수는 날짜 선택 컴포넌트(date-picker)의 안쪽과 서버 쪽 변환을 위한 것입니다. 화면에 브라우저 기본 날짜·시각 입력(<input type="date"> 등)을 직접 그리지 않고 날짜 선택 컴포넌트를 씁니다(@plott/webkit-config 의 린트 규칙 date-input 이 막습니다).

import { useState, type ReactElement } from "react";import { dateOnly, type TimeZone } from "@plott/webkit-time";import { toPickerDate, fromPickerDate, toDatetimeLocal, fromDatetimeLocal, parseTimeInput } from "@plott/webkit-time/interop";
declare function DayPicker(props: { selected: Date; onSelect: (d: Date | undefined) => void }): ReactElement;declare function DateTimePicker(props: { value: string; onChange: (value: string) => void }): ReactElement;
export function Fields({ zone }: { zone: TimeZone }) {  const [checkIn, setCheckIn] = useState(dateOnly("2026-11-03"));  const [ms, setMs] = useState<number | null>(0);  parseTimeInput("14:30:15");  return (    <>      <DayPicker selected={toPickerDate(checkIn)} onSelect={(d) => d && setCheckIn(fromPickerDate(d))} />      <DateTimePicker value={ms === null ? "" : toDatetimeLocal(ms, zone)} onChange={(value) => setMs(fromDatetimeLocal(value, zone))} />    </>  );}

한국 공휴일·영업일 — /kr

import { holidayKr, holidaysKr, krCalendar } from "@plott/webkit-time/kr";import { dateOnly, isBusinessDay, type DateOnly } from "@plott/webkit-time";
declare const d: DateOnly;
holidayKr(dateOnly("2026-02-17"));holidaysKr(2026);krCalendar.isBusinessDay(d);krCalendar.addBusinessDays(dateOnly("2026-02-13"), 1);krCalendar.dayType(d);isBusinessDay(d, { holidays: krCalendar.isHoliday });

• holidayKr 는 그날의 공휴일 이름 배열(겹치면 둘 이상), 공휴일이 아니면 null 입니다. holidaysKr(year) 는 [{ date, names }] 를 날짜 순으로 줍니다.
• addBusinessDays(2026-02-13, 1) 은 2026-02-19 입니다(주말과 설날 연휴를 건넙니다).
• dayType 은 holiday → holidayEve(다음 날이 공휴일) → sat → sun → fri → weekday 순으로 처음 맞는 것을 줍니다. 다른 우선순위가 필요하면 krCalendar.isHoliday 로 앱이 다시 짭니다.
• 표는 2018-01-01~2027-12-31 이고 holidayKrCoverage() 가 { from, to, generatedAt, source } 를 줍니다.
• isHolidayDataStaleKr(today) 는 표가 «내년 말» 까지 덮지 못하면 true 입니다. 시계를 읽지 않고 기준일을 받습니다. 앱도 같은 함수를 자기 CI 에 둘 수 있습니다.

달력과 날짜 입력 도우미

import {  addDaysClamped,  dateOnly,  dateOrder,  deadlineIn,  dayLengthMinutes,  eachDayThrough,  instantAtWallMinutes,  isWithinDeadline,  minutesIntoDayIn,  monthGrid,  parseLocalizedDate,  timeOfDay,  weekInfo,} from "@plott/webkit-time";
declare const paidAtMs: number;
const { firstDay } = weekInfo("en-US");const weeks = monthGrid(2026, 11, firstDay);const order = dateOrder("de-DE");const typed = parseLocalizedDate("3.11.2026", "de-DE");const last = addDaysClamped(dateOnly("9999-12-31"), 1);const days = eachDayThrough(dateOnly("2026-11-03"), dateOnly("2026-11-05"));
const zone = "America/Los_Angeles";const length = dayLengthMinutes(dateOnly("2026-03-08"), zone);const elapsed = minutesIntoDayIn(paidAtMs, zone);const at = instantAtWallMinutes(dateOnly("2026-03-08"), 300, zone);const rule = { daysBefore: 2, time: timeOfDay("23:59") };const deadline = deadlineIn(dateOnly("2026-11-10"), rule, zone);const open = isWithinDeadline(paidAtMs, dateOnly("2026-11-10"), rule, zone);

• weekInfo(locale) 는 { firstDay, weekend, minimalDays } 를 ISO 요일(월=1 … 일=7)로 줍니다. 값은 Intl.Locale 의 주 정보이고, 그것이 없는 환경에서는 지역(region)별 표로 정해서 같은 모양을 줍니다. 로케일을 늘 인자로 받고 실행 환경의 로케일은 읽지 않습니다.
• monthGrid(year, month, weekStartsOn) 은 그 달을 덮는 주를 DateOnly[][](주마다 7칸)로 줍니다. 앞뒤 칸은 이웃 달 날짜이고 지원 범위 밖 이웃 날짜가 필요한 달(9999년 12월 등)은 던집니다.
• dateOrder(locale) 은 숫자 날짜의 year·month·day 순서이고, parseDateByOrder(text, order)·parseLocalizedDate(text, locale) 은 그 순서로 친 날짜 글자를 읽습니다. 구분 글자는 무엇이든 받고, 4자리 연도·1~2자리 월일·ASCII 숫자만 받으며 틀리면 null 입니다. 서력(그레고리력)과 라틴 숫자만 다룹니다.
• addDaysClamped·addMonthsClamped·addYearsClamped 는 1000-01-01~9999-12-31 경계에서 던지지 않고 경계에 멈춥니다. addDays·addMonths 는 계속 던집니다. eachDayThrough(from, through) 는 양 끝을 넣고 지원 범위의 마지막 날도 담습니다.
• dayLengthMinutes(date, zone) 은 그날의 실제 길이(분)입니다(서머타임 전환일은 1380·1500). minutesIntoDayIn(instant, zone) 은 그날 자정부터 실제로 흐른 분, instantAtWallMinutes(date, wallMinutes, zone) 은 자정부터 센 벽시계 분을 순간으로 바꿉니다(없는 시각은 뒤로, 하루를 넘는 분은 다음 날로 넘깁니다).
• deadlineIn(date, { daysBefore, time }, zone) 은 date 의 daysBefore 일 전 time 분이 끝나는 순간(그 분의 다음 분 시작)이고, isWithinDeadline(instant, date, rule, zone) 은 그 순간 전이면 true 입니다. «체크인 이틀 전 23:59 까지 취소» 가 { daysBefore: 2, time: "23:59" } 입니다.

Temporal 어댑터 — /temporal

Temporal 네임스페이스를 첫 인자로 받는 구조적 타입만 씁니다. 폴리필을 가져오지도 전역 Temporal 을 읽지도 않습니다.

import { dateOnly } from "@plott/webkit-time";import { fromPlainDate, toPlainDate, toZoned, type PlainDateLike } from "@plott/webkit-time/temporal";
declare const Temporal: {  PlainDate: { from(item: string): PlainDateLike };  Instant: { fromEpochMilliseconds(ms: number): { toZonedDateTimeISO(zone: string): unknown } };};declare const paidAtMs: number;
const checkIn = dateOnly("2026-11-03");const p = toPlainDate(Temporal, checkIn);const back = fromPlainDate(p);const z = toZoned(Temporal, paidAtMs, "Asia/Seoul");

fromPlainDate 는 ISO 가 아닌 달력(japanese·hebrew …)이면 던집니다. fromPlainTime 은 초·나노초가 0 이 아니면 기본으로 던지고 { truncate: true } 면 분 아래를 버립니다. toInstant 는 유한한 정수 ms 만 받습니다. toZoned 의 시간대는 IANA 이름이나 고정 오프셋(+09:00)입니다.

기본으로 지키는 것

• 시간대를 늘 인자로 받습니다. 실행 환경의 시간대(서버 컨테이너는 보통 UTC, 브라우저는 기기)를 읽지 않습니다. new Date().toISOString().slice(0, 10) 은 UTC 의 오늘이라 한국 시각 00:00–08:59 에 어제가 됩니다. today(zone) 을 씁니다.
• 어느 시간대도 기본값이 아닙니다. 루트 진입점은 시간대 값을 내보내지 않고, 어떤 함수도 인자를 생략하면 특정 시간대로 읽지 않습니다(/kr 의 KST·kst 는 값일 뿐입니다). parseInstant(value) 는 둘째 인자를 비우면 오프셋 없는 문자열을 거절하고 null 을 줍니다.
• «오늘» 을 모듈 상수로 두지 않습니다. 열어 둔 화면이 자정을 넘기면 어제에 머뭅니다. useToday 는 간격마다, 그리고 탭이 다시 보일 때 다시 봅니다.
• 클라이언트 컴포넌트가 그리는 중에 오늘을 셈하지 않습니다. 미리 그린 화면(빌드 시각)과 브라우저가 다른 날짜를 그려 hydration 이 어긋납니다. 서버가 정한 값을 useToday 의 두 번째 인자로 넘깁니다.
• 범위의 끝은 넣지 않습니다([start, end)). 23:59:59.999 같은 끝값을 만들지 않습니다.
• 모양이 틀리거나 있을 수 없는 값은 null 입니다. 2026-02-30, 24:00, 26년 8월 26일 을 짐작해 읽지 않고, 빈 값을 «지금» 이나 Invalid Date 로 바꾸지 않습니다.
• 오프셋 없는 서버 값의 시간대에는 기본값이 없습니다. UTC 로 직렬화하는 서버의 T05:00 을 KST 로 읽으면 9시간 어긋납니다. 서버와의 계약을 offsetless 로 적습니다("UTC"·"Asia/Seoul" 같은 시간대 이름이거나 { offsetless: 시간대 }). 거절하려면 둘째 인자를 비웁니다.
• 서머타임이 있는 시간대도 맞습니다. 없는 시각(봄)은 뒤로, 두 번 있는 시각(가을)은 앞의 것으로 정합니다(Temporal 의 compatible 과 같습니다). UTC+14 부터 UTC−12 까지, 날짜 변경선을 건너뛴 날(사모아 2011-12-30)과 30·45분 오프셋(로드하우·카트만두·채텀)도 표로 검증합니다.
• 시간대 이름을 검사합니다. isTimeZone 은 기준 대소문자의 IANA 이름(Asia/Seoul, UTC, 별칭 Asia/Kolkata)만 받습니다. +09:00·EST·Asia/seoul 은 false 이고 { allowOffsets: true } 면 ±HH:MM 도 받습니다. 틀린 이름을 함수에 넘기면 @plott/webkit-time: unknown time zone RangeError 입니다(parseInstant 도 같습니다. 코드의 실수이므로 null 이 아니라 던집니다).
• 지원 연도는 1000–9999 입니다. 그 밖(기원전·5자리)은 RangeError. 옛 지방평균시처럼 분 아래 오프셋(서울 1900년 +8:27:52)은 offsetSeconds 로 초까지 셉니다(offsetMinutes 는 반올림).
• 영업일·휴일은 앱이 정합니다. isBusinessDay·addBusinessDays 의 쉬는 요일은 기본 토·일(weekend 로 바꿈), 공휴일은 holidays(date) 함수로 받습니다. 루트 진입점은 어느 나라의 달력도 내장하지 않습니다.
• 날짜 범위는 [from, toExclusive) 입니다. eachDay·diffDays 는 끝 날을 세지 않습니다. overlaps 도 반쯤 열린 범위라 맞닿은 두 범위는 겹치지 않고 빈 범위는 아무것과도 겹치지 않습니다.
• 날짜 목록은 상한이 있습니다. eachDay 는 36,600 일(maxDays)을 넘으면 문자열을 만들기 전에 RangeError 입니다. 1000-01-01~9999-12-31 같은 입력이 330 만 개를 할당하지 못하게 합니다.
• addBusinessDays 의 가드는 «연달아 영업일이 없는 날» 로 셉니다. 영업일이 3,660 일 연속으로 나오지 않을 때(holidays 가 늘 true)만 던지므로 영업일 80,000 일 뒤 같은 먼 계산은 통과합니다. 쉬는 요일이 7개 다 차면 RangeError 입니다.
• 표 밖의 한국 날짜는 던집니다. 모르는 날을 «평일» 로 읽으면 결제 마감·요금이 조용히 틀립니다. 먼 미래를 어림만 하는 화면은 createKrCalendar({ outOfCoverage: "ignore" }) 로 표 밖을 «공휴일 아님» 으로 읽습니다. 표 안의 날짜는 다음 날이나 전날이 표 밖이어도 늘 답합니다. 표의 마지막 날(2027-12-31)의 dayType 은 다음 날을 «모름» 으로 보고 연휴 전날 판정만 건너뜁니다. holidayKr·isHolidayKr 는 표 밖 날짜 자체를 물으면 던집니다.
• 날짜 계산은 지원 범위 끝에서 던지고, 멈추는 계산은 따로 고릅니다. addDays·addMonths·eachDay 는 1000-01-01·9999-12-31 을 넘으면 RangeError 입니다. 경계에 멈추려면 addDaysClamped·addMonthsClamped·addYearsClamped·eachDayThrough 를 씁니다.
• 고정한 «오늘» 은 시계를 읽지 않습니다. useToday(zone, initial, { frozen: true }) 는 initial 을 그대로 돌려주고 타이머·구독·시계 호출이 없습니다.
• 주 정보는 환경에 따라 달라지지 않습니다. Intl.Locale 에 주 정보가 없으면 지역별 표로 같은 모양의 값을 줍니다. 틀린 로케일 태그는 던집니다.
• 한국 공휴일 표는 코드에 들어 있고 런타임에 네트워크를 쓰지 않습니다. 모듈을 읽는 것만으로는 일하지 않고 처음 쓸 때 한 번 색인을 만듭니다. 돌려준 이름 배열은 얼어 있습니다.
• Temporal 어댑터는 값을 조용히 바꾸지 않습니다. 초가 있는 PlainTime 은 기본으로 던지고, ISO 가 아닌 달력의 PlainDate 는 던집니다.

테스트는 로스앤젤레스 시간대(TZ=America/Los_Angeles)에서 돕니다. 시간대 계산 테스트(zone·dst·interop·kr·temporal 과 callable 별 테스트)는 Pacific/Kiritimati(+14)와 UTC 에서 한 번씩 더 돌며 결과가 같아야 합니다. 앱의 날짜 테스트도 시계(vi.setSystemTime)와 시간대(test.env.TZ)를 고정합니다.

그 밖

공휴일 데이터 갱신

원천은 @hyunbinseo/holidays-kr(MIT, 우주항공청(한국천문연구원) 월력요항과 관보 기준)이고 이 패키지의 devDependency 입니다. 스크립트가 src/kr/holidays.data.ts 를 만들며, 앱에 원천 패키지가 따라가지 않습니다.

1. 원천 패키지를 올립니다: pnpm --filter @plott/webkit-time up @hyunbinseo/holidays-kr.
2. packages/time 에서 node scripts/update-holidays-kr.mjs 를 돌립니다. 연도 범위는 원천에 있는 가장 늦은 해까지 자동입니다(--from·--to·--out·--generated-at 로 바꿀 수 있습니다). 생성되는 파일에는 주석이 없습니다.
3. node scripts/update-holidays-kr.mjs --check 는 파일을 쓰지 않고 지금 표가 원천과 같은지만 봅니다(다르면 종료 코드 1).
4. git diff src/kr/holidays.data.ts 로 바뀐 날을 확인하고 pnpm test 를 돌립니다. 새 해가 들어오면 개수 기대값(holidaysKr(2027) 등)과 표 밖 기대값(2028-…)이 달라집니다.
5. 원천 패키지에 아직 없는 임시공휴일은 표를 손으로 고치지 않고 앱에서 krCalendar.isHoliday(d) || extra.has(d) 로 덧붙입니다.

공휴일 표 검증

2026년과 2027년 표는 공식 발표와 날짜가 모두 같습니다. 2027년은 한국천문연구원 달력자료(월력요항) 2027(우주항공청 2027년 월력요항 기준, 자료생성 2026-06-30)의 24일과 같습니다. 2026년의 노동절(5월 1일)·제헌절(7월 17일)은 월력요항 2026(2025-06-30 발표)에 없고 «공휴일에 관한 법률» 개정 뒤 관공서의 공휴일에 관한 규정(대통령령 제36290호, 2026-04-30 개정, 2026-05-01 시행)이 더한 날이며, 나머지 20일은 월력요항 2026(한국천문연구원 자료)과 같습니다. test/kr-official.test.ts 가 이 날짜를 고정해, 다시 만든 표가 다르면 테스트가 실패합니다. 표에는 2026·2027년의 임시공휴일이 없습니다. 임시공휴일은 발표되는 대로 앱이 덧붙입니다.

Temporal 지원 상태

Temporal 은 Chrome·Edge 144, Firefox 139 가 내고 Safari 는 내지 않으며, Node 26 에는 있고 Node 24 에는 없습니다(https://web-platform-dx.github.io/web-features-explorer/features/temporal/). Node 24 에서 쓰려면 폴리필을 앱이 넘깁니다.

Temporal·date-fns·dayjs 와의 관계

• 값의 모양(PlainDate = YYYY-MM-DD)을 Temporal 과 같게 두어 옮기기 쉽고, 옮기는 길은 /temporal 어댑터가 줍니다.
• dayjs 의 시간대 플러그인과 date-fns 의 @date-fns/tz 도 Intl 로 계산합니다. 오늘·하루 범위·날짜 더하기는 Intl 로 충분해 의존성을 두지 않습니다.

export 전체