@checkdigit/time 1.0.0-PR.11-7d2f

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

@@ -0,0 +1,84 @@
+import toDate from '../toDate/index';
+import type { Interval } from '../types';
+
+/**
+ * The {@link areIntervalsOverlapping} function options.
+ */
+export interface AreIntervalsOverlappingOptions {
+  inclusive?: boolean;
+}
+
+/**
+ * @name areIntervalsOverlapping
+ * @category Interval Helpers
+ * @summary Is the given time interval overlapping with another time interval?
+ *
+ * @description
+ * Is the given time interval overlapping with another time interval? Adjacent intervals do not count as overlapping.
+ *
+ * @param intervalLeft - the first interval to compare. See [Interval]{@link https://date-fns.org/docs/Interval}
+ * @param intervalRight - the second interval to compare. See [Interval]{@link https://date-fns.org/docs/Interval}
+ * @param options - the object with options
+ * @returns whether the time intervals are overlapping
+ * @throws {RangeError} The start of an interval cannot be after its end
+ * @throws {RangeError} Date in interval cannot be `Invalid Date`
+ *
+ * @example
+ * // For overlapping time intervals:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 17), end: new Date(2014, 0, 21) }
+ * )
+ * //=> true
+ *
+ * @example
+ * // For non-overlapping time intervals:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 21), end: new Date(2014, 0, 22) }
+ * )
+ * //=> false
+ *
+ * @example
+ * // For adjacent time intervals:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 30) }
+ * )
+ * //=> false
+ *
+ * @example
+ * // Using the inclusive option:
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 24) }
+ * )
+ * //=> false
+ * areIntervalsOverlapping(
+ *   { start: new Date(2014, 0, 10), end: new Date(2014, 0, 20) },
+ *   { start: new Date(2014, 0, 20), end: new Date(2014, 0, 24) },
+ *   { inclusive: true }
+ * )
+ * //=> true
+ */
+export default function areIntervalsOverlapping(
+  intervalLeft: Interval,
+  intervalRight: Interval,
+  options?: AreIntervalsOverlappingOptions
+): boolean {
+  const leftStartTime = toDate(intervalLeft.start).getTime();
+  const leftEndTime = toDate(intervalLeft.end).getTime();
+  const rightStartTime = toDate(intervalRight.start).getTime();
+  const rightEndTime = toDate(intervalRight.end).getTime();
+
+  // Throw an exception if start date is after end date or if any date is `Invalid Date`
+  if (!(leftStartTime <= leftEndTime && rightStartTime <= rightEndTime)) {
+    throw new RangeError('Invalid interval');
+  }
+
+  if (options?.inclusive) {
+    return leftStartTime <= rightEndTime && rightStartTime <= leftEndTime;
+  }
+
+  return leftStartTime < rightEndTime && rightStartTime < leftEndTime;
+}

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

@@ -0,0 +1,35 @@
+import max from '../max/index';
+import min from '../min/index';
+import type { Interval } from '../types';
+
+/**
+ * @name clamp
+ * @category Interval Helpers
+ * @summary Return a date bounded by the start and the end of the given interval
+ *
+ * @description
+ * Clamps a date to the lower bound with the start of the interval and the upper
+ * bound with the end of the interval.
+ *
+ * - When the date is less than the start of the interval, the start is returned.
+ * - When the date is greater than the end of the interval, the end is returned.
+ * - Otherwise the date is returned.
+ *
+ * @example
+ * // What is Mar, 21, 2021 bounded to an interval starting at Mar, 22, 2021 and ending at Apr, 01, 2021
+ * const result = clamp(new Date(2021, 2, 21), {
+ *   start: new Date(2021, 2, 22),
+ *   end: new Date(2021, 3, 1),
+ * })
+ * //=> Mon Mar 22 2021 00:00:00
+ *
+ * @param date - the date to be bounded
+ * @param interval - the interval to bound to
+ * @returns the date bounded by the start and the end of the interval
+ */
+export default function clamp<DateType extends Date>(
+  date: DateType | number,
+  { start, end }: Interval
+): DateType | Date {
+  return min([max([date, start]), end]);
+}

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

