date-fns

date-fns

date-fns v4 の日付計算、書式設定、解析、FP モード、ロケール、公式タイムゾーンパッケージ @date-fns/tz／@date-fns/utc には、このスキルを使用してください。

ワークフロー

1. コードを変更する前に、ローカル環境を確認します。
   • パッケージ：date-fns、任意で @date-fns/tz、@date-fns/utc（存在する場合はレガシーの date-fns-tz も）。
   • バージョン：第一級の { in }／TZDate／UTCDate 相互運用には、date-fns ≥ 4 を優先します。v3 もよく使われていますが、date-fns-tz を使わない限り、ローカル環境のみでの利用となります。
   • タイムゾーンの用途：システムローカルの UI、UTC に正規化したサーバー側の計算、または名前付き IANA タイムゾーン（ユーザー／会場／本社）。
   • インポート："date-fns"、"date-fns/fp"、"date-fns/locale/*"、"date-fns/constants" から名前付きでインポートします。
2. バージョンが不明確な場合や、タイムゾーン、Unicode トークン、SSR、メジャーアップグレードに関わる作業では、ドキュメントを更新します。source-map.md から始めてください。
3. 詳細の参照先：
   • インストール、インポート、基本概念、Invalid Date：setup-core.md。
   • format／parse／parseISO、Unicode トークン：format-parse.md。
   • 加算／設定／境界、差分、Interval、Duration：manipulate-compare.md。
   • TZDate、UTCDate、tz／utc、transpose、DST、SSR：timezones.md。
   • FP、ロケール、TypeScript：fp-locales-types.md。
   • v2→v3→v4 および date-fns-tz の移行：migration-pitfalls.md。
4. プロジェクトでインストールされているメジャーバージョンと既存のインポートスタイルに合わせます。タイムゾーンの意味論上必要でない限り、@date-fns/tz や @date-fns/utc を追加しないでください。
5. 型チェックに加え、該当する場合は Invalid Date、暦日単位と経過時間単位の差分、タイムゾーン／SSR の境界ケースに絞ったテストで検証します。

タイムゾーンの判断ツリー

System-local calendar / host TZ only?
  → plain Date + date-fns

UTC-only math (server day, charts, no IANA zones)?
  → @date-fns/utc (UTCDate / UTCDateMini or { in: utc })

Named IANA zone or multi-zone product?
  → @date-fns/tz (TZDate / TZDateMini or { in: tz("…") })

Stuck on date-fns v3?
  → upgrade to v4 + official packages, or use legacy date-fns-tz until then

基本的な判断基準

• 素の date-fns はシステムローカルであり、UTC ライブラリではありません。ローカル以外の暦日フィールドには @date-fns/utc または @date-fns/tz を使用します。
• 名前付きインポートを優先します。定数はメインのバレルではなく、"date-fns/constants" からインポートします。
• format の前に必ず isValid を実行します。format は Invalid Date に対して RangeError をスローします。
• Unicode トークンには yyyy-MM-dd を使用し、Moment 形式の YYYY-MM-DD／DD（週番号基準の年／年内の日）は使用しないでください。format-parse.md を参照してください。
• parseISO("YYYY-MM-DD") → ローカルの午前 0 時、new Date("YYYY-MM-DD") → UTC の午前 0 時です。混同しないでください。
• 暦日については differenceInCalendar* を、経過した完全な単位については differenceIn* を優先します。
• タイムゾーンが混在する場合やプリミティブ値を使う場合は、{ in: tz("…") } または { in: utc } でコンテキストを固定します。指定がない場合、最初のオブジェクトの Date／拡張型の引数が優先され、引数の順序によって日付計算の結果が変わることがあります。
• new TZDate(iso, zone) とレガシーの toZonedTime は異なります。同じ瞬間を表しますが、壁時計上の時刻は異なります。壁時計の時刻を再マッピングするには transpose を使用します。
• ライブラリ境界では 完全版の TZDate／UTCDate を優先します。Mini バリアントでは、ゾーン対応の toString／ロケール書式設定関数が省かれます（システムタイムゾーンが漏れる原因になります）。
• @date-fns/tz とサードパーティ製の date-fns-tz を混同しないでください。

検証

リポジトリで定義されているコマンドを優先します。該当する項目を確認してください。

• bun pm ls date-fns @date-fns/tz @date-fns/utc（移行する場合は date-fns-tz も）。
• DateArg、オプションの型、拡張型の戻り値の型を型チェックします。
• テスト：有効／無効な解析、Unicode トークン、暦日単位と経過時間単位の差分、逆順の区間、DST の春の時刻変更／秋の時刻変更、{ in } と引数順によるタイムゾーン選択。
• SSR／ハイドレーションのスモークテスト：サーバー（多くの場合 UTC）とクライアント（ローカル）で「今日」やローカル日の境界をまたいで書式設定する場合。

実行した検査と実行しなかった検査、残っているバージョン上の前提を報告してください。