次世代JS標準時刻API Temporal を3年先行利用して得た知見を共有します！

現在時刻の取得

const now = Temporal.Now.zonedDateTimeISO();
=> Temporal.ZonedDateTime 2025-09-06T01:23:45.678+09:00[Asia/Tokyo]

Date型との相互変換

Dateからの移行期に便利な相互変換

// Date → Temporal.ZonedDateTime
export function dateToZdt(date: Date, timeZone: Temporal.TimeZoneLike = "Asia/Tokyo") {
  return Temporal.Instant.fromEpochMilliseconds(Number(date)).toZonedDateTimeISO(timeZone);
}

// Temporal.ZonedDateTime → Date
export function zdtToDate(t: Temporal.ZonedDateTime) {
  return new Date(t.epochMilliseconds);
}

RFC3339フォーマットとの相互変換

時差( OffsetDateTime )を含む表現であれば、RFC3339フォーマットの利用が便利です

// "2025-09-01T12:34:56.789Z" → Temporal.ZonedDateTime
export function rfc3339ToZdt(rfc3339: string, timeZone: Temporal.TimeZoneLike = "Asia/Tokyo") {
  return Temporal.Instant.from(rfc3339).toZonedDateTimeISO(timeZone);
}

// Temporal.ZonedDateTime → "2025-09-01T12:34:56.789+09:00"
export function zdtToRFC3339(t: Temporal.ZonedDateTime){
  return t.toString({ timeZoneName: "never", calendarName: "never" });
}

input["datetime-local"]との相互変換

HTMLフォームのdatetime-local型の ローカル日時文字列 の値を取り扱う際に活躍します

// "2025-10-01T12:34:56" → Temporal.ZonedDateTime
export function inputDateTimeToZdt(dateTimeString: string, timeZone: Temporal.TimeZoneLike = "Asia/Tokyo") {
  return Temporal.PlainDateTime.from(dateTimeString).toZonedDateTime(timeZone);
}

// Temporal.ZonedDateTime → "2025-10-01T12:34:56"
export function zdtToInputDateTime(t: Temporal.ZonedDateTime) {
  return t.toPlainDateTime().toString({ smallestUnit: "second" });
}

日本語日時表現

option引数に Intl.DateTimeFormat を加えて実務でよく利用される日本語表記に変換します。

// Temporal.ZonedDateTime → "2025年10月1日(水) 10:00:00"
export function zdtToLocalizedDateTime(
  t: Temporal.ZonedDateTime,
  options?: Intl.DateTimeFormatOptions,
): string {
  return t.toLocaleString("ja-JP", {
    year: "numeric",
    month: "long",
    day: "numeric",
    weekday: "short",
    hour: "numeric",
    minute: "numeric",
    second: "numeric",
    ...options,
  });
}

バリデーションでの利用例: Zodスキーマ連携

import { z } from "zod";
import { inputDateTimeToZdt, isBefore } from "./util";

const schema = z.object({
  StartsAt: z.string().transform((val) => inputDateTimeToZdt(val)),
  EndsAt: z.string().transform((val) => inputDateTimeToZdt(val)),
})
  .refine((values) => {
    if (values.StartsAt.equals(values.EndsAt)) return false;
    return isBefore(values.StartsAt, values.EndsAt);
  }, {
    message: "開始時間は終了時間より前に設定してください",
    path: ["StartsAt"],
  })