@checkdigit/time 3.0.0-PR.17-5aaf → 4.0.0-PR.18-81a3

package/src/date-fns/intervalToDuration/index.ts

@@ -1,11 +1,11 @@
-import add from '../add/index';
-import differenceInDays from '../differenceInDays/index';
-import differenceInHours from '../differenceInHours/index';
-import differenceInMinutes from '../differenceInMinutes/index';
-import differenceInMonths from '../differenceInMonths/index';
-import differenceInSeconds from '../differenceInSeconds/index';
-import differenceInYears from '../differenceInYears/index';
-import toDate from '../toDate/index';
+import { add } from '../add/index';
+import { differenceInDays } from '../differenceInDays/index';
+import { differenceInHours } from '../differenceInHours/index';
+import { differenceInMinutes } from '../differenceInMinutes/index';
+import { differenceInMonths } from '../differenceInMonths/index';
+import { differenceInSeconds } from '../differenceInSeconds/index';
+import { differenceInYears } from '../differenceInYears/index';
+import { toDate } from '../toDate/index';
 import type { Duration, Interval } from '../types';
 
 /**
@@ -16,12 +16,11 @@ import type { Duration, Interval } from '../types';
  * @description
  * Convert a interval object to a duration object.
  *
- * @param interval - the interval to convert to duration
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
  *
- * @returns The duration Object
- * @throws {RangeError} `start` must not be Invalid Date
- * @throws {RangeError} `end` must not be Invalid Date
- * @throws {RangeError} The start of an interval cannot be after its end
+ * @param interval - The interval to convert to duration
+ *
+ * @returns The duration object
  *
  * @example
  * // Get the duration between January 15, 1929 and April 4, 1968.
@@ -31,34 +30,40 @@ import type { Duration, Interval } from '../types';
  * })
  * // => { years: 39, months: 2, days: 20, hours: 7, minutes: 5, seconds: 0 }
  */
