Typescript: Temporal

process.env.TZ = "America/New_York";

const noon = new Date("2026-07-31T12:00:00Z");
console.log("로컬: getHours()", noon.getHours()); // 로컬: getHours() 8
console.log("UTC: getUTCHours()", noon.getUTCHours()); // UTC: getUTCHours() 12

const seoulHour = new Intl.DateTimeFormat("en-CA", {
  timeZone: "Asia/Seoul",
  hour: "2-digit",
  hourCycle: "h23",
}).format(noon);

// 결과값이 문자열이므로, 시간의 계산은 불가
console.log("서울: ", seoulHour); // 서울:  21

// 특정 순간을 의미하는 Instant를 생성(Date는 항상 Instant 입니다)
const noon = Temporal.Instant.from("2026-07-31T12:00:00Z");

// 각 타임존으로 noon을 변환
for (const tz of ["America/New_York", "UTC", "Asia/Seoul"]) {
  const z = noon.toZonedDateTimeISO(tz);
  console.log(`${tz.padEnd(20)} ${z.hour}시  (offset ${z.offset})`);
  // America/New_York     8시  (offset -04:00)
  // UTC                  12시  (offset +00:00)
  // Asia/Seoul           21시  (offset +09:00)
}

// 문자열이 아니라 값이므로 그대로 계산에 쓸 수 있습니다.
const seoul = noon.toZonedDateTimeISO("Asia/Seoul");
console.log("서울 기준 3시간 뒤:", seoul.add({ hours: 3 }).hour + "시"); // 서울 기준 3시간 뒤: 0시

process.env.TZ = "America/New_York";

for (const input of [
  '2026-07-31', //       날짜만 있는 ISO      → UTC로 해석
  '2026-07-31T09:00', // 시각이 붙은 ISO      → 로컬로 해석 (!)
  '2026-07-31 09:00', // T 대신 공백          → 명세 밖, 엔진 재량
  '07/31/2026', //       ISO가 아예 아님      → 명세 밖, 엔진 재량
  '2026-07-31T09:00Z', // 명시적 UTC          → UTC로 해석
]) {
  console.log(input, "-->", new Date(input).toISOString());
}
// 2026-07-31 --> 2026-07-31T00:00:00.000Z
// 2026-07-31T09:00 --> 2026-07-31T13:00:00.000Z
// 2026-07-31 09:00 --> 2026-07-31T13:00:00.000Z
// 07/31/2026 --> 2026-07-31T04:00:00.000Z
// 2026-07-31T09:00Z --> 2026-07-31T09:00:00.000Z

// 날짜만 있는 문자열 → PlainDate. 타임존이 아예 개입하지 않습니다.
console.log(`PlainDate.from("2026-07-31")`, Temporal.PlainDate.from("2026-07-31").toString()); // PlainDate.from("2026-07-31") 2026-07-31

// 시각까지 있지만 타임존이 없는 문자열 → PlainDateTime. 역시 타임존은 포함되지 않습니다.
console.log(`PlainDateTime.from("...T09:00")`, Temporal.PlainDateTime.from("2026-07-31T09:00").toString()); // PlainDateTime.from("...T09:00") 2026-07-31T09:00:00

// 명확한 시점을 원하면 타임존을 명시해야 합니다. 생략하면 통과하지 않습니다.
console.log(`ZonedDateTime.from("...[NY]")`, Temporal.ZonedDateTime.from("2026-07-31T09:00[America/New_York]").toString()); // ZonedDateTime.from("...[NY]") 2026-07-31T09:00:00-04:00[America/New_York]

// 추측을 요구하는 입력은 모두 거부됩니다.
for (const [desc, action] of [
  ["타임존 없이 Instant 요구", () => Temporal.Instant.from("2026-07-31T09:00")],
  ["타임존 없이 Zoned 요구", () => Temporal.ZonedDateTime.from("2026-07-31T09:00")],
  ["존재하지 않는 2월 30일", () => Temporal.PlainDate.from("2026-02-30")],
  ["ISO가 아닌 07/31/2026", () => Temporal.PlainDate.from("07/31/2026")],
  ["banana", () => Temporal.PlainDate.from("banana")],
]) {
  try {
    console.log(desc, "→", action().toString(), "(통과)");
  } catch (e) {
    console.log(desc, "→", e.constructor.name, "즉시 예외");
  }
}
// 타임존 없이 Instant 요구 → RangeError 즉시 예외
// 타임존 없이 Zoned 요구 → RangeError 즉시 예외
// 존재하지 않는 2월 30일 → RangeError 즉시 예외
// ISO가 아닌 07/31/2026 → RangeError 즉시 예외
// banana → RangeError 즉시 예외

function startOfMonth(date) {
  date.setDate(1); // 인자로 받은 객체를 직접 수정합니다
  return date;
}

const someDate = new Date('2026-07-31T12:00:00Z');
console.log("함수 호출 전", someDate.toISOString().slice(0, 10)); // 함수 호출 전 2026-07-31
startOfMonth(someDate);
console.log("함수 호출 후", someDate.toISOString().slice(0, 10)); // 함수 호출 후 2026-07-01

