日時ライブラリのTemporalの色々なAPIをいじってみた

はじめに

Temporalは現状 TC39 proposal stage 3 のものを使用しています
今後APIが変わる可能性もあるのでご注意ください

JavaScriptで日時ライブラリを使用する機会があり、Temporalが stage 3 だったのを思い出したので、少し触ってみようと思いました。

せっかくなので、何か作りながら触ってみようということで、簡易的なカレンダーを作ってみました。

Temporalとは

JavaScript標準ライブラリへの追加を目指して開発中の日時ライブラリです。

Temporalについては日本語でもドキュメントを一部翻訳いただいていたり、Qiitaにすでにいい記事がいくつかあるので、詳しくはそちらをご覧ください。

• こちらは Stage 2 時点のものなのでAPIが変わっているものがありますが、Temporalとはなにか?というのがわかりやすいです。

• stage 3 時点での各APIについて説明されています

つくったもの

色々なAPIを使いたいと思い、カレンダーを作りました。 (ソースコードはこちら)

インストール

js-temporal/temporal-polyfillのREADMEを参考にライブラリをインストールします。

APIの詳細 (随時追加予定)

今回いじった部分をいくつかピックアップして使い方を説明していきます。

現在の日時

Temporal.Nowで現在の日時を取得できます。

Object の関係図にあるのですが、TemporalにはPlainDateTimeやPlainDate, PlainMonthDayなどのオブジェクトがあり、最初使い方に迷います。

どれを使えばいいかは以下の画像¹を参考にするとわかりやすいです。

Temporal.Now.zonedDateTimeISO().toString() // 2022-03-03T22:59:43.755983755+09:00[Asia/Tokyo]
Temporal.Now.zonedDateTimeISO().toLocaleString() // 2022/3/3 22:59:43 JST

Temporal.Now.plainDateISO().toString() // 2022-03-03
Temporal.Now.plainDateISO().toLocaleString() // 2022/3/3

また以下のように各種プロパティを使うことで、year,monthなどの値を取得することができます。

日付の計算

PlainDateTimeやPlainDateなどのオブジェクトには、add, subtractといったメソッドが用意されています。

const today = Temporal.Now.plainDateISO()
const tomorrow = today.add({ days: 1 })
const yesterday = today.subtract({ days: 1 })

また、比較はequalsやcompareを使います。
compareの戻り値は −1, 0, 1 なので、これで並び替えができます。

Temporal.PlainDate.compare(today, tomorrow)  // -1
Temporal.PlainDate.compare(today, today)     // 0
Temporal.PlainDate.compare(today, yesterday) // 1

今回は使わなかったのですが、期間を計算するuntil,sinceなどもあります。

また、withを使うと、日付だけ固定するなどの日時を作ることができるのも便利そうです。

const today = Temporal.Now.plainDateISO()
const firstDayOfMonth = today.with({ day: 1 })

フォーマットして表示

文字列として表示をしたいときに、toJSON, toString, toLocaleStringなどを使うことができます。

これらのメソッドのオプションで表示方法を指定することができます。

Temporal.Now.plainTimeISO().toString({
  smallestUnit: 'minute',
  roundingMode: 'floor',
})
// 23:25

Temporal.Now.plainDateISO().toLocaleString(undefined, {
  dateStyle: 'medium',
})
// 2022/03/03

また、他にTemporalのpolyfillにはIntlに対する拡張も含まれており、これを使ってもformatができるようです。

const dateTimeFormat = new Intl.DateTimeFormat()
console.log(dateTimeFormat.format(Temporal.Now.plainDateTimeISO())) // 2022/3/4 9:38:22
console.log(dateTimeFormat.format(Temporal.Now.plainDateISO())) // 2022/3/4
console.log(dateTimeFormat.format(Temporal.Now.plainDateTimeISO().toPlainTime())) // 9:40:24

これを使うと、以下のようにフォーマットができます。

console.log(firstDayOfThisMonth.date))// Temporal.PlainDate <2022-03-01>

const monthDateFormater = new Intl.DateTimeFormat(undefined, {
  day: 'numeric',
  month: 'numeric',
})
console.log(monthDateFormater.format(firstDayOfThisMonth.date)) // 3/1

PlainYearMonthやPlainMonthDateのフォーマット方法については、こちらの記事で説明していますので、ご覧ください。

その他

Cookbookに色々な事例付きで使い方が乗っているので、参考にしてみてください。

タイムゾーンについてはこちらで説明されています。

まとめ

Temporalは機能が豊富すぎて、最初どう使えばいいのか分からなかったのですが、基本のオブジェクトについてはわかってきました。
もう少し触りながら、Temporalの概念や細かいAPIの仕様なども調べてみようと思います。

参考

• tc39/proposal-temporal: Provides standard objects and functions for working with dates and times.
• js-temporal/temporal-polyfill: Polyfill for Temporal (under construction)
• Temporal documentation
• Temporal walkthrough - Google スライド
• JavaScriptの日時処理はこう変わる！　Temporal入門 - Qiita
• Temporal で JavaScript の次世代の日時処理に触れてみる - Qiita

1. https://tc39.es/proposal-temporal/docs/ja/index.html より引用 ↩