API Reference
@bi-shop-it/lib/date の全関数・型リファレンス。
すべて @bi-shop-it/lib/date から named import で使用する。
import { dateOnly, addDays, formatDateOnly } from '@bi-shop-it/lib/date';DateOnly
YYYY-MM-DD 形式のブランド型文字列。時刻情報を持たない日付を表す。
type DateOnly = string & { readonly __brand: 'DateOnly' };DateOnlySchema は valibot のバリデーションスキーマ。フォーム入力や API レスポンスの検証に使用する。
dateOnly(s: string): DateOnly
文字列を検証し DateOnly を返す。不正な値の場合はエラーを投げる。
dateOnly('2026-06-15'); // "2026-06-15"
dateOnly('2026-02-29'); // Error: 2026年は閏年ではない
dateOnly('2026/06/15'); // Error: フォーマットが不正注意: 実在しない日付（2月30日等）もエラーになる。正規表現だけでなく Date で実在性を検証している。
dateOnlyFromDate(d: Date): DateOnly
Date から UTC 基準で DateOnly を生成する。ローカルタイムゾーンは考慮しない。
dateOnlyFromDate(new Date('2026-06-15T23:30:00.000Z'));
// "2026-06-15"（UTC 基準。JST では 6/16 だが UTC の日付を返す）dateTimeToDateOnly との使い分け: タイムゾーンを考慮して日付を取得したい場合は dateTimeToDateOnly(dt, timeZone) を使う。dateOnlyFromDate は常に UTC 基準である。
dateOnlyToDate(d: DateOnly): Date
DateOnly を UTC midnight の Date に変換する。外部ライブラリとの連携など、Date オブジェクトが必要な場合に使用する。
dateOnlyToDate(dateOnly('2026-06-15'));
// new Date('2026-06-15T00:00:00.000Z')addDays(d: DateOnly, days: number): DateOnly
指定日数を加算する。負の値で減算。月・年の境界を自動で跨ぐ。
addDays(dateOnly('2026-06-15'), 5); // "2026-06-20"
addDays(dateOnly('2026-06-15'), -3); // "2026-06-12"
addDays(dateOnly('2026-01-30'), 3); // "2026-02-02"（月跨ぎ）addMonths(d: DateOnly, months: number): DateOnly
指定月数を加算する。負の値で減算。月末日が存在しない場合はその月の末日に補正する。
addMonths(dateOnly('2026-01-15'), 2); // "2026-03-15"
addMonths(dateOnly('2026-01-31'), 1); // "2026-02-28"（2月に31日は存在しない → 末日に補正）
addMonths(dateOnly('2026-03-31'), 1); // "2026-04-30"（4月に31日は存在しない → 末日に補正）addYears(d: DateOnly, years: number): DateOnly
指定年数を加算する。負の値で減算。閏年の 2/29 から平年に加算する場合は 2/28 に補正する。
addYears(dateOnly('2026-06-15'), 1); // "2027-06-15"
addYears(dateOnly('2024-02-29'), 1); // "2025-02-28"（閏年 → 平年の補正）diffDays(a: DateOnly, b: DateOnly): number
2つの日付の差を日数で返す。a - b の符号を持つ。
diffDays(dateOnly('2026-06-18'), dateOnly('2026-06-15')); // 3（a が後）
diffDays(dateOnly('2026-06-15'), dateOnly('2026-06-18')); // -3（a が前）
diffDays(dateOnly('2026-06-15'), dateOnly('2026-06-15')); // 0（同日）endOfMonth(d: DateOnly): DateOnly
その月の末日を返す。閏年も正しく処理する。
endOfMonth(dateOnly('2026-01-15')); // "2026-01-31"
endOfMonth(dateOnly('2026-04-15')); // "2026-04-30"
endOfMonth(dateOnly('2026-02-15')); // "2026-02-28"
endOfMonth(dateOnly('2024-02-15')); // "2024-02-29"（閏年）DateTime
ミリ秒付き UTC ISO 8601 形式のブランド型文字列。時刻情報を含む日時を表す。
type DateTime = string & { readonly __brand: 'DateTime' };制約: ミリ秒（.000）が必須で、末尾は Z（UTC）のみ許可する。タイムゾーンオフセット付き（+09:00 等）は受け付けない。この制約により dateTimeFromDate() の出力と形式が常に一致する。
DateTimeSchema は valibot のバリデーションスキーマ。
dateTime(s: string): DateTime
文字列を検証し DateTime を返す。
dateTime('2026-06-15T09:00:00.000Z'); // OK
dateTime('2026-06-15T09:00:00Z'); // Error: ミリ秒がない
dateTime('2026-06-15T09:00:00.000+09:00'); // Error: UTC 以外は不正
dateTime('2026-06-15'); // Error: 時刻がない（DateOnly を使う）dateTimeFromDate(d: Date): DateTime
Date を DateTime に変換する。不正な Date（new Date('invalid') 等）の場合はエラーを投げる。
dateTimeFromDate(new Date('2026-06-15T05:30:00.000Z'));
// "2026-06-15T05:30:00.000Z"
dateTimeFromDate(new Date('invalid'));
// Error: Invalid DatedateTimeToDate(dt: DateTime): Date
DateTime を Date に変換する。外部ライブラリとの連携など、Date オブジェクトが必要な場合に使用する。
dateTimeToDate(dateTime('2026-06-15T09:00:00.000Z'));
// new Date('2026-06-15T09:00:00.000Z')dateTimeNow(): DateTime
現在時刻の DateTime を返す。テスト時は setClock で制御できる。
dateTimeNow(); // "2026-06-15T09:00:00.000Z"（現在時刻）Timezone
タイムゾーンを明示的に指定して日付変換を行う関数群。timeZone 引数は IANA タイムゾーン名（'Asia/Tokyo', 'UTC' 等）を指定する。不正なタイムゾーン名の場合はエラーを投げる。
dateOnlyToday(timeZone: string): DateOnly
指定タイムゾーンでの「今日」の日付を返す。テスト時は setClock で制御できる。
// UTC が 2026-06-15T23:00 のとき:
dateOnlyToday('UTC'); // "2026-06-15"
dateOnlyToday('Asia/Tokyo'); // "2026-06-16"（JST では翌日）dateOnlyFromDate(new Date()) との違い: dateOnlyFromDate は常に UTC 基準で日付を返す。ユーザーのタイムゾーンでの「今日」が必要な場合は dateOnlyToday を使う。
dateTimeToDateOnly(dt: DateTime, timeZone: string): DateOnly
DateTime を指定タイムゾーンでの DateOnly に変換する。
const dt = dateTime('2026-06-15T23:30:00.000Z');
dateTimeToDateOnly(dt, 'Asia/Tokyo'); // "2026-06-16"（JST では翌日）
dateTimeToDateOnly(dt, 'UTC'); // "2026-06-15"dateOnlyFromDate との違い: dateOnlyFromDate は常に UTC 基準。タイムゾーンを考慮した日付変換にはこの関数を使う。
Clock
テスト用の時刻制御。dateTimeNow と dateOnlyToday が参照する現在時刻を差し替える。プロダクションコードでは使用しない。
import { setClock, resetClock } from '@bi-shop-it/lib/date/testing';setClock(fn: () => Date): void
現在時刻を返す関数を差し替える。
setClock(() => new Date('2026-06-15T10:00:00.000Z'));
dateTimeNow(); // "2026-06-15T10:00:00.000Z"resetClock(): void
setClock で差し替えた時刻を元に戻す。テストの afterEach で必ず呼ぶ。
afterEach(() => {
resetClock();
});