function startOfMonth(date) {
  return date.with({ day: 1 }); // 원본을 건드리지 않고 새 값을 반환
}

const someDate = Temporal.PlainDate.from("2026-07-31");
console.log("함수 호출 전", someDate.toString()); // 함수 호출 전 2026-07-31
const firstDay = startOfMonth(someDate);
console.log("함수 호출 후", someDate.toString(), "  ← 원본 그대로"); // 함수 호출 후 2026-07-31   ← 원본 그대로
console.log("반환값", firstDay.toString()); // 반환값 2026-07-01

// 3월의 두번째 일요일 2am -> 3am으로 변경(-05:00 EST-> -04:00 EDT). 따라서 뉴욕기준 2026년 3월 8일 2am은 존재하지 않음.
// 따라서 2026년 3월 8일은 23시간
// 이후 11월 1일 2am에 다시 EDT->EST로 변경되며, 1am을 두번 통과하므로 11월 1일은 25시간
const beforeSpringForward = new Date('2026-03-08T00:00:00-05:00');
console.log("3월 8일 자정", beforeSpringForward); // 3월 8일 자정 2026-03-08T05:00:00.000Z

// 다음 날(+ 86,400,000 ms) -> 2026-03-09T05:00:00.000Z 이므로, EDT 기준으로는 3월 9일 오전 1시.
const nextDay = new Date(beforeSpringForward.getTime() + 86400000);
console.log("다음날 자정이 아니다!", nextDay.toLocaleString('en-US', { timeZone: 'America/New_York' })); // 다음날 자정이 아니다! 3/9/2026, 1:00:00 AM

const midnight = Temporal.ZonedDateTime.from("2026-03-08T00:00[America/New_York]");

console.log("3월 8일 자정", midnight.toString());
console.log("  .add({ days: 1 })  ", midnight.add({ days: 1 }).toString(), " ← 진짜 다음 날 자정"); // .add({ days: 1 })   2026-03-09T00:00:00-04:00[America/New_York]  ← 진짜 다음 날 자정
console.log("  .add({ hours: 24 })", midnight.add({ hours: 24 }).toString(), " ← 24시간 뒤 (오전 1시)"); // .add({ hours: 24 }) 2026-03-09T01:00:00-04:00[America/New_York]  ← 24시간 뒤 (오전 1시)

// 하루가 몇 시간인지 직접 물어볼 수 있습니다.
for (const d of ["2026-03-07", "2026-03-08", "2026-11-01"]) {
  const z = Temporal.PlainDate.from(d).toZonedDateTime({ timeZone: "America/New_York" });
  console.log(`  ${d} → ${z.hoursInDay}시간`);
}
// 2026-03-07 → 24시간
// 2026-03-08 → 23시간
// 2026-11-01 → 25시간

// 존재하지 않는 시각을 예약하려 하면 조용히 옮기지 않고 거부할 수 있습니다.
for (const option of ["compatible", "reject"]) {
  try {
    const r = Temporal.PlainDateTime.from("2026-03-08T02:30")
      .toZonedDateTime("America/New_York", { disambiguation: option });
    console.log(`  02:30 (${option})`.padEnd(24), r.toPlainTime().toString(), "← 조용히 이동함");
  } catch (e) {
    console.log(`  02:30 (${option})`.padEnd(24), e.constructor.name, "← 없는 시각이라고 알려줌");
  }
}
// 02:30 (compatible)     03:30:00 ← 조용히 이동함
// 02:30 (reject)         RangeError ← 없는 시각이라고 알려줌

// 11월 1일 01:30은 두 번 존재합니다. 어느 쪽인지 고를 수 있습니다.
for (const option of ["earlier", "later"]) {
  const r = Temporal.PlainDateTime.from("2026-11-01T01:30")
    .toZonedDateTime("America/New_York", { disambiguation: option });
  console.log(`  01:30 (${option})`.padEnd(24), r.toInstant().toString());
}
// 01:30 (earlier)        2026-11-01T05:30:00Z
// 01:30 (later)          2026-11-01T06:30:00Z

// 1월 31일 + 1달 -> 2월 31일 -> 3월 3일
const monthEnd = new Date('2026-01-31T12:00:00Z');
monthEnd.setUTCMonth(monthEnd.getUTCMonth() + 1);
console.log("1월 31일 + 1달", monthEnd.toISOString().slice(0, 10)); // 1월 31일 + 1달 2026-03-03

// 두 날짜의 차이 구하기. 86,400,000 ms를 이용해서 나눠야 함. DST를 사용하는 경우 1년에 두 번 틀림
const rangeStart = new Date('2026-01-01T00:00:00Z');
const rangeEnd = new Date('2026-09-15T00:00:00Z');
console.log("두 날짜의 간격", (rangeEnd - rangeStart) / 86400000); // 두 날짜의 간격 257