-export default function interval<DateType extends Date>(interval: Interval<DateType>): Duration {
+export function intervalToDuration<DateType extends Date>(interval: Interval<DateType>): Duration {
   const start = toDate(interval.start);
   const end = toDate(interval.end);
 
-  if (isNaN(start.getTime())) throw new RangeError('Start Date is invalid');
-  if (isNaN(end.getTime())) throw new RangeError('End Date is invalid');
-  if (start > end) {
-    throw new RangeError('The start of an interval cannot be after its end');
-  }
+  const duration: Duration = {};
+
+  const years = differenceInYears(end, start);
+  if (years) duration.years = years;
+
+  // @ts-ignore
+  const remainingMonths = add(start, { years: duration.years });
+
+  const months = differenceInMonths(end, remainingMonths);
+  if (months) duration.months = months;
+
+  const remainingDays = add(remainingMonths, { months: duration.months! });
+
+  const days = differenceInDays(end, remainingDays);
+  if (days) duration.days = days;
 
-  const duration: Duration = {
-    years: differenceInYears(end, start),
-  };
+  const remainingHours = add(remainingDays, { days: duration.days! });
 
-  const remainingMonths = add(start, { years: duration.years as number });
-  duration.months = differenceInMonths(end, remainingMonths);
+  const hours = differenceInHours(end, remainingHours);
+  if (hours) duration.hours = hours;
 
-  const remainingDays = add(remainingMonths, { months: duration.months });
-  duration.days = differenceInDays(end, remainingDays);
+  const remainingMinutes = add(remainingHours, { hours: duration.hours! });
 
-  const remainingHours = add(remainingDays, { days: duration.days });
-  duration.hours = differenceInHours(end, remainingHours);
+  const minutes = differenceInMinutes(end, remainingMinutes);
+  if (minutes) duration.minutes = minutes;
 
-  const remainingMinutes = add(remainingHours, { hours: duration.hours });
-  duration.minutes = differenceInMinutes(end, remainingMinutes);
+  const remainingSeconds = add(remainingMinutes, { minutes: duration.minutes! });
 
-  const remainingSeconds = add(remainingMinutes, { minutes: duration.minutes });
-  duration.seconds = differenceInSeconds(end, remainingSeconds);
+  const seconds = differenceInSeconds(end, remainingSeconds);
+  if (seconds) duration.seconds = seconds;
 
   return duration;
 }

package/src/date-fns/intervalToDuration/test.mts

@@ -0,0 +1,235 @@
+import { describe, expect, it } from 'vitest';
+import { intervalToDuration } from './index';
+import { addMonths } from '../addMonths/index';
+
+describe('intervalToDuration', () => {
+  it('returns correct duration for arbitrary dates', () => {
+    const start = new Date(1929, 0, 15, 12, 0, 0);
+    const end = new Date(1968, 3, 4, 19, 5, 0);
+    const result = intervalToDuration({ start, end });
+
+    expect(result).toEqual({
+      years: 39,
+      months: 2,
+      days: 20,
+      hours: 7,
+      minutes: 5,
+    });
+  });
+
+  it('returns correct duration (1 of everything)', () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2021, 3, 2, 13, 1, 1);
+    const result = intervalToDuration({ start, end });
+
+    expect(result).toEqual({
+      years: 1,
+      months: 1,
+      days: 1,
+      hours: 1,
+      minutes: 1,
+      seconds: 1,
+    });
+  });
+
+  it('returns duration of 0 when the dates are the same', () => {
+    const start = new Date(2020, 2, 1, 12, 0, 0);
+    const end = new Date(2020, 2, 1, 12, 0, 0);
+    const result = intervalToDuration({ start, end });
+
+    expect(result).toEqual({});
+  });
+
+  it("returns a negative duration if interval's start date is greater than its end date", () => {
+    const interval = {
+      start: new Date(2020, 3, 1),
+      end: new Date(2020, 2, 1),
+    };
+    const result = intervalToDuration(interval);
+
+    expect(result).toEqual({ months: -1 });
+  });
+
+  it("returns an empty object if interval's start date invalid", () => {
+    const interval = {
+      start: new Date(NaN),
+      end: new Date(2020, 0, 1),
+    };
+    const result = intervalToDuration(interval);
+
+    expect(result).toEqual({});
+  });
+
+  it("returns an empty object  if interval's end date invalid", () => {
+    const interval = {
+      start: new Date(2020, 0, 1),
+      end: new Date(NaN),
+    };
+    const result = intervalToDuration(interval);
+
+    expect(result).toEqual({});
+  });
+
+  describe('edge cases', () => {
+    it('returns correct duration for dates in the end of Feb - issue 2255', () => {
+      expect(
+        intervalToDuration({
+          start: new Date(2012, 1 /* Feb */, 28, 9, 0, 0),
+          end: new Date(2012, 1 /* Feb */, 29, 10, 0, 0),
+        }),
+      ).toEqual({
+        days: 1,
+        hours: 1,
+      });
+
+      expect(
+        intervalToDuration({
+          start: new Date(2012, 1 /* Feb */, 29, 9, 0, 0),
+          end: new Date(2012, 1 /* Feb */, 29, 10, 0, 0),
+        }),
+      ).toEqual({
+        hours: 1,
+      });
+
+      expect(
+        intervalToDuration({
+          start: new Date(2012, 1 /* Feb */, 28, 9, 0, 0),
+          end: new Date(2012, 1 /* Feb */, 28, 10, 0, 0),
+        }),
+      ).toEqual({
+        hours: 1,
+      });
+
+      // Issue 2261
+      expect(
+        intervalToDuration({
+          start: new Date(2021, 1 /* Feb */, 28, 7, 23, 7),
+          end: new Date(2021, 1 /* Feb */, 28, 7, 38, 18),
+        }),
+      ).toEqual({
+        minutes: 15,
+        seconds: 11,
+      });
+    });
+
+    it('returns correct duration for end of month start dates - issue 2611', () => {
+      const start = new Date(2021, 7, 31);
+      const end = addMonths(start, 1);
+
+      expect(end).toEqual(new Date(2021, 8, 30));
+
+      const duration = intervalToDuration({ start, end });
+      const expectedDuration = {
+        months: 1,
+      };
+
+      expect(duration).toEqual(expectedDuration);
+    });
+
+    it('returns correct duration for Feb 29 on leap year + 1 month - issue 1778', () => {
+      const duration = intervalToDuration({
+        start: new Date(2020, 1, 29),
+        end: new Date(2020, 2, 29),
+      });
+      const expectedDuration = {
+        months: 1,
+      };
+
+      expect(duration).toEqual(expectedDuration);
+    });
+
+    it('returns correct duration for Feb 28 to Apr 30 interval - issue 2910', () => {
+      const duration = intervalToDuration({
+        start: new Date(2022, 1, 28),
+        end: new Date(2022, 3, 30),
+      });
+      const expectedDuration = {
+        months: 2,
+        days: 2,
+      };
+
+      expect(duration).toEqual(expectedDuration);
+    });
+
+    describe('issue 2470', () => {
+      it('returns correct duration for Feb 28 to Aug 31 interval', () => {
+        const duration = intervalToDuration({
+          start: new Date(2021, 1, 28),
+          end: new Date(2021, 7, 31),
+        });
+        const expectedDuration = {
+          months: 6,
+          days: 3,
+        };
+
+        expect(duration).toEqual(expectedDuration);
+      });
+
+      it('returns correct duration for Feb 28 to Aug 30 interval', () => {
+        const duration = intervalToDuration({
+          start: new Date(2021, 1, 28),
+          end: new Date(2021, 7, 30),
+        });
+        const expectedDuration = {
+          months: 6,
+          days: 2,
+        };
+
+        expect(duration).toEqual(expectedDuration);
+      });
+
+      it('returns correct duration for Feb 28 to Aug 29 interval', () => {
+        const duration = intervalToDuration({
+          start: new Date(2021, 1, 28),
+          end: new Date(2021, 7, 29),
+        });
+        const expectedDuration = {
+          months: 6,
+          days: 1,
+        };
+
+        expect(duration).toEqual(expectedDuration);
+      });
+
+      it('returns correct duration for Feb 28 to Aug 28 interval', () => {
+        const duration = intervalToDuration({
+          start: new Date(2021, 1, 28),
+          end: new Date(2021, 7, 28),
+        });
+        const expectedDuration = {
+          months: 6,
+        };
+
+        expect(duration).toEqual(expectedDuration);
+      });
+
+      it('returns correct duration for Feb 28 to Aug 27 interval', () => {
+        // Feb 28 to July 28 is 5 months, July 28 to Aug 27 is 30 days
+
+        const duration = intervalToDuration({
+          start: new Date(2021, 1, 28),
+          end: new Date(2021, 7, 27),
+        });
+        const expectedDuration = {
+          months: 5,
+          days: 30,
+        };
+
+        expect(duration).toEqual(expectedDuration);
+      });
+
+      it('returns correct duration for Apr 30 to May 31 interval', () => {
+        const duration = intervalToDuration({
+          start: new Date(2021, 3, 30),
+          end: new Date(2021, 4, 31),
+        });
+        const expectedDuration = {
+          months: 1,
+          days: 1,
+        };
+
+        expect(duration).toEqual(expectedDuration);
+      });
+    });
+  });
+});

