@digitalwalletcorp/utils 0.2.0 → 0.4.0

package/src/date-util.ts

@@ -0,0 +1,448 @@
+import { DateTime, Duration as LuxonDuration } from 'luxon';
+import type { DateTimeUnit } from 'luxon';
+
+/** 日時として解釈する値。string はISO形式または inputFormat の書式、number は epoch ミリ秒 */
+export type DateInput = string | Date | number | null | undefined;
+
+/** 日時の切り捨て(startOf / endOf)に使う単位 */
+export type DateUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+
+/** 期間の単位 */
+export type TimeUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
+
+/** 日時の加算・減算に使う期間。負の値で減算になる */
+export interface Duration {
+  years?: number;
+  quarters?: number;
+  months?: number;
+  weeks?: number;
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  milliseconds?: number;
+}
+
+/**
+ * 日時を解釈するときのオプション
+ */
+export interface ParseDateOptions {
+  /** 入力の書式。配列の場合は先頭から順に試す。いずれにも一致しない場合はISO形式として解釈する */
+  inputFormat?: string | string[];
+  /** ゾーン情報を含まない入力をどのタイムゾーンの日時とみなすか(IANA名)。既定は 'UTC' */
+  inputTimezone?: string;
+  /** 解釈した日時に加算する期間。startOf / endOf より先に適用する */
+  duration?: Duration;
+  /** 指定した単位の最初の時点に切り捨てる(month なら月初の00:00:00.000) */
+  startOf?: DateUnit;
+  /** 指定した単位の最後の時点に切り上げる(month なら月末の23:59:59.999) */
+  endOf?: DateUnit;
+}
+
+/**
+ * 日時を文字列にするときのオプション
+ */
+export interface FormatDateOptions extends ParseDateOptions {
+  /** 出力の書式。省略時はISO形式 */
+  outputFormat?: string;
+  /** 出力に使うタイムゾーン(IANA名)。既定は 'UTC' */
+  outputTimezone?: string;
+  /** 日時として解釈できない値に対する出力。既定は 'Invalid Date' */
+  invalidText?: string;
+}
+
+/** タイムゾーンの略称。夏時間のないタイムゾーンでは daylight を持たない */
+export interface TimezoneAbbreviation {
+  standard: string;
+  daylight?: string;
+}
+
+/** IANA名をキーにしたタイムゾーンの略称の表 */
+export type TimezoneAbbreviations = Record<string, TimezoneAbbreviation>;
+
+/**
+ * タイムゾーンの略称を解決するときのオプション
+ */
+export interface TimezoneAbbrOptions {
+  /** 夏時間かどうかを判定する時点。既定は現在時刻 */
+  at?: Date;
+  /** 既定の表に追加・上書きする略称 */
+  abbreviations?: TimezoneAbbreviations;
+}
+
+const DEFAULT_TIMEZONE = 'UTC';
+
+const TIMESTAMP_FORMAT = `yyyy-MM-dd'T'HH:mm:ss.SSSZZ`;
+
+/** 1970-01-01 を表すExcelの日付シリアル値 */
+const EXCEL_EPOCH_SERIAL = 25569;
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+
+const MILLISECONDS_PER_HOUR = 60 * 60 * 1000;
+
+const GMT_OFFSET = /GMT[+-]\d{1,2}(:\d{2})?/g;
+
+/**
+ * 略称の既定の表。略称は世界で一意ではないため(CST は米国中部・中国などで使われる)、このライブラリが採用する表記である
+ */
+const DEFAULT_TIMEZONE_ABBREVIATIONS: TimezoneAbbreviations = {
+  'UTC': { standard: 'UTC' },
+  'Asia/Tokyo': { standard: 'JST' },
+  'Asia/Seoul': { standard: 'KST' },
+  'Asia/Shanghai': { standard: 'CST' },
+  'Asia/Hong_Kong': { standard: 'HKT' },
+  'Asia/Taipei': { standard: 'CST' },
+  'Asia/Singapore': { standard: 'SGT' },
+  'Asia/Manila': { standard: 'PHT' },
+  'Asia/Bangkok': { standard: 'ICT' },
+  'Asia/Ho_Chi_Minh': { standard: 'ICT' },
+  'Asia/Jakarta': { standard: 'WIB' },
+  'Asia/Kolkata': { standard: 'IST' },
+  'Asia/Dubai': { standard: 'GST' },
+  'Australia/Sydney': { standard: 'AEST', daylight: 'AEDT' },
+  'Pacific/Auckland': { standard: 'NZST', daylight: 'NZDT' },
+  'Europe/London': { standard: 'GMT', daylight: 'BST' },
+  'Europe/Paris': { standard: 'CET', daylight: 'CEST' },
+  'Europe/Berlin': { standard: 'CET', daylight: 'CEST' },
+  'Europe/Madrid': { standard: 'CET', daylight: 'CEST' },
+  'Europe/Rome': { standard: 'CET', daylight: 'CEST' },
+  'Europe/Amsterdam': { standard: 'CET', daylight: 'CEST' },
+  'America/New_York': { standard: 'EST', daylight: 'EDT' },
+  'America/Toronto': { standard: 'EST', daylight: 'EDT' },
+  'America/Chicago': { standard: 'CST', daylight: 'CDT' },
+  'America/Denver': { standard: 'MST', daylight: 'MDT' },
+  'America/Phoenix': { standard: 'MST' },
+  'America/Los_Angeles': { standard: 'PST', daylight: 'PDT' },
+  'America/Vancouver': { standard: 'PST', daylight: 'PDT' },
+  'America/Mexico_City': { standard: 'CST' },
+  'America/Sao_Paulo': { standard: 'BRT' }
+};
+
+/**
+ * タイムゾーンの指定が不正な場合は、日時の不正とは区別して例外にする
+ */
+const assertZone = (d: DateTime): void => {
+  if (!d.isValid && d.invalidReason === 'unsupported zone') {
+    throw new RangeError(d.invalidExplanation ?? d.invalidReason);
+  }
+};
+
+const toDateTime = (value: DateInput, options?: ParseDateOptions): DateTime | null => {
+  if (value == null || value === '') {
+    return null;
+  }
+  const zone = options?.inputTimezone ?? DEFAULT_TIMEZONE;
+  let d: DateTime | null = null;
+  if (value instanceof Date) {
+    d = DateTime.fromJSDate(value, { zone: zone });
+  } else if (typeof value === 'number') {
+    d = Number.isFinite(value) ? DateTime.fromMillis(value, { zone: zone }) : null;
+  } else {
+    const formats = options?.inputFormat ? [options.inputFormat].flat() : [];
+    for (const format of formats) {
+      const parsed = DateTime.fromFormat(value, format, { zone: zone });
+      assertZone(parsed);
+      if (parsed.isValid) {
+        d = parsed;
+        break;
+      }
+    }
+    if (d == null) {
+      d = DateTime.fromISO(value, { zone: zone });
+    }
+  }
+  if (d == null) {
+    return null;
+  }
+  assertZone(d);
+  if (!d.isValid) {
+    return null;
+  }
+  if (options?.duration) {
+    d = d.plus(options.duration);
+  }
+  if (options?.startOf) {
+    d = d.startOf(options.startOf);
+  }
+  if (options?.endOf) {
+    d = d.endOf(options.endOf);
+  }
+  return d;
+};
+
+const compare = (date1: DateInput, date2: DateInput, options: ParseDateOptions | undefined, predicate: (v1: number, v2: number) => boolean): boolean => {
+  const d1 = toDateTime(date1, options);
+  const d2 = toDateTime(date2, options);
+  if (!d1 || !d2) {
+    return false;
+  }
+  return predicate(d1.valueOf(), d2.valueOf());
+};
+
+/**
+ * 値を日時として解釈し、Date を返す
+ * duration / startOf / endOf は inputTimezone のゾーンで計算する
+ * 解釈できない値、null / undefined / 空文字は null を返す。タイムゾーンの指定が不正な場合は RangeError をスローする
+ *
+ * @param {DateInput} value
+ * @param {ParseDateOptions} [options]
+ * @returns {Date | null}
+ */
+export function parseDate(value: DateInput, options?: ParseDateOptions): Date | null {
+  return toDateTime(value, options)?.toJSDate() ?? null;
+}
+
+/**
+ * 値を日時として解釈し、outputTimezone での文字列にする
+ * null / undefined / 空文字は空文字を返す。解釈できない値は invalidText(既定 'Invalid Date')を返す
+ * タイムゾーンの指定が不正な場合は RangeError をスローする
+ *
+ * @param {DateInput} value
+ * @param {FormatDateOptions} [options]
+ * @returns {string}
+ */
+export function formatDate(value: DateInput, options?: FormatDateOptions): string {
+  if (value == null || value === '') {
+    return '';
+  }
+  const d = toDateTime(value, options);
+  if (!d) {
+    return options?.invalidText ?? 'Invalid Date';
+  }
+  const output = d.setZone(options?.outputTimezone ?? DEFAULT_TIMEZONE);
+  assertZone(output);
+  return options?.outputFormat ? output.toFormat(options.outputFormat) : output.toISO() as string;
+}
+
+/**
+ * 値が日時として解釈できるか判定する
+ *
+ * @param {DateInput} value
+ * @param {ParseDateOptions} [options]
+ * @returns {boolean}
+ */
+export function isValid(value: DateInput, options?: ParseDateOptions): boolean {
+  return toDateTime(value, options) != null;
+}
+
+/**
+ * date1 と date2 が同じ時刻か判定する。どちらかが解釈できない場合は false
+ *
+ * @param {DateInput} date1
+ * @param {DateInput} date2
+ * @param {ParseDateOptions} [options] 両方の値に適用する
+ * @returns {boolean}
+ */
+export function isSame(date1: DateInput, date2: DateInput, options?: ParseDateOptions): boolean {
+  return compare(date1, date2, options, (v1, v2) => v1 === v2);
+}
+
+/**
+ * date1 が date2 より前の時刻か判定する。どちらかが解釈できない場合は false
+ *
+ * @param {DateInput} date1
+ * @param {DateInput} date2
+ * @param {ParseDateOptions} [options] 両方の値に適用する
+ * @returns {boolean}
+ */
+export function isBefore(date1: DateInput, date2: DateInput, options?: ParseDateOptions): boolean {
+  return compare(date1, date2, options, (v1, v2) => v1 < v2);
+}
+
+/**
+ * date1 が date2 と同じか、より前の時刻か判定する。どちらかが解釈できない場合は false
+ *
+ * @param {DateInput} date1
+ * @param {DateInput} date2
+ * @param {ParseDateOptions} [options] 両方の値に適用する
+ * @returns {boolean}
+ */
+export function isSameOrBefore(date1: DateInput, date2: DateInput, options?: ParseDateOptions): boolean {
+  return compare(date1, date2, options, (v1, v2) => v1 <= v2);
+}
+
+/**
+ * date1 が date2 より後の時刻か判定する。どちらかが解釈できない場合は false
+ *
+ * @param {DateInput} date1
+ * @param {DateInput} date2
+ * @param {ParseDateOptions} [options] 両方の値に適用する
+ * @returns {boolean}
+ */
+export function isAfter(date1: DateInput, date2: DateInput, options?: ParseDateOptions): boolean {
+  return compare(date1, date2, options, (v1, v2) => v2 < v1);
+}
+
+/**
+ * date1 が date2 と同じか、より後の時刻か判定する。どちらかが解釈できない場合は false
+ *
+ * @param {DateInput} date1
+ * @param {DateInput} date2
+ * @param {ParseDateOptions} [options] 両方の値に適用する
+ * @returns {boolean}
+ */
+export function isSameOrAfter(date1: DateInput, date2: DateInput, options?: ParseDateOptions): boolean {
+  return compare(date1, date2, options, (v1, v2) => v2 <= v1);
+}
+
+/**
+ * 値が inputTimezone での今日より前の日付か判定する。解釈できない場合は false
+ *
+ * @param {DateInput} value
+ * @param {ParseDateOptions} [options]
+ * @returns {boolean}
+ */
+export function isPastDate(value: DateInput, options?: ParseDateOptions): boolean {
+  const target = toDateTime(value, options)?.startOf('day');
+  if (!target) {
+    return false;
+  }
+  const today = DateTime.now().setZone(options?.inputTimezone ?? DEFAULT_TIMEZONE).startOf('day');
+  return target.valueOf() < today.valueOf();
+}
+
+/**
+ * 値が現在時刻より前か判定する。解釈できない場合は false
+ *
+ * @param {DateInput} value
+ * @param {ParseDateOptions} [options]
+ * @returns {boolean}
+ */
+export function isPastDateTime(value: DateInput, options?: ParseDateOptions): boolean {
+  const target = toDateTime(value, options);
+  return target != null && target.valueOf() < Date.now();
+}
+
+/**
+ * date1 − date2 を unit の単位で返す
+ * 両方を inputTimezone で unit の始まりに切り捨ててから差を取るため、暦の上での差になる(23:00 と翌 01:00 の days は 1)
+ * どちらかが解釈できない場合は NaN を返す
+ *
+ * @param {DateInput} date1
+ * @param {DateInput} date2
+ * @param {TimeUnit} unit
+ * @param {ParseDateOptions} [options] 両方の値に適用する
+ * @returns {number}
+ */
+export function diff(date1: DateInput, date2: DateInput, unit: TimeUnit, options?: ParseDateOptions): number {
+  const d1 = toDateTime(date1, options);
+  const d2 = toDateTime(date2, options);
+  if (!d1 || !d2) {
+    return NaN;
+  }
+  // 'days' → 'day' のように切り捨ての単位にする
+  const dateUnit = unit.slice(0, -1) as DateTimeUnit;
+  return d1.startOf(dateUnit).diff(d2.startOf(dateUnit), unit).get(unit);
+}
+
+/**
+ * timezone での今日の始まりを返す
+ *
+ * @param {string} [timezone] IANA名。既定は 'UTC'
+ * @returns {Date}
+ */
+export function currentDate(timezone: string = DEFAULT_TIMEZONE): Date {
+  const d = DateTime.now().setZone(timezone).startOf('day');
+  assertZone(d);
+  return d.toJSDate();
+}
+
+/**
+ * 現在時刻を返す
+ * Date はタイムゾーンを保持しないため、ゾーンは文字列にする時点(formatDate の outputTimezone)で指定する
+ *
+ * @returns {Date}
+ */
+export function currentDateTime(): Date {
+  return new Date();
+}
+
+/**
+ * 現在時刻を timezone での 'yyyy-MM-ddTHH:mm:ss.SSS+HH:mm' 形式の文字列で返す
+ *
+ * @param {string} [timezone] IANA名。既定は 'UTC'
+ * @returns {string}
+ */
+export function currentTimestamp(timezone: string = DEFAULT_TIMEZONE): string {
+  const d = DateTime.now().setZone(timezone);
+  assertZone(d);
+  return d.toFormat(TIMESTAMP_FORMAT);
+}
+
+/**
+ * Excelの日付シリアル値を epoch ミリ秒に変換する
+ * Excelの日付シリアル値はゾーンの概念を持たないため、そのままではUTCの日時として変換される
+ * シリアル値がどのゾーンの日時かが分かっている場合は offset に時間差を指定する
+ *
+ * @example
+ *   convertExcelDateSerialToUnixTimeSerial(45200);                 // 1696118400000 (2023-10-01T00:00:00Z)
+ *   convertExcelDateSerialToUnixTimeSerial(45200, { offset: 9 }); // 1696086000000 (2023-10-01T00:00:00+09:00)
+ *
+ * @param {number} excelDateSerial
+ * @param {*} [options]
+ *   └ offset シリアル値のゾーンのUTCからの時間差(時)
+ * @returns {number}
+ */
+export function convertExcelDateSerialToUnixTimeSerial(excelDateSerial: number, options?: {
+  offset: number;
+}): number {
+  let timeserial = (excelDateSerial - EXCEL_EPOCH_SERIAL) * MILLISECONDS_PER_DAY;
+  if (options?.offset) {
+    timeserial -= options.offset * MILLISECONDS_PER_HOUR;
+  }
+  return timeserial;
+}
+
+/**
+ * 期間の値を別の単位に換算する
+ * 月と年は固定長(1か月 = 30日、1年 = 365日)として換算する
+ *
+ * @example
+ *   convertTimeUnit(1, 'hours', 'milliseconds');   // 3600000
+ *
+ * @param {number} value
+ * @param {TimeUnit} inputUnit
+ * @param {TimeUnit} outputUnit
+ * @returns {number}
+ */
+export function convertTimeUnit(value: number, inputUnit: TimeUnit, outputUnit: TimeUnit): number {
+  return LuxonDuration.fromObject({ [inputUnit]: value }).as(outputUnit);
+}
+
+/**
+ * タイムゾーンの略称を返す。夏時間の期間中は夏時間の略称を返す
+ * 既定の表にない場合は null を返す。表は options.abbreviations で追加・上書きできる
+ *
+ * @param {string} timezone IANA名
+ * @param {TimezoneAbbrOptions} [options]
+ * @returns {string | null}
+ */
+export function getTimezoneAbbr(timezone: string, options?: TimezoneAbbrOptions): string | null {
+  const definition = { ...DEFAULT_TIMEZONE_ABBREVIATIONS, ...options?.abbreviations }[timezone];
+  if (!definition) {
+    return null;
+  }
+  if (definition.daylight) {
+    const d = DateTime.fromJSDate(options?.at ?? new Date(), { zone: timezone });
+    assertZone(d);
+    if (d.isInDST) {
+      return definition.daylight;
+    }
+  }
+  return definition.standard;
+}
+
+/**
+ * 文字列中の 'GMT+9' のようなオフセット表記を、timezone の略称に置き換える
+ * 略称が解決できない場合は文字列をそのまま返す
+ *
+ * @param {string} text
+ * @param {string} timezone IANA名
+ * @param {TimezoneAbbrOptions} [options]
+ * @returns {string}
+ */
+export function applyTimezoneAbbr(text: string, timezone: string, options?: TimezoneAbbrOptions): string {
+  const abbr = getTimezoneAbbr(timezone, options);
+  return abbr == null ? text : text.replace(GMT_OFFSET, abbr);
+}