// 날짜의 각 요소 구하기, getMonth는 0부터 시작하고, getDay는 요일을 리턴 함.
const july31 = new Date("2026-07-31T12:00:00Z");
console.log("getMonth:", july31.getUTCMonth());
console.log("getDay:", july31.getUTCDay());
console.log("getFullYear:", july31.getUTCFullYear());
// getMonth: 6
// getDay: 5
// getFullYear: 2026

// 1월 31일 + 1달 → 2월 28일로 잘라냅니다(clamp). 3월로 넘어가지 않습니다.
const endMonth = Temporal.PlainDate.from("2026-01-31");
console.log("1월 31일 + 1달      ", endMonth.add({ months: 1 }).toString()); // 1월 31일 + 1달       2026-02-28
console.log(`  overflow:"reject" `, (() => {
  try { return endMonth.add({ months: 1 }, { overflow: "reject" }).toString(); }
  catch (e) { return e.constructor.name + " (넘침을 알려달라고 할 수도 있음)"; }
})());
// overflow:"reject"  RangeError (넘침을 알려달라고 할 수도 있음)

// 주의: 한 달씩 두 번 더하는 것과 두 달을 한 번에 더하는 것은 다릅니다.
// ex: 매월 구독 결제일은 최초 결제일에서 누적된 달만큼 한 번에 계산해야 합니다.
console.log("  1달+1달           ", endMonth.add({ months: 1 }).add({ months: 1 }).toString()); // 1달+1달            2026-03-28
console.log("  2달 한 번에       ", endMonth.add({ months: 2 }).toString()); // 2달 한 번에        2026-03-31

// 두 날짜의 간격. 86,400,000 같은 상수가 필요 없습니다.
const start = Temporal.PlainDate.from("2026-01-01");
const end = Temporal.PlainDate.from("2026-09-15");
console.log("두 날짜의 간격(일)  ", start.until(end).total({ unit: "day" })); // 두 날짜의 간격(일)   257
console.log("  ISO 8601 표기     ", start.until(end, { largestUnit: "month" }).toString()); // ISO 8601 표기      P8M14D

// 필드 접근. 메서드가 아니라 속성이고, 월은 1부터 시작합니다.
const july31 = Temporal.PlainDate.from("2026-07-31");
console.log("month (1부터)       ", july31.month);
console.log("day   (일)          ", july31.day);
console.log("dayOfWeek (요일)    ", july31.dayOfWeek, "(1=월요일)");
console.log("year                ", july31.year);
console.log("daysInMonth         ", july31.daysInMonth);
// month (1부터)        7
// day   (일)           31
// dayOfWeek (요일)     5 (1=월요일)
// year                 2026
// daysInMonth          31

const july31 = new Date("2026-07-31T12:00:00Z");

// 표기는 가능하지만, 결과는 문자열 값이므로 1과 같은 이유로 날짜 계산 등은 불가능.
for (const calendar of ['hebrew', 'islamic-umalqura', 'japanese', 'buddhist']) {
  console.log(
    calendar,
    new Intl.DateTimeFormat(`en-u-ca-${calendar}`, {
      timeZone: 'UTC',
      dateStyle: 'long',
    }).format(july31)
  );
}
// hebrew 17 Av 5786
// islamic-umalqura Safar 17, 1448 AH
// japanese July 31, 8 Reiwa
// buddhist July 31, 2569 BE

const july31 = Temporal.PlainDate.from("2026-07-31");

for (const calendar of ['hebrew', 'islamic-umalqura', 'japanese', 'buddhist']) {
  const d = july31.withCalendar(calendar);
  const year = d.era ? `${d.era} ${d.eraYear}년 (연속 ${d.year})` : `${d.year}년`;
  console.log(calendar, year);
}
// hebrew 5786년
// islamic-umalqura 1448년
// japanese reiwa 8년 (연속 2026)
// buddhist 2569년

// 문자열이 아니기 때문에 계산이 가능합니다.
const japaneseJuly31 = july31.withCalendar("japanese");
console.log(japaneseJuly31.add({ days: 2}).toString()); // 2026-08-02[u-ca=japanese]

> npm i -D typescript@7 @types/node
> node -v         
v26.6.0

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "lib": ["esnext", "dom"],
    "types": ["node"],
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true
  }
}

// Temporal은 전역(global)이므로 import가 필요 없습니다.
// 타입은 tsconfig의 lib: ["esnext"] 에서 옵니다.
const meeting: Temporal.ZonedDateTime =
  Temporal.ZonedDateTime.from('2026-03-08T09:00[America/New_York]');

console.log(meeting.toString());
console.log(`이 날은 ${meeting.hoursInDay}시간`);          // 23 — 서머타임 시작
console.log('서울에서는:', meeting.withTimeZone('Asia/Seoul').toPlainDateTime().toString());

> node temporal.ts 
2026-03-08T09:00:00-04:00[America/New_York]
이 날은 23시간
서울에서는: 2026-03-08T22:00:00