package/src/date-fns/intlFormat/index.ts

@@ -1,23 +1,27 @@
-type Locale = Intl.ResolvedDateTimeFormatOptions['locale'];
-type FormatOptions = Intl.DateTimeFormatOptions;
-type LocaleOptions = { locale: Locale | Locale[] };
+import { toDate } from '../toDate/index';
 
-export default function intlFormat<DateType extends Date>(date: DateType): string;
-
-export default function intlFormat<DateType extends Date>(date: DateType, localeOptions: LocaleOptions): string;
+/**
+ * The locale string (see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).
+ */
+export type IntlFormatLocale = Intl.ResolvedDateTimeFormatOptions['locale'];
 
-export default function intlFormat<DateType extends Date>(date: DateType, formatOptions: FormatOptions): string;
+/**
+ * The format options (see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options)
+ */
+export type IntlFormatFormatOptions = Intl.DateTimeFormatOptions;
 
-export default function intlFormat<DateType extends Date>(
-  date: DateType,
-  formatOptions: FormatOptions,
-  localeOptions: LocaleOptions,
-): string;
+/**
+ * The locale options.
+ */
+export interface IntlFormatLocaleOptions {
+  /** The locale(s) to use (see: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument) */
+  locale: IntlFormatLocale | IntlFormatLocale[];
+}
 
 /**
  * @name intlFormat
  * @category Common Helpers
- * @summary  Format the date with Intl.DateTimeFormat (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
+ * @summary Format the date with Intl.DateTimeFormat (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
  *
  * @description
  * Return the formatted date string in the given format.
@@ -26,69 +30,106 @@ export default function intlFormat<DateType extends Date>(
  *
  * > ⚠️ Please note that before Node version 13.0.0, only the locale data for en-US is available by default.
  *
- * @param argument - the original date.
- * @param formatOptions - an object with options.
- * @param formatOptions.localeMatcher - locale selection algorithm.
- * @param formatOptions.weekday - representation the days of the week.
- * @param formatOptions.era - representation of eras.
- * @param formatOptions.year - representation of years.
- * @param formatOptions.month - representation of month.
- * @param formatOptions.day - representation of day.
- * @param formatOptions.hour - representation of hours.
- * @param formatOptions.minute - representation of minutes.
- * @param formatOptions.second - representation of seconds.
- * @param formatOptions.timeZoneName - representation of names of time zones.
- * @param formatOptions.formatMatcher - format selection algorithm.
- * @param formatOptions.hour12 - determines whether to use 12-hour time format.
- * @param formatOptions.timeZone - the time zone to use.
- * @param localeOptions - an object with locale.
- * @param localeOptions.locale - the locale code
- * @returns the formatted date string.
- * @throws {RangeError} `date` must not be Invalid Date
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The date to format
+ *
+ * @returns The formatted date string
+ *
+ * @throws `date` must not be Invalid Date
  *
  * @example
- * // Represent 10 October 2019 in German.
- * // Convert the date with format's options and locale's options.
+ * // Represent 4 October 2019 in middle-endian format:
+ * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456))
+ * //=> 10/4/2019
+ */
+export function intlFormat<DateType extends Date>(date: DateType | number | string): string;
+
+/**
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The date to format
+ * @param localeOptions - An object with locale
+ *
+ * @returns The formatted date string
+ *
+ * @throws `date` must not be Invalid Date
+ *
+ * @example
+ * // Represent 4 October 2019 in Korean.
+ * // Convert the date with locale's options.
  * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456), {
- *      weekday: 'long',
- *      year: 'numeric',
- *      month: 'long',
- *      day: 'numeric',
- *    }, {
- *      locale: 'de-DE',
- *  })
- * //=> Freitag, 4. Oktober 2019
+ *   locale: 'ko-KR',
+ * })
+ * //=> 2019. 10. 4.
+ */
+export function intlFormat<DateType extends Date>(
+  date: DateType | number | string,
+  localeOptions: IntlFormatLocaleOptions,
+): string;
+
+/**
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The date to format
+ * @param formatOptions - The format options
+ *
+ * @returns The formatted date string
+ *
+ * @throws `date` must not be Invalid Date
  *
  * @example
- * // Represent 10 October 2019.
+ * // Represent 4 October 2019.
  * // Convert the date with format's options.
  * const result = intlFormat.default(new Date(2019, 9, 4, 12, 30, 13, 456), {
- *      year: 'numeric',
- *      month: 'numeric',
- *      day: 'numeric',
- *      hour: 'numeric',
- *  })
+ *   year: 'numeric',
+ *   month: 'numeric',
+ *   day: 'numeric',
+ *   hour: 'numeric',
+ * })
  * //=> 10/4/2019, 12 PM
+ */
+export function intlFormat<DateType extends Date>(
+  date: DateType | number | string,
+  formatOptions: IntlFormatFormatOptions,
+): string;
+
+/**
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
  *
- * @example
- * // Represent 10 October 2019 in Korean.
- * // Convert the date with locale's options.
- * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456), {
- *      locale: 'ko-KR',
- *  })
- * //=> 2019. 10. 4.
+ * @param date - The date to format
+ * @param formatOptions - The format options
+ * @param localeOptions - An object with locale
+ *
+ * @returns The formatted date string
+ *
+ * @throws `date` must not be Invalid Date
  *
  * @example
- * // Represent 10 October 2019 in middle-endian format:
- * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456))
- * //=> 10/4/2019
+ * // Represent 4 October 2019 in German.
+ * // Convert the date with format's options and locale's options.
+ * const result = intlFormat(new Date(2019, 9, 4, 12, 30, 13, 456), {
+ *   weekday: 'long',
+ *   year: 'numeric',
+ *   month: 'long',
+ *   day: 'numeric',
+ * }, {
+ *   locale: 'de-DE',
+ * })
+ * //=> Freitag, 4. Oktober 2019
  */