@@ -0,0 +1,55 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name closestIndexTo
+ * @category Common Helpers
+ * @summary Return an index of the closest date from the array comparing to the given date.
+ *
+ * @description
+ * Return an index of the closest date from the array comparing to the given date.
+ *
+ * @param dateToCompare - the date to compare with
+ * @param datesArray - the array to search
+ * @returns an index of the date closest to the given date or undefined if no valid value is given
+ *
+ * @example
+ * // Which date is closer to 6 September 2015?
+ * const dateToCompare = new Date(2015, 8, 6)
+ * const datesArray = [
+ *   new Date(2015, 0, 1),
+ *   new Date(2016, 0, 1),
+ *   new Date(2017, 0, 1)
+ * ]
+ * const result = closestIndexTo(dateToCompare, datesArray)
+ * //=> 1
+ */
+export default function closestIndexTo<DateType extends Date>(
+  dirtyDateToCompare: DateType | number,
+  datesArray: Array<DateType | number>
+): number | undefined {
+  const dateToCompare = toDate(dirtyDateToCompare);
+
+  if (isNaN(Number(dateToCompare))) return NaN;
+
+  const timeToCompare = dateToCompare.getTime();
+
+  let result: number | undefined;
+  let minDistance: number;
+  datesArray.forEach(function (dirtyDate, index) {
+    const currentDate = toDate(dirtyDate);
+
+    if (isNaN(Number(currentDate))) {
+      result = NaN;
+      minDistance = NaN;
+      return;
+    }
+
+    const distance = Math.abs(timeToCompare - currentDate.getTime());
+    if (result == null || distance < minDistance) {
+      result = index;
+      minDistance = distance;
+    }
+  });
+
+  return result;
+}

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

@@ -0,0 +1,54 @@
+import constructFrom from '../constructFrom/index';
+import toDate from '../toDate/index';
+
+/**
+ * @name closestTo
+ * @category Common Helpers
+ * @summary Return a date from the array closest to the given date.
+ *
+ * @description
+ * Return a date from the array closest to the given date.
+ *
+ * @param dateToCompare - the date to compare with
+ * @param datesArray - the array to search
+ * @returns the date from the array closest to the given date or undefined if no valid value is given
+ *
+ * @example
+ * // Which date is closer to 6 September 2015: 1 January 2000 or 1 January 2030?
+ * const dateToCompare = new Date(2015, 8, 6)
+ * const result = closestTo(dateToCompare, [
+ *   new Date(2000, 0, 1),
+ *   new Date(2030, 0, 1)
+ * ])
+ * //=> Tue Jan 01 2030 00:00:00
+ */
+export default function closestTo<DateType extends Date>(
+  dirtyDateToCompare: DateType | number,
+  datesArray: Array<DateType | number>
+): DateType | undefined {
+  const dateToCompare = toDate(dirtyDateToCompare);
+
+  if (isNaN(Number(dateToCompare))) return constructFrom(dirtyDateToCompare, NaN);
+
+  const timeToCompare = dateToCompare.getTime();
+
+  let result: DateType | undefined;
+  let minDistance: number;
+  datesArray.forEach((dirtyDate) => {
+    const currentDate = toDate(dirtyDate);
+
+    if (isNaN(Number(currentDate))) {
+      result = constructFrom(dirtyDateToCompare, NaN);
+      minDistance = NaN;
+      return;
+    }
+
+    const distance = Math.abs(timeToCompare - currentDate.getTime());
+    if (result == null || distance < minDistance) {
+      result = currentDate;
+      minDistance = distance;
+    }
+  });
+
+  return result;
+}

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

