date-fns/tzを触ってみた

はじめに

https://blog.date-fns.org/v40-with-time-zone-support/
date-fnsのv4.0でタイムゾーンがサポートされました。
今までdate-fnsを導入したプロジェクトでタイムゾーンを考慮した日時を扱う場合は、外部パッケージのdate-fns-tzと組み合わせて実装していましたが、今回のアップデートでdate-fns/tzという新しいパッケージとして使用できるようになりました。

この記事では、時刻表記に関する知識と、それを踏まえたdata-fns/tzの使い方を見ていきます。

時刻表記について

JavaScriptのDate()コンストラクタの引数のうち、日付文字列の形式はISO8601で定められています。date-fns/tzのREADMEでもこの日付文字列が使われているため、ここではISO 8601形式がどのようなものなのかおさらいしておきます。

Time zone	ISO 8601形式
日本標準時(JST)	2024-09-27T13:50:40+09:00
協定世界時(UTC)	2024-09-27T04:50:40Z

• 「年、月、日」は-(ハイフン) で区切る。
• 「時、分、秒」は:(コロン)で区切る。
• 「日付」と「時間」の区切りにTを用いる。
• 協定世界時(UTC)の場合は末尾にZ記号をつける。
• UTCより先に進んでいる時間帯の場合は+、UTCより後に遅れている時間帯の場合は-として、時刻の後ろに ±hh:mm, ±hhmm, ±hh のいずれかを添える

ISO 8601形式には基本形式と拡張形式がありますが、JavaScriptのDate()コンストラクタにおいては拡張形式を採用しているため、基本形式の説明は省略しています。

date-fns/tzの使い方

インストール

$ npm install @date-fns/tz --save

よく使いそうなものに絞って紹介します。

TZDate

TZDate()はDate()に似たAPIを持ちますが、日時の計算を指定されたタイムゾーンで行います。
TZDate()コンストラクタの引数は末尾の引数以外はDate()コンストラクタの引数と同じです。

new TZDate(2022, 2, "Asia/Singapore");

new TZDate(timestamp, "Asia/Singapore");

new TZDate("2024-09-12T00:00:00Z", "Asia/Singapore");

DST（サマータイム）も計算してくれるようです。

import { TZDate } from "@date-fns/tz";
import { addHours } from "date-fns";

// 実行環境のタイムゾーンが America/Los_Angeles だと想定します。
// DST（サマータイム）中の 2022年3月13日 日曜日 02:00:00 の時間を扱います。

// 実行環境のタイムゾーンに基づき、DST（サマータイム）が計算されて 02:00 ではなく 03:00 が出力されます。
const date = new Date(2022, 2, 13);
addHours(date, 2).toString();
//=> 'Sun Mar 13 2022 03:00:00 GMT-0700 (Pacific Daylight Time)'

// タイムゾーンを Asia/Singapore に指定すると、DST（サマータイム）はないので 02:00 が出力されます。
const tzDate = new TZDate(2022, 2, 13, "Asia/Singapore");
addHours(tzDate, 2).toString();
//=> 'Sun Mar 13 2022 02:00:00 GMT+0800 (Singapore Standard Time)'

withTimeZone

指定したタイムゾーンで新たにTZDateインスタンスを作成できます。

const sg = new TZDate(2022, 2, 13, "Asia/Singapore");
const ny = sg.withTimeZone("America/New_York");

sg.toString();
//=> 'Sun Mar 13 2022 00:00:00 GMT+0800 (Singapore Standard Time)'

ny.toString();
//=> 'Sat Mar 12 2022 11:00:00 GMT-0500 (Eastern Standard Time)'

tz

date-fnsの関数にタイムゾーンのコンテキストを指定できます。

import { isSameDay } from "date-fns";
import { tz } from "@date-fns/tz";

isSameDay("2024-09-09T23:00:00-04:00", "2024-09-10T10:00:00+08:00", {
  in: tz("Europe/Prague"),
});
//=> true

上記のinオプションはdate-fnsのv4.0以降でしか使用できません。
isSameDay()だけでなく、date-fnsのv4.0以降、あらゆる関数にタイムゾーンを指定するオプションが追加されているようです。

まとめ

今回の記事では、date-fnsのv4.0で新たに追加されたタイムゾーンサポートと、date-fns/tzパッケージの基本的な使い方について解説しました。
date-fnsはv5.0に向けてTemporal APIへの対応も視野に入れており、今後のアップデートにも注目ですね。