-export default function intlFormat<DateType extends Date>(
-  date: DateType,
-  formatOrLocale?: FormatOptions | LocaleOptions,
-  localeOptions?: LocaleOptions,
+export function intlFormat<DateType extends Date>(
+  date: DateType | number | string,
+  formatOptions: IntlFormatFormatOptions,
+  localeOptions: IntlFormatLocaleOptions,
+): string;
+
+export function intlFormat<DateType extends Date>(
+  date: DateType | number | string,
+  formatOrLocale?: IntlFormatFormatOptions | IntlFormatLocaleOptions,
+  localeOptions?: IntlFormatLocaleOptions,
 ): string {
-  let formatOptions: FormatOptions | undefined;
+  let formatOptions: IntlFormatFormatOptions | undefined;
 
   if (isFormatOptions(formatOrLocale)) {
     formatOptions = formatOrLocale;
@@ -96,9 +137,11 @@ export default function intlFormat<DateType extends Date>(
     localeOptions = formatOrLocale;
   }
 
-  return new Intl.DateTimeFormat(localeOptions?.locale, formatOptions).format(date);
+  return new Intl.DateTimeFormat(localeOptions?.locale, formatOptions).format(toDate(date));
 }
 
-function isFormatOptions(opts: LocaleOptions | FormatOptions | undefined): opts is FormatOptions {
+function isFormatOptions(
+  opts: IntlFormatLocaleOptions | IntlFormatFormatOptions | undefined,
+): opts is IntlFormatFormatOptions {
   return opts !== undefined && !('locale' in opts);
 }

package/src/date-fns/intlFormat/test.mts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { intlFormat } from './index';
+
+// Before Node version 13.0.0, only the locale data for en-US is available by default.
+const hasFullICU = () => {
+  try {
+    const january = new Date(9e8);
+    const spanish = new Intl.DateTimeFormat('es', { month: 'long' });
+    return spanish.format(january) === 'enero';
+  } catch (err) {
+    return false;
+  }
+};
+
+const fullICUOnly = hasFullICU() ? it : it.skip;
+
+const getOperationSystemLocale = () => {
+  // https://stackoverflow.com/questions/46072248/node-js-how-to-detect-user-language/46072415
+  return Intl.DateTimeFormat().resolvedOptions().locale;
+};
+
+describe('intlFormat', () => {
+  describe('formats date', () => {
+    fullICUOnly("should work without format's options and locale's options", () => {
+      const date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456);
+      const result = intlFormat(date);
+      const localeResult = intlFormat(date, {
+        locale: getOperationSystemLocale(),
+      });
+
+      expect(result).toBe(localeResult);
+    });
+
+    fullICUOnly("should work with only format's options", () => {
+      const date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456);
+      const formatOptions: Intl.DateTimeFormatOptions = {
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+        second: 'numeric',
+        hour12: false,
+        timeZone: 'America/Los_Angeles',
+      };
+
+      const result = intlFormat(date, formatOptions);
+      const localeResult = intlFormat(date, formatOptions, {
+        locale: getOperationSystemLocale(),
+      });
+
+      expect(result).toBe(localeResult);
+    });
+
+    fullICUOnly("should work with only locale's options", () => {
+      const date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456);
+      // Korean uses year-month-day order
+      const localeOptions = {
+        locale: 'ko-KR',
+      };
+
+      const result = intlFormat(date, localeOptions);
+
+      expect(result).toBe('2019. 10. 4.');
+    });
+
+    fullICUOnly("should work with format's options and locale's options", () => {
+      const date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456);
+      const formatOptions: Intl.DateTimeFormatOptions = {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+      };
+      const localeOptions = {
+        locale: 'de-DE',
+      };
+
+      const result = intlFormat(date, formatOptions, localeOptions);
+
+      expect(result).toBe('Freitag, 4. Oktober 2019');
+    });
+  });
+
+  it('throws RangeError if the date value is invalid', () => {
+    expect(() => intlFormat(new Date(NaN))).toThrow(RangeError);
+  });
+});