Temporal APIと日時計算の正確なモデル

なぜ日時APIに「正確なモデル」が要るのか

日時のバグは「たまにずれる」形で表面化するため、再現も発見も難しいのが厄介です。月初の集計が1日ずれる、夏時間の切替日だけ予約が二重になる、サーバーとブラウザで同じ「3月1日」が別の瞬間を指す——これらは個別のコーディングミスというより、時刻を1つの数値で雑に表すという旧来モデルの帰結です。Temporalは「壁掛け時計の時刻」と「物理的な瞬間」を別物として型で区別し、暦やタイムゾーンの規則を明示的に適用させることで、これらを構造的に防ぎます。前提として基礎は JavaScript を、時刻が内部で数値として持たれる点は JavaScriptの数値表現とIEEE754が生む落とし穴 を押さえておくと理解が早いです。

Date の設計上の欠陥

Date は1995年のJavaScript誕生時にJavaの旧 java.util.Date を写して作られ、その欠陥ごと引き継ぎました。中心的な問題は次の通りです。

Date の実体はエポック（1970-01-01T00:00:00 UTC）からの経過ミリ秒という1つの数値だけです。タイムゾーン情報を内部に持たず、getHours() のような「ローカル系」のメソッドは呼び出した実行環境のタイムゾーンを使って毎回その場で換算します。つまり同じ Date 値でも、東京のサーバーとロンドンのブラウザでは getDate() が別の日を返し得ます。

Temporal の中核：不変オブジェクトと型の分離

Temporalはこれらを根本から作り直した提案です。設計原則は2つに集約できます。

1. 全オブジェクトが不変（immutable）：add with round などはすべて元を変えず新しいインスタンスを返す。共有しても安全で、加工の副作用が消えます。
2. 「時刻の種類」を型で分ける：タイムゾーンを持たない「壁掛け時計の時刻」（Plain系）と、地球上の特定の瞬間（Instant / ZonedDateTime）を別の型として区別します。

この型分離が本質です。たとえば「毎朝9時に通知」の9時は、どのタイムゾーンでも9時であってほしい壁掛け時計の時刻＝Plain です。一方「打ち上げは協定世界時の正確なこの瞬間」は地球上で一意な物理的瞬間＝Instant です。両者を1つの Date で兼ねていたことが、旧来の混乱の元でした。

// すべて不変。元のインスタンスは変わらず、新しい値が返る
const d = Temporal.PlainDate.from('2026-03-01'); // 月は1始まり
const next = d.add({ days: 7 });                 // 2026-03-08（dはそのまま）

// 物理的な瞬間。タイムゾーンに紐づけて初めて「壁掛け時刻」になる
const meeting = Temporal.ZonedDateTime.from(
  '2026-03-01T09:00[Asia/Tokyo]'
);
meeting.toInstant().epochNanoseconds; // 全世界で一意な瞬間

PlainDateTime は「3月1日9時」までは決めるがタイムゾーンを欠くため、まだ物理的瞬間ではありません。これに Asia/Tokyo のようなタイムゾーンを与えて初めて ZonedDateTime（＝一意な Instant）が確定します。Plain と Zoned の往復で必ずタイムゾーンを通すこの設計が、後述の夏時間問題を表に引きずり出します。

Plain と Zoned の境界：夏時間(DST)をどう扱うか

夏時間（DST）の切替日には、存在しない時刻と二度ある時刻が生まれます。たとえば米国で春に時計が午前2時から3時へ飛ぶ日、02:30 は実在しません。秋に3時から2時へ戻る日、01:30 は1日に2回訪れます。Date はこの不規則さを暗黙に握りつぶし、どちらの瞬間を指すか不定でした。

Temporalは PlainDateTime（壁掛け時刻）から ZonedDateTime（瞬間）へ変換する瞬間に、この曖昧さを明示的な選択肢として扱わせます。

// DSTで存在しない壁掛け時刻を瞬間へ写すとき、挙動を選べる
const pdt = Temporal.PlainDateTime.from('2026-03-08T02:30');
pdt.toZonedDateTime('America/New_York', { disambiguation: 'reject' });
// → RangeError（存在しない時刻を握りつぶさず明示的に弾く）

重要なのは、ZonedDateTime 同士の「N日後」と「N時間後」が別物になる点です。add({ hours: 24 }) は物理的に24時間後の瞬間へ進めるのに対し、add({ days: 1 }) は暦の上で翌日の同じ壁掛け時刻へ進めます。DST切替を跨ぐ日、後者は実際の経過が23時間や25時間になり得ます。Date ではこの区別が表現できず、「日付の加算」を時間ミリ秒で代用したコードが切替日だけ1時間ずれていました。

暦(カレンダー)とうるう秒の正しい位置づけ

ZonedDateTime と PlainDate は**暦（calendar）**も保持します。既定は iso8601（グレゴリオ暦の代理）ですが、japanese（和暦）や hebrew、islamic なども扱え、year month のような数値が暦ごとに正しく解釈されます。たとえば年内の月数が12でない暦では、add({ months: 1 }) の意味が暦規則に従って決まります。これも「数値の足し算」では表せなかった情報です。

うるう秒の扱いは特に誤解されがちです。Temporalの Instant と内部時刻はうるう秒を持たない連続したタイムライン（UTCのうるう秒を平滑化したPOSIX的なエポック時刻）で表されます。つまり 23:59:60 のような値は受け付けず、60 秒は存在しないものとして丸められます。

永続化と相互運用

不変で型が分かれている分、保存・送信時の形式選びも明確になります。物理的な瞬間を保存するなら、タイムゾーンまで含む ZonedDateTime のISO文字列（...[Asia/Tokyo] 付き）か、地点情報が不要なら Instant（UTCの Z 付き）を使います。一方、壁掛け時刻そのもの（毎朝9時など）はタイムゾーンを付けずに PlainTime / PlainDate として保存するのが正解で、ここに無理にタイムゾーンを与えると「どこかの9時」に固定されて意図がずれます。

// 瞬間として保存（地点も復元したいなら ZonedDateTime 文字列）
zdt.toString();        // "2026-03-01T09:00:00+09:00[Asia/Tokyo]"
zdt.toInstant().toString(); // "2026-03-01T00:00:00Z"（UTCの瞬間のみ）

Temporalオブジェクトは構造化クローンの対象にもなり得ますが、ワーカー間やストレージへ渡す際は文字列化してから扱うのが堅実です（クローンの可否や落とし穴は 構造化クローンとTransferable を参照）。Date との橋渡しは Temporal.Instant.fromEpochMilliseconds(date.getTime()) などで瞬間を介して行い、ローカル時刻のメソッドを経由しないのが安全です。

まとめ