@digitalwalletcorp/utils 0.10.0 → 0.11.0

package/src/date-time.ts

@@ -0,0 +1,395 @@
+/**
+ * このクラス DateTime の役割は、日時演算の実体としての luxon を内部に閉じ込め、利用者側に露出させないことにある
+ */
+import { DateTime as LuxonDateTime } from 'luxon';
+import type { DateInput, DateUnit, Duration, ParseDateOptions, TimeUnit } from './date-util';
+
+/** set で変更する日時の要素。month は1〜12 */
+export interface DateTimeFields {
+  year?: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+}
+
+/**
+ * 日時を文字列にするときのオプション
+ */
+export interface DateTimeFormatOptions {
+  /** 月名・曜日名に使うロケール。既定は 'en-US' */
+  locale?: string;
+}
+
+const DEFAULT_TIMEZONE = 'UTC';
+
+const DEFAULT_LOCALE = 'en-US';
+
+/**
+ * タイムゾーンの指定が不正な場合は、日時の不正とは区別して例外にする
+ */
+const assertZone = (d: LuxonDateTime): void => {
+  if (!d.isValid && d.invalidReason === 'unsupported zone') {
+    throw new RangeError(d.invalidExplanation ?? d.invalidReason);
+  }
+};
+
+/**
+ * set に渡された要素が min〜max の整数であることを確かめる
+ */
+const assertField = (name: keyof DateTimeFields, value: number | undefined, min: number, max: number): void => {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isInteger(value) || value < min || max < value) {
+    throw new RangeError(`${name} must be an integer from ${min} to ${max}: ${value}`);
+  }
+};
+
+/**
+ * 日時を表す不変オブジェクト
+ * 演算メソッドは自身を変更せず、結果を新しいインスタンスで返す
+ * インスタンスごとにタイムゾーンを持ち、startOf / endOf / set や各要素の参照はそのタイムゾーンで計算する
+ */
+export class DateTime {
+  /**
+   * 日時演算インスタンス
+   */
+  private dateTime: LuxonDateTime;
+
+  private constructor(dateTime: LuxonDateTime) {
+    this.dateTime = dateTime;
+  }
+
+  /**
+   * 現在時刻を返す
+   * タイムゾーンの指定が不正な場合は RangeError をスローする
+   *
+   * @param {string} [timezone] IANA名。既定は 'UTC'
+   * @returns {DateTime}
+   */
+  public static now(timezone: string = DEFAULT_TIMEZONE): DateTime {
+    const d = LuxonDateTime.now().setZone(timezone);
+    assertZone(d);
+    return new DateTime(d);
+  }
+
+  /**
+   * 値を日時として解釈する
+   * 生成したインスタンスは inputTimezone のタイムゾーンを持つ
+   * DateTime を渡した場合、inputTimezone を省略すると渡した DateTime のタイムゾーンを引き継ぐ
+   * duration / startOf / endOf はそのタイムゾーンで計算する
+   * 解釈できない値、null / undefined / 空文字は null を返す。タイムゾーンの指定が不正な場合は RangeError をスローする
+   *
+   * @param {DateInput} value
+   * @param {ParseDateOptions} [options]
+   * @returns {DateTime | null}
+   */
+  public static parse(value: DateInput, options?: ParseDateOptions): DateTime | null {
+    if (value == null || value === '') {
+      return null;
+    }
+    const zone = options?.inputTimezone ?? DEFAULT_TIMEZONE;
+    let d: LuxonDateTime | null = null;
+    if (value instanceof DateTime) {
+      d = options?.inputTimezone ? value.dateTime.setZone(options.inputTimezone) : value.dateTime;
+    } else if (value instanceof Date) {
+      d = LuxonDateTime.fromJSDate(value, { zone: zone });
+    } else if (typeof value === 'number') {
+      d = Number.isFinite(value) ? LuxonDateTime.fromMillis(value, { zone: zone }) : null;
+    } else {
+      const locale = options?.locale ?? DEFAULT_LOCALE;
+      const formats = options?.inputFormat ? [options.inputFormat].flat() : [];
+      for (const format of formats) {
+        const parsed = LuxonDateTime.fromFormat(value, format, {
+          zone: zone,
+          locale: locale
+        });
+        assertZone(parsed);
+        if (parsed.isValid) {
+          d = parsed;
+          break;
+        }
+      }
+      if (d == null) {
+        d = LuxonDateTime.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 new DateTime(d);
+  }
+
+  /** 年 */
+  public get year(): number {
+    return this.dateTime.year;
+  }
+
+  /** 月(1〜12) */
+  public get month(): number {
+    return this.dateTime.month;
+  }
+
+  /** 日 */
+  public get day(): number {
+    return this.dateTime.day;
+  }
+
+  /** 時 */
+  public get hour(): number {
+    return this.dateTime.hour;
+  }
+
+  /** 分 */
+  public get minute(): number {
+    return this.dateTime.minute;
+  }
+
+  /** 秒 */
+  public get second(): number {
+    return this.dateTime.second;
+  }
+
+  /** ミリ秒 */
+  public get millisecond(): number {
+    return this.dateTime.millisecond;
+  }
+
+  /** 曜日。月曜が1、日曜が7 */
+  public get weekday(): number {
+    return this.dateTime.weekday;
+  }
+
+  /** その月の日数 */
+  public get daysInMonth(): number {
+    return this.dateTime.daysInMonth as number;
+  }
+
+  /** 夏時間の期間中か */
+  public get isInDST(): boolean {
+    return this.dateTime.isInDST;
+  }
+
+  /** タイムゾーン(IANA名) */
+  public get timezone(): string {
+    return this.dateTime.zoneName as string;
+  }
+
+  /**
+   * 期間を加算した結果を返す
+   * 負の値を指定すると減算になる
+   *
+   * @param {Duration} duration
+   * @returns {DateTime}
+   */
+  public plus(duration: Duration): DateTime {
+    return new DateTime(this.dateTime.plus(duration));
+  }
+
+  /**
+   * 期間を減算した結果を返す
+   *
+   * @param {Duration} duration
+   * @returns {DateTime}
+   */
+  public minus(duration: Duration): DateTime {
+    return new DateTime(this.dateTime.minus(duration));
+  }
+
+  /**
+   * 指定した単位の最初の時点に切り捨てた結果を返す(month なら月初の00:00:00.000)
+   * week は月曜始まりで切り捨てる
+   *
+   * @param {DateUnit} unit
+   * @returns {DateTime}
+   */
+  public startOf(unit: DateUnit): DateTime {
+    return new DateTime(this.dateTime.startOf(unit));
+  }
+
+  /**
+   * 指定した単位の最後の時点に切り上げた結果を返す(month なら月末の23:59:59.999)
+   * week は日曜終わりで切り上げる
+   *
+   * @param {DateUnit} unit
+   * @returns {DateTime}
+   */
+  public endOf(unit: DateUnit): DateTime {
+    return new DateTime(this.dateTime.endOf(unit));
+  }
+
+  /**
+   * 指定した要素を変更した結果を返す
+   * 範囲外の値や整数でない値を指定した場合は RangeError をスローする
+   * day を指定せずに year / month を変更し、日がその月に無い場合は月末日にする(1月31日に { month: 2 } なら2月末日)
+   *
+   * @param {DateTimeFields} fields
+   * @returns {DateTime}
+   */
+  public set(fields: DateTimeFields): DateTime {
+    assertField('month', fields.month, 1, 12);
+    assertField('hour', fields.hour, 0, 23);
+    assertField('minute', fields.minute, 0, 59);
+    assertField('second', fields.second, 0, 59);
+    assertField('millisecond', fields.millisecond, 0, 999);
+    // day の上限は変更後の年月で決まる
+    const daysInMonth = this.dateTime.set({
+      year: fields.year ?? this.year,
+      month: fields.month ?? this.month,
+      day: 1
+    }).daysInMonth as number;
+    assertField('day', fields.day, 1, daysInMonth);
+    return new DateTime(this.dateTime.set(fields));
+  }
+
+  /**
+   * 同じ時刻を別のタイムゾーンで表した結果を返す
+   * タイムゾーンの指定が不正な場合は RangeError をスローする
+   *
+   * @param {string} timezone IANA名
+   * @returns {DateTime}
+   */
+  public setZone(timezone: string): DateTime {
+    const d = this.dateTime.setZone(timezone);
+    assertZone(d);
+    return new DateTime(d);
+  }
+
+  /**
+   * 自身 − other を unit の単位で返す
+   * 両方を自身のタイムゾーンで unit の始まりに切り捨ててから差を取るため、暦の上での差になる(23:00 と翌 01:00 の days は 1)
+   *
+   * @param {DateTime} other
+   * @param {TimeUnit} unit
+   * @returns {number}
+   */
+  public diff(other: DateTime, unit: TimeUnit): number {
+    // 'days' → 'day' のように切り捨ての単位にする
+    const dateUnit = unit.slice(0, -1) as DateUnit;
+    const target = other.dateTime.setZone(this.dateTime.zone);
+    return this.dateTime.startOf(dateUnit).diff(target.startOf(dateUnit), unit).get(unit);
+  }
+
+  /**
+   * 時刻を比較する。タイムゾーンが異なっていても同じ時刻なら等しい
+   *
+   * @param {DateTime} other
+   * @returns {-1 | 0 | 1} 自身が前なら-1、等しければ0、後なら1
+   */
+  public compareTo(other: DateTime): -1 | 0 | 1 {
+    return Math.sign(this.toMillis() - other.toMillis()) as -1 | 0 | 1;
+  }
+
+  /**
+   * 同じ時刻か判定する
+   *
+   * @param {DateTime} other
+   * @returns {boolean}
+   */
+  public eq(other: DateTime): boolean {
+    return this.compareTo(other) === 0;
+  }
+
+  /**
+   * 自身が前の時刻か判定する
+   *
+   * @param {DateTime} other
+   * @returns {boolean}
+   */
+  public lt(other: DateTime): boolean {
+    return this.compareTo(other) < 0;
+  }
+
+  /**
+   * 自身が前か同じ時刻か判定する
+   *
+   * @param {DateTime} other
+   * @returns {boolean}
+   */
+  public lte(other: DateTime): boolean {
+    return this.compareTo(other) <= 0;
+  }
+
+  /**
+   * 自身が後の時刻か判定する
+   *
+   * @param {DateTime} other
+   * @returns {boolean}
+   */
+  public gt(other: DateTime): boolean {
+    return 0 < this.compareTo(other);
+  }
+
+  /**
+   * 自身が後か同じ時刻か判定する
+   *
+   * @param {DateTime} other
+   * @returns {boolean}
+   */
+  public gte(other: DateTime): boolean {
+    return 0 <= this.compareTo(other);
+  }
+
+  /**
+   * 自身のタイムゾーンで、指定した書式の文字列にする
+   *
+   * @param {string} outputFormat
+   * @param {DateTimeFormatOptions} [options]
+   * @returns {string}
+   */
+  public format(outputFormat: string, options?: DateTimeFormatOptions): string {
+    return this.dateTime.toFormat(outputFormat, { locale: options?.locale ?? DEFAULT_LOCALE });
+  }
+
+  /**
+   * 自身のタイムゾーンで、ISO形式の文字列にする
+   *
+   * @returns {string}
+   */
+  public toISO(): string {
+    return this.dateTime.toISO() as string;
+  }
+
+  /**
+   * Date に変換する
+   *
+   * @returns {Date}
+   */
+  public toDate(): Date {
+    return this.dateTime.toJSDate();
+  }
+
+  /**
+   * epoch ミリ秒に変換する
+   *
+   * @returns {number}
+   */
+  public toMillis(): number {
+    return this.dateTime.toMillis();
+  }
+
+  /**
+   * 自身のタイムゾーンで、ISO形式の文字列にする
+   *
+   * @returns {string}
+   */
+  public toString(): string {
+    return this.toISO();
+  }
+}

package/src/date-util.ts

@@ -1,8 +1,10 @@
-import { DateTime, Duration as LuxonDuration } from 'luxon';
-import type { DateTimeUnit } from 'luxon';
+import { DateTime } from './date-time';
 
-/** 日時として解釈する値。string はISO形式または inputFormat の書式、number は epoch ミリ秒 */
-export type DateInput = string | Date | number | null | undefined;
+/**
+ * 日時として解釈する値。string はISO形式または inputFormat の書式、number は epoch ミリ秒
+ * DateTime は inputTimezone を省略した場合、その DateTime のタイムゾーンで扱う
+ */
+export type DateInput = string | Date | number | DateTime | null | undefined;
 
 /** 日時の切り捨て(startOf / endOf)に使う単位 */
 export type DateUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
@@ -37,6 +39,8 @@ export interface ParseDateOptions {
   startOf?: DateUnit;
   /** 指定した単位の最後の時点に切り上げる(month なら月末の23:59:59.999) */
   endOf?: DateUnit;
+  /** 書式の月名・曜日名を解釈・出力するときのロケール。既定は 'en-US' */
+  locale?: string;
 }
 
 /**
@@ -119,65 +123,13 @@ const DEFAULT_TIMEZONE_ABBREVIATIONS: TimezoneAbbreviations = {
   '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);
+  const d1 = DateTime.parse(date1, options);
+  const d2 = DateTime.parse(date2, options);
   if (!d1 || !d2) {
     return false;
   }
-  return predicate(d1.valueOf(), d2.valueOf());
+  return predicate(d1.toMillis(), d2.toMillis());
 };
 
 /**
@@ -190,7 +142,7 @@ const compare = (date1: DateInput, date2: DateInput, options: ParseDateOptions |
  * @returns {Date | null}
  */
 export function parseDate(value: DateInput, options?: ParseDateOptions): Date | null {
-  return toDateTime(value, options)?.toJSDate() ?? null;
+  return DateTime.parse(value, options)?.toDate() ?? null;
 }
 
 /**
@@ -206,19 +158,18 @@ export function parseDate(value: DateInput, options?: ParseDateOptions): Date |
 export function formatDate(options: FormatDateOptions): string;
 export function formatDate(value: DateInput, options?: FormatDateOptions): string;
 export function formatDate(value: DateInput | FormatDateOptions, options?: FormatDateOptions): string {
-  if (typeof value === 'object' && value !== null && !(value instanceof Date)) {
+  if (typeof value === 'object' && value !== null && !(value instanceof Date) && !(value instanceof DateTime)) {
     return formatDate(new Date(), value);
   }
   if (value == null || value === '') {
     return '';
   }
-  const d = toDateTime(value, options);
+  const d = DateTime.parse(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;
+  return options?.outputFormat ? output.format(options.outputFormat, { locale: options.locale }) : output.toISO();
 }
 
 /**
@@ -229,7 +180,7 @@ export function formatDate(value: DateInput | FormatDateOptions, options?: Forma
  * @returns {boolean}
  */
 export function isValid(value: DateInput, options?: ParseDateOptions): boolean {
-  return toDateTime(value, options) != null;
+  return DateTime.parse(value, options) != null;
 }
 
 /**
@@ -300,12 +251,12 @@ export function isSameOrAfter(date1: DateInput, date2: DateInput, options?: Pars
  * @returns {boolean}
  */
 export function isPastDate(value: DateInput, options?: ParseDateOptions): boolean {
-  const target = toDateTime(value, options)?.startOf('day');
+  const target = DateTime.parse(value, options)?.startOf('day');
   if (!target) {
     return false;
   }
-  const today = DateTime.now().setZone(options?.inputTimezone ?? DEFAULT_TIMEZONE).startOf('day');
-  return target.valueOf() < today.valueOf();
+  const today = DateTime.now(target.timezone).startOf('day');
+  return target.lt(today);
 }
 
 /**
@@ -316,8 +267,8 @@ export function isPastDate(value: DateInput, options?: ParseDateOptions): boolea
  * @returns {boolean}
  */
 export function isPastDateTime(value: DateInput, options?: ParseDateOptions): boolean {
-  const target = toDateTime(value, options);
-  return target != null && target.valueOf() < Date.now();
+  const target = DateTime.parse(value, options);
+  return target != null && target.toMillis() < Date.now();
 }
 
 /**
@@ -332,14 +283,12 @@ export function isPastDateTime(value: DateInput, options?: ParseDateOptions): bo
  * @returns {number}
  */
 export function diff(date1: DateInput, date2: DateInput, unit: TimeUnit, options?: ParseDateOptions): number {
-  const d1 = toDateTime(date1, options);
-  const d2 = toDateTime(date2, options);
+  const d1 = DateTime.parse(date1, options);
+  const d2 = DateTime.parse(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);
+  return d1.diff(d2, unit);
 }
 
 /**
@@ -349,9 +298,7 @@ export function diff(date1: DateInput, date2: DateInput, unit: TimeUnit, options
  * @returns {string}
  */
 export function currentTimestamp(timezone: string = DEFAULT_TIMEZONE): string {
-  const d = DateTime.now().setZone(timezone);
-  assertZone(d);
-  return d.toFormat(TIMESTAMP_FORMAT);
+  return DateTime.now(timezone).format(TIMESTAMP_FORMAT);
 }
 
 /**
@@ -378,22 +325,6 @@ export function convertExcelDateSerialToUnixTimeSerial(excelDateSerial: number,
   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);
-}
-
 /**
  * timezone が at の時点で夏時間かどうかを返す
  * at を省略した場合は現在時刻で判定する。at が解釈できない場合は false を返す
@@ -404,12 +335,8 @@ export function convertTimeUnit(value: number, inputUnit: TimeUnit, outputUnit:
  * @returns {boolean}
  */
 export function isInDST(timezone: string, at?: DateInput): boolean {
-  const d = at === undefined ? DateTime.now().setZone(timezone) : toDateTime(at)?.setZone(timezone);
-  if (d == null) {
-    return false;
-  }
-  assertZone(d);
-  return d.isInDST;
+  const d = at === undefined ? DateTime.now(timezone) : DateTime.parse(at)?.setZone(timezone);
+  return d?.isInDST ?? false;
 }
 
 /**
@@ -426,9 +353,8 @@ export function getTimezoneAbbr(timezone: string, options?: TimezoneAbbrOptions)
     return null;
   }
   if (definition.daylight) {
-    const d = DateTime.fromJSDate(options?.at ?? new Date(), { zone: timezone });
-    assertZone(d);
-    if (d.isInDST) {
+    const d = DateTime.parse(options?.at ?? new Date())?.setZone(timezone);
+    if (d?.isInDST) {
       return definition.daylight;
     }
   }