@@ -0,0 +1,51 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name compareAsc
+ * @category Common Helpers
+ * @summary Compare the two dates and return -1, 0 or 1.
+ *
+ * @description
+ * Compare the two dates and return 1 if the first date is after the second,
+ * -1 if the first date is before the second or 0 if dates are equal.
+ *
+ * @param dateLeft - the first date to compare
+ * @param dateRight - the second date to compare
+ * @returns the result of the comparison
+ *
+ * @example
+ * // Compare 11 February 1987 and 10 July 1989:
+ * const result = compareAsc(new Date(1987, 1, 11), new Date(1989, 6, 10))
+ * //=> -1
+ *
+ * @example
+ * // Sort the array of dates:
+ * const result = [
+ *   new Date(1995, 6, 2),
+ *   new Date(1987, 1, 11),
+ *   new Date(1989, 6, 10)
+ * ].sort(compareAsc)
+ * //=> [
+ * //   Wed Feb 11 1987 00:00:00,
+ * //   Mon Jul 10 1989 00:00:00,
+ * //   Sun Jul 02 1995 00:00:00
+ * // ]
+ */
+export default function compareAsc<DateType extends Date>(
+  dirtyDateLeft: DateType | number,
+  dirtyDateRight: DateType | number
+): number {
+  const dateLeft = toDate(dirtyDateLeft);
+  const dateRight = toDate(dirtyDateRight);
+
+  const diff = dateLeft.getTime() - dateRight.getTime();
+
+  if (diff < 0) {
+    return -1;
+  } else if (diff > 0) {
+    return 1;
+    // Return 0 if diff is 0; return NaN if diff is NaN
+  } else {
+    return diff;
+  }
+}

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

@@ -0,0 +1,51 @@
+import toDate from '../toDate/index';
+
+/**
+ * @name compareDesc
+ * @category Common Helpers
+ * @summary Compare the two dates reverse chronologically and return -1, 0 or 1.
+ *
+ * @description
+ * Compare the two dates and return -1 if the first date is after the second,
+ * 1 if the first date is before the second or 0 if dates are equal.
+ *
+ * @param dateLeft - the first date to compare
+ * @param dateRight - the second date to compare
+ * @returns the result of the comparison
+ *
+ * @example
+ * // Compare 11 February 1987 and 10 July 1989 reverse chronologically:
+ * const result = compareDesc(new Date(1987, 1, 11), new Date(1989, 6, 10))
+ * //=> 1
+ *
+ * @example
+ * // Sort the array of dates in reverse chronological order:
+ * const result = [
+ *   new Date(1995, 6, 2),
+ *   new Date(1987, 1, 11),
+ *   new Date(1989, 6, 10)
+ * ].sort(compareDesc)
+ * //=> [
+ * //   Sun Jul 02 1995 00:00:00,
+ * //   Mon Jul 10 1989 00:00:00,
+ * //   Wed Feb 11 1987 00:00:00
+ * // ]
+ */
+export default function compareDesc<DateType extends Date>(
+  dirtyDateLeft: DateType | number,
+  dirtyDateRight: DateType | number
+): number {
+  const dateLeft = toDate(dirtyDateLeft);
+  const dateRight = toDate(dirtyDateRight);
+
+  const diff = dateLeft.getTime() - dateRight.getTime();
+
+  if (diff > 0) {
+    return -1;
+  } else if (diff < 0) {
+    return 1;
+    // Return 0 if diff is 0; return NaN if diff is NaN
+  } else {
+    return diff;
+  }
+}

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

