date-fns

date-fns + @date-fns/tz

目的

最新の date-fns とネイティブのタイムゾーンパッケージ @date-fns/tz を使用して、日付／時刻のコードを実装、レビュー、リファクタリングする際にこのスキルを使用します。

バージョンの基準（呼び出し時に再確認）

• date-fns の最新確認済みバージョン：4.1.0
• @date-fns/tz の最新確認済みバージョン：1.4.1
• 再確認用コマンド：
  • npm view date-fns version
  • npm view @date-fns/tz version
  • npm view date-fns dist-tags --json
  • npm view @date-fns/tz dist-tags --json

使用する場面

• 日付の解析、検証、フォーマット、比較、計算。
• タイムゾーンを考慮したビジネスロジックの構築（スケジューリング、境界、レポート作成）。
• 日付ロジックを不変のユーティリティパターンに移行する場合。
• DST やトークン形式のバグに対するコードの堅牢性を高める場合。

必須ルール

• ネイティブのタイムゾーンパッケージ @date-fns/tz を使用します。
• date-fns-tz は推奨しないでください。
• 既存のコードが date-fns-tz を使用している場合は、@date-fns/tz への移行を提案してください。
• 一度だけ解析し、早い段階で検証して（isValid）、操作には Date の値を渡します。
• Unicode トークン（yyyy、MM、dd）を正しく使用し、Moment 形式のトークンを想定しないでください。
• タイムゾーンに依存する計算では、明示的なタイムゾーンコンテキスト（TZDate または { in: tz("...") }）を使用します。

標準的なインポート

import { format, parseISO, isValid, addDays, startOfDay } from "date-fns";
import { TZDate, tz, tzOffset, tzName, tzScan } from "@date-fns/tz";

ワークフロー

1) 入力を正規化する

• 変換には parseISO／toDate を使用します。
• isValid で検証します。
• 内部値には Date／TZDate を使用し、文字列を混在させた計算は避けます。

2) 純粋なヘルパーで計算する

• add/sub、differenceIn*、startOf*/endOf*、isSame*、isWithinInterval を優先します。
• 明確な理由がない限り、セッターによる Date の変更は避けます。

3) タイムゾーンコンテキストを明示的に適用する

• オプション A：TZDate の値を使用します。
• オプション B：決定的なタイムゾーンコンテキストを指定するため、tz("Area/City") と date-fns の in オプションを使用します。

4) 安全にフォーマット／出力する

• 表示には format を使用します。
• 交換形式には標準規格対応のヘルパー（formatISO、formatRFC3339）を使用します。
• 転送形式と表示形式は分けて管理します。

成果物

回答には以下を含めます。

• 正確なインポート。
• 用途に必要な、正しく動作する最小限の関数セット。
• タイムゾーンの方針（TZDate と { in: tz(...) } のどちらを使うか）とその理由。
• エッジケースに関する注意事項（DST の境界、トークンの正確性、無効な入力）。

段階的な情報開示

必要なものだけを読み込みます。

• 基本的なヘルパーについては reference/core-functions.md。
• @date-fns/tz のパターンについては reference/native-timezones.md。
• インポート／ランタイムの実践方法については reference/imports-and-practices.md。
• トークンの正確性については reference/format-parse-tokens.md。
• すぐにコピーして使えるスニペットについては reference/examples.md。
• 「date-fns-tz は決して使用しない」という厳格な指針については reference/anti-patterns.md。
• バージョンの確認方法とソースへのリンクについては reference/version-and-sources.md。