date-fnsのメソッドでできること

いい加減、日付ライブラリくらい使えるようになろうかなということで、date-fnsを調べたので、そのメモを残します。
当社調べでは…241個のメソッドを提供しているようです。頭悪いので、typescript定義ファイルを上から見ていきます。
全て見たつもりですが、見落としがあったらごめんなさい。責任は取れないです。

詳細はちゃんとドキュメントを読みましょう：https://date-fns.org/docs/Getting-Started

まとめ

良くわからんものを除き、date-fnsのメソッドを26個に分類した。

基本的なメソッド
- format: Date型→文字列
- parse: 文字列→Date型
- add: 足し算
- sub: 引き算
- get: getter
- set: setter
- is: 判定いろいろ　※42個をひとまとめにしてしまったので、詳細はis節を参照。
- compare: 比較
役に立ちそうなメソッド
- differenceIn: 2つの日付の間隔を、日付単位や年単位などで取得。
- previous/next: 次の月曜日や前の水曜日を取得。
- startOf/endOf: 日付の余計な部分をそぎ落としていい感じにしてくれる。
- lastDayOf: ある特定の週や、年月・年などの最終日を取得。
- getXXinYY: ある年月に含まれる日付を返す等。
日付の配列に対するメソッド
- min/max: 最古/最新を取得する。
- closest: 配列内の各日付で、最も指定した日付に近い日付を探す。
期間(独自のInterval型)に対するメソッド
- eachXXOfInterval: 指定した期間に含まれる要素を返却する。
- clamp: 期間内で、ある日付に最も近い日付を返却する。
- overlappingInterval: 期間の重なりの判定や重なりに含まれる日付の取得。
その他マニアックそうなメソッド
- DefaultOptions: デフォルトオプション。週の開始曜日とか。
- roundToNearestMinutes: 分単位についての四捨五入。
独自型の変換用
- intervalToDuration
- milliseconds
正直、いらなそうなメソッド

補足：バージョン

    "date-fns": "2.30.0",

補足：Type

そもそも前提として、date-fnsはNodeJS標準のDate型を使うライブラリです。parseした結果は標準のDate型で受け取りますし、formatしたい日付は標準のDate型で指定することができます。
しかし、利便性のためか、以下の4点だけ独自の型定義を提供しているらしい。

Locale
- まぁ、ロケールでしょう。きっと…型定義見ましたが、複雑でした。
Duration
- 日付と日付の間隔。3時間半とか。2カ月とか。

type Duration = { years?: number, months?: number, weeks?: number, days?: number, hours?: number, minutes?: number, seconds?: number, };

Interval
- 開始～終了を持つ一定の期間。2022年1月3日～2023年5月15日とか。

type Interval = { start: Date | number, end: Date | number };

Day
- 曜日を示す型かな。。。

type Day = 0 | 1 | 2 | 3 | 4 | 5 | 6;

メソッド

良くわからんもの

いきなりだけど、以下は良くわからんかった。

add

日付に3時間を足し算したり、日付と期間を足したりできます。営業日を足すというものもあるが、祝日は考慮できなさそう。

clamp

期間内で、ある日付に最も近い日付を返却する。

clamp

closest

配列内の各日付で、最も指定した日付に近い日付を探す。

compare

日付の比較。

conversion

ミリ秒を時間に、日付を週間になど、単位を変える系。いろいろあるけど把握が面倒で使いづらそう…
date-fnsの検索欄で"Conversion Helpers"と入れると一覧表示される。

DefaultOptions

ようわからんが、getter/setterがある。調べてみるとライブラリの使い道が増すかも。

differenceIn

2つの日付の差を任意の単位で取得する。
また、differenceInCalendar版もある。これは、計算前に余計な部分をそぎ落としてくれるので、例えば2000年12月31日と2020年1月1日の間隔を2020-2000 = 20としてくれる。

eachXXOfInterval

指定した期間に含まれる要素を返却する。例えば、1月1日～1月20日の間の日付（1～20日）とか。

eachDayOfInterval
...

eachWeekendOf

年月・または年に含まれる週末だけを返してくれる。なぜこれだけあるんだろうか…

startOf/endOf

日付の余計な部分をそぎ落としていい感じにしてくれる。月末とかね。Yesterday,Today,Tomorrow等もある。

format

いろんなformatがある。文字列→日付。

format
...

fromUnixTime

unixtimeから日付型を取得する。標準のDate型のコンストラクタと何が違うんだろうか。。。

fromUnixTime

get

要素から時間等の1要素を取得する。※月はDate型と同じで-1した値になるので注意。1月は0、12月は11。

getDay
...

getXXinYY

ある年月に含まれる日付を返すとか、そういう関数がちらほら。

intervalToDuration

開始～終了の期間を元に、間隔（3日と4時間とか）を取得する。

intervalToDuration

is

isから始まる判定メソッドが系42個ある。内訳は以下のとおり。

曜日等
- isSunday
- isMonday
- isTuesday
- isWednesday
- isThursday
- isFriday
- isSaturday
- isWeekend
月初/月末
- isFirstDayOfMonth
- isLastDayOfMonth
現在との比較
- isThisHour
- isThisISOWeek
- isThisMinute
- isThisMonth
- isThisQuarter
- isThisSecond
- isThisWeek
- isThisYear
- isFuture
- isPast
- isToday
- isTomorrow
- isYesterday
2つの日付を比較(特定要素で)
2つの日付を比較(その他)
- isAfter
- isBefore
- isEqual
その他いろいろ
- isExists: 年月日の存在判定
- isDate: Date型かどうかを判定
- isMatch: 文字列があるformatにmatchするか（そもそも解釈できるか）の判定
- isLeapYear: うるう年判定
- isValid: Date型がそもそも不正かどうかの判定
- isWithinInterval: 期間内かどうかの判定

lastDayOf

ある特定の週や、年月・年などの最終日を取得。

lastDayOfMonth
...

min/max

日付配列の中で、最古・最新の物を取得。

milliseconds

期間をミリ秒単位に変換する。

milliseconds

overlappingInterval

2つの期間の重なりに関するメソッド。重なりの判定や、重なっている日付の一覧取得。

previous/next

次の月曜日とかを取得できる。

parse

文字列を日付に変換する。

parse
...

roundToNearestMinutes

分単位についての四捨五入。なぜか分だけある…

roundToNearestMinutes

set

日付の特定要素だけを編集する。

sub

日付から引き算を行う。

sub
subDays
...

toDate

Date型に変換する。

toDate