@@ -0,0 +1,233 @@
+/**
+ * Days in 1 week.
+ *
+ * @name daysInWeek
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const daysInWeek = 7;
+
+/**
+ * Days in 1 year
+ * One years equals 365.2425 days according to the formula:
+ *
+ * > Leap year occures every 4 years, except for years that are divisable by 100 and not divisable by 400.
+ * > 1 mean year = (365+1/4-1/100+1/400) days = 365.2425 days
+ *
+ * @name daysInYear
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const daysInYear: number = 365.2425;
+
+/**
+ * Maximum allowed time.
+ *
+ * @name maxTime
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const maxTime = Math.pow(10, 8) * 24 * 60 * 60 * 1000;
+
+/**
+ * Milliseconds in 1 week.
+ *
+ * @name millisecondsInWeek
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const millisecondsInWeek = 604800000;
+
+/**
+ * Milliseconds in 1 day.
+ *
+ * @name millisecondsInDay
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const millisecondsInDay = 86400000;
+
+/**
+ * Milliseconds in 1 minute
+ *
+ * @name millisecondsInMinute
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const millisecondsInMinute = 60000;
+
+/**
+ * Milliseconds in 1 hour
+ *
+ * @name millisecondsInHour
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const millisecondsInHour = 3600000;
+
+/**
+ * Milliseconds in 1 second
+ *
+ * @name millisecondsInSecond
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const millisecondsInSecond = 1000;
+
+/**
+ * Minimum allowed time.
+ *
+ * @name minTime
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const minTime = -maxTime;
+
+/**
+ * Minutes in 1 year.
+ *
+ * @name minutesInYear
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const minutesInYear = 525600;
+
+/**
+ * Minutes in 1 month.
+ *
+ * @name minutesInMonth
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const minutesInMonth = 43200;
+
+/**
+ * Minutes in 1 day.
+ *
+ * @name minutesInDay
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const minutesInDay = 1440;
+
+/**
+ * Minutes in 1 hour.
+ *
+ * @name minutesInHour
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const minutesInHour = 60;
+
+/**
+ * Months in 1 quarter.
+ *
+ * @name monthsInQuarter
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const monthsInQuarter = 3;
+
+/**
+ * Months in 1 year.
+ *
+ * @name monthsInYear
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const monthsInYear = 12;
+
+/**
+ * Quarters in 1 year
+ *
+ * @name quartersInYear
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const quartersInYear = 4;
+
+/**
+ * Seconds in 1 hour.
+ *
+ * @name secondsInHour
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const secondsInHour = 3600;
+
+/**
+ * Seconds in 1 minute.
+ *
+ * @name secondsInMinute
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const secondsInMinute = 60;
+
+/**
+ * Seconds in 1 day.
+ *
+ * @name secondsInDay
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const secondsInDay = secondsInHour * 24;
+
+/**
+ * Seconds in 1 week.
+ *
+ * @name secondsInWeek
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const secondsInWeek = secondsInDay * 7;
+
+/**
+ * Seconds in 1 year.
+ *
+ * @name secondsInYear
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const secondsInYear = secondsInDay * daysInYear;
+
+/**
+ * Seconds in 1 month
+ *
+ * @name secondsInMonth
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const secondsInMonth = secondsInYear / 12;
+
+/**
+ * Seconds in 1 quarter.
+ *
+ * @name secondsInQuarter
+ * @constant
+ * @type {number}
+ * @default
+ */
+export const secondsInQuarter = secondsInMonth * 3;

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

@@ -0,0 +1,34 @@
+import type { GenericDateConstructor } from '../types';
+
+/**
+ * @name constructFrom
+ * @category Date Extension Helpers
+ * @summary Constructs a date using the reference date and the value
+ *
+ * @description
+ * The function constructs a new date using the constructor from the reference
+ * date and the given value. It helps to build generic functions that accept
+ * date extensions.
+ *
+ * @param date {Date|number} - the reference date to take constructor from
+ * @param value {Date|number} - the value to create the date
+ * @returns date initialized using the given date and value
+ *
+ * @example
+ * import { constructFrom } from 'date-fns'
+ *
+ * // A function that clones a date preserving the original type
+ * function cloneDate<DateType extends Date(date: DateType): DateType {
+ *   return constructFrom(
+ *     date, // Use contrustor from the given date
+ *     date.getTime() // Use the date value to create a new date
+ *   )
+ * }
+ */
+export default function constructFrom<DateType extends Date>(date: DateType | number, value: Date | number): DateType {
+  if (date instanceof Date) {
+    return new (date.constructor as GenericDateConstructor<DateType>)(value);
+  } else {
+    return new Date(value) as DateType;
+  }
+}

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

@@ -0,0 +1,28 @@
+import { daysInWeek } from '../constants/index';
+
+/**
+ * @name daysToWeeks
+ * @category Conversion Helpers
+ * @summary Convert days to weeks.
+ *
+ * @description
+ * Convert a number of days to a full number of weeks.
+ *
+ * @param days - number of days to be converted
+ *
+ * @returns the number of days converted in weeks
+ *
+ * @example
+ * // Convert 14 days to weeks:
+ * const result = daysToWeeks(14)
+ * //=> 2
+ *
+ * @example
+ * // It uses floor rounding:
+ * const result = daysToWeeks(13)
+ * //=> 1
+ */
+export default function daysToWeeks(days: number): number {
+  const weeks = days / daysInWeek;
+  return Math.floor(weeks);
+}

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

@@ -0,0 +1,81 @@
+import addDays from '../addDays/index';
+import differenceInCalendarDays from '../differenceInCalendarDays/index';
+import isSameDay from '../isSameDay/index';
+import isValid from '../isValid/index';
+import isWeekend from '../isWeekend/index';
+import toDate from '../toDate/index';
+
+/**
+ * @name differenceInBusinessDays
+ * @category Day Helpers
+ * @summary Get the number of business days between the given dates.
+ *
+ * @description
+ * Get the number of business day periods between the given dates.
+ * Business days being days that arent in the weekend.
+ * Like `differenceInCalendarDays`, the function removes the times from
+ * the dates before calculating the difference.
+ *
+ * @param dateLeft - the later date
+ * @param dateRight - the earlier date
+ * @returns the number of business days
+ *
+ * @example
+ * // How many business days are between
+ * // 10 January 2014 and 20 July 2014?
+ * const result = differenceInBusinessDays(
+ *   new Date(2014, 6, 20),
+ *   new Date(2014, 0, 10)
+ * )
+ * //=> 136
+ *
+ * // How many business days are between
+ * // 30 November 2021 and 1 November 2021?
+ * const result = differenceInBusinessDays(
+ *   new Date(2021, 10, 30),
+ *   new Date(2021, 10, 1)
+ * )
+ * //=> 21
+ *
+ * // How many business days are between
+ * // 1 November 2021 and 1 December 2021?
+ * const result = differenceInBusinessDays(
+ *   new Date(2021, 10, 1),
+ *   new Date(2021, 11, 1)
+ * )
+ * //=> -22
+ *
+ * // How many business days are between
+ * // 1 November 2021 and 1 November 2021 ?
+ * const result = differenceInBusinessDays(
+ *   new Date(2021, 10, 1),
+ *   new Date(2021, 10, 1)
+ * )
+ * //=> 0
+ */
+export default function differenceInBusinessDays<DateType extends Date>(
+  dirtyDateLeft: DateType | number,
+  dirtyDateRight: DateType | number
+): number {
+  const dateLeft = toDate(dirtyDateLeft);
+  let dateRight = toDate(dirtyDateRight);
+
+  if (!isValid(dateLeft) || !isValid(dateRight)) return NaN;
+
+  const calendarDifference = differenceInCalendarDays(dateLeft, dateRight);
+  const sign = calendarDifference < 0 ? -1 : 1;
+
+  const weeks = Math.trunc(calendarDifference / 7);
+
+  let result = weeks * 5;
+  dateRight = addDays(dateRight, weeks * 7);
+
+  // the loop below will run at most 6 times to account for the remaining days that don't makeup a full week
+  while (!isSameDay(dateLeft, dateRight)) {
+    // sign is used to account for both negative and positive differences
+    result += isWeekend(dateRight) ? 0 : sign;
+    dateRight = addDays(dateRight, sign);
+  }
+
+  return result === 0 ? 0 : result;
+}