@checkdigit/time 1.1.0 → 2.0.0-PR.14-c36c

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

@@ -0,0 +1,275 @@
+import { millisecondsInHour, millisecondsInMinute } from '../constants/index';
+
+/**
+ * The {@link parseISO} function options.
+ */
+export interface ParseISOOptions {
+  additionalDigits?: 0 | 1 | 2;
+}
+
+/**
+ * @name parseISO
+ * @category Common Helpers
+ * @summary Parse ISO string
+ *
+ * @description
+ * Parse the given string in ISO 8601 format and return an instance of Date.
+ *
+ * Function accepts complete ISO 8601 formats as well as partial implementations.
+ * ISO 8601: http://en.wikipedia.org/wiki/ISO_8601
+ *
+ * If the argument isn't a string, the function cannot parse the string or
+ * the values are invalid, it returns Invalid Date.
+ *
+ * @param argument - the value to convert
+ * @param options - an object with options.
+ * @returns the parsed date in the local time zone
+ *
+ * @example
+ * // Convert string '2014-02-11T11:30:30' to date:
+ * const result = parseISO('2014-02-11T11:30:30')
+ * //=> Tue Feb 11 2014 11:30:30
+ *
+ * @example
+ * // Convert string '+02014101' to date,
+ * // if the additional number of digits in the extended year format is 1:
+ * const result = parseISO('+02014101', { additionalDigits: 1 })
+ * //=> Fri Apr 11 2014 00:00:00
+ */
+export default function parseISO(argument: string, options?: ParseISOOptions): Date {
+  const additionalDigits = options?.additionalDigits ?? 2;
+  const dateStrings = splitDateString(argument);
+
+  let date;
+  if (dateStrings.date) {
+    const parseYearResult = parseYear(dateStrings.date, additionalDigits);
+    date = parseDate(parseYearResult.restDateString, parseYearResult.year);
+  }
+
+  if (!date || isNaN(date.getTime())) {
+    return new Date(NaN);
+  }
+
+  const timestamp = date.getTime();
+  let time = 0;
+  let offset;
+
+  if (dateStrings.time) {
+    time = parseTime(dateStrings.time);
+    if (isNaN(time)) {
+      return new Date(NaN);
+    }
+  }
+
+  if (dateStrings.timezone) {
+    offset = parseTimezone(dateStrings.timezone);
+    if (isNaN(offset)) {
+      return new Date(NaN);
+    }
+  } else {
+    const dirtyDate = new Date(timestamp + time);
+    // js parsed string assuming it's in UTC timezone
+    // but we need it to be parsed in our timezone
+    // so we use utc values to build date in our timezone.
+    // Year values from 0 to 99 map to the years 1900 to 1999
+    // so set year explicitly with setFullYear.
+    const result = new Date(0);
+    result.setFullYear(dirtyDate.getUTCFullYear(), dirtyDate.getUTCMonth(), dirtyDate.getUTCDate());
+    result.setHours(
+      dirtyDate.getUTCHours(),
+      dirtyDate.getUTCMinutes(),
+      dirtyDate.getUTCSeconds(),
+      dirtyDate.getUTCMilliseconds(),
+    );
+    return result;
+  }
+
+  return new Date(timestamp + time + offset);
+}
+
+interface DateString {
+  date?: string;
+  time?: string;
+  timezone?: string;
+}
+
+interface ParsedYear {
+  year: number;
+  restDateString: string;
+}
+
+const patterns = {
+  dateTimeDelimiter: /[T ]/,
+  timeZoneDelimiter: /[Z ]/i,
+  timezone: /([Z+-].*)$/,
+};
+
+const dateRegex = /^-?(?:(\d{3})|(\d{2})(?:-?(\d{2}))?|W(\d{2})(?:-?(\d{1}))?|)$/;
+const timeRegex = /^(\d{2}(?:[.,]\d*)?)(?::?(\d{2}(?:[.,]\d*)?))?(?::?(\d{2}(?:[.,]\d*)?))?$/;
+const timezoneRegex = /^([+-])(\d{2})(?::?(\d{2}))?$/;
+
+function splitDateString(dateString: string): DateString {
+  const dateStrings: DateString = {};
+  const array = dateString.split(patterns.dateTimeDelimiter);
+  let timeString;
+
+  // The regex match should only return at maximum two array elements.
+  // [date], [time], or [date, time].
+  if (array.length > 2) {
+    return dateStrings;
+  }
+
+  if (/:/.test(array[0] as string)) {
+    timeString = array[0];
+  } else {
+    dateStrings.date = array[0] as string;
+    timeString = array[1];
+    if (patterns.timeZoneDelimiter.test(dateStrings.date)) {
+      dateStrings.date = dateString.split(patterns.timeZoneDelimiter)[0] as string;
+      timeString = dateString.substr(dateStrings.date.length, dateString.length);
+    }
+  }
+
+  if (timeString) {
+    const token = patterns.timezone.exec(timeString);
+    if (token) {
+      dateStrings.time = timeString.replace(token[1] as string, '');
+      dateStrings.timezone = token[1] as string;
+    } else {
+      dateStrings.time = timeString;
+    }
+  }
+
+  return dateStrings;
+}
+
+function parseYear(dateString: string, additionalDigits: number): ParsedYear {
+  const regex = new RegExp(
+    '^(?:(\\d{4}|[+-]\\d{' + (4 + additionalDigits) + '})|(\\d{2}|[+-]\\d{' + (2 + additionalDigits) + '})$)',
+  );
+
+  const captures = dateString.match(regex);
+  // Invalid ISO-formatted year
+  if (!captures) return { year: NaN, restDateString: '' };
+
+  const year = captures[1] ? parseInt(captures[1]) : null;
+  const century = captures[2] ? parseInt(captures[2]) : null;
+
+  // either year or century is null, not both
+  return {
+    year: century === null ? (year as number) : century * 100,
+    restDateString: dateString.slice(((captures[1] as string) || (captures[2] as string)).length),
+  };
+}
+
+function parseDate(dateString: string, year: number): Date {
+  // Invalid ISO-formatted year
+  if (year === null) return new Date(NaN);
+
+  const captures = dateString.match(dateRegex);
+  // Invalid ISO-formatted string
+  if (!captures) return new Date(NaN);
+
+  const isWeekDate = !!captures[4];
+  const dayOfYear = parseDateUnit(captures[1] as string);
+  const month = parseDateUnit(captures[2] as string) - 1;
+  const day = parseDateUnit(captures[3] as string);
+  const week = parseDateUnit(captures[4] as string);
+  const dayOfWeek = parseDateUnit(captures[5] as string) - 1;
+
+  if (isWeekDate) {
+    if (!validateWeekDate(year, week, dayOfWeek)) {
+      return new Date(NaN);
+    }
+    return dayOfISOWeekYear(year, week, dayOfWeek);
+  } else {
+    const date = new Date(0);
+    if (!validateDate(year, month, day) || !validateDayOfYearDate(year, dayOfYear)) {
+      return new Date(NaN);
+    }
+    date.setUTCFullYear(year, month, Math.max(dayOfYear, day));
+    return date;
+  }
+}
+
+function parseDateUnit(value: string): number {
+  return value ? parseInt(value) : 1;
+}
+
+function parseTime(timeString: string): number {
+  const captures = timeString.match(timeRegex);
+  if (!captures) return NaN; // Invalid ISO-formatted time
+
+  const hours = parseTimeUnit(captures[1] as string);
+  const minutes = parseTimeUnit(captures[2] as string);
+  const seconds = parseTimeUnit(captures[3] as string);
+
+  if (!validateTime(hours, minutes, seconds)) {
+    return NaN;
+  }
+
+  return hours * millisecondsInHour + minutes * millisecondsInMinute + seconds * 1000;
+}
+
+function parseTimeUnit(value: string): number {
+  return (value && parseFloat(value.replace(',', '.'))) || 0;
+}
+
+function parseTimezone(timezoneString: string): number {
+  if (timezoneString === 'Z') return 0;
+
+  const captures = timezoneString.match(timezoneRegex);
+  if (!captures) return 0;
+
+  const sign = captures[1] === '+' ? -1 : 1;
+  const hours = parseInt(captures[2] as string);
+  const minutes = (captures[3] && parseInt(captures[3])) || 0;
+
+  if (!validateTimezone(hours, minutes)) {
+    return NaN;
+  }
+
+  return sign * (hours * millisecondsInHour + minutes * millisecondsInMinute);
+}
+
+function dayOfISOWeekYear(isoWeekYear: number, week: number, day: number): Date {
+  const date = new Date(0);
+  date.setUTCFullYear(isoWeekYear, 0, 4);
+  const fourthOfJanuaryDay = date.getUTCDay() || 7;
+  const diff = (week - 1) * 7 + day + 1 - fourthOfJanuaryDay;
+  date.setUTCDate(date.getUTCDate() + diff);
+  return date;
+}
+
+// Validation functions
+
+// February is null to handle the leap year (using ||)
+const daysInMonths = [31, null, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+function isLeapYearIndex(year: number): boolean {
+  return year % 400 === 0 || (year % 4 === 0 && year % 100 !== 0);
+}
+
+function validateDate(year: number, month: number, date: number): boolean {
+  return month >= 0 && month <= 11 && date >= 1 && date <= (daysInMonths[month] || (isLeapYearIndex(year) ? 29 : 28));
+}
+
+function validateDayOfYearDate(year: number, dayOfYear: number): boolean {
+  return dayOfYear >= 1 && dayOfYear <= (isLeapYearIndex(year) ? 366 : 365);
+}
+
+function validateWeekDate(_year: number, week: number, day: number): boolean {
+  return week >= 1 && week <= 53 && day >= 0 && day <= 6;
+}
+
+function validateTime(hours: number, minutes: number, seconds: number): boolean {
+  if (hours === 24) {
+    return minutes === 0 && seconds === 0;
+  }
+
+  return seconds >= 0 && seconds < 60 && minutes >= 0 && minutes < 60 && hours >= 0 && hours < 25;
+}
+
+function validateTimezone(_hours: number, minutes: number): boolean {
+  return minutes >= 0 && minutes <= 59;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * @name parseJSON
+ * @category Common Helpers
+ * @summary Parse a JSON date string
+ *
+ * @description
+ * Converts a complete ISO date string in UTC time, the typical format for transmitting
+ * a date in JSON, to a JavaScript `Date` instance.
+ *
+ * This is a minimal implementation for converting dates retrieved from a JSON API to
+ * a `Date` instance which can be used with other functions in the `date-fns` library.
+ * The following formats are supported:
+ *
+ * - `2000-03-15T05:20:10.123Z`: The output of `.toISOString()` and `JSON.stringify(new Date())`
+ * - `2000-03-15T05:20:10Z`: Without milliseconds
+ * - `2000-03-15T05:20:10+00:00`: With a zero offset, the default JSON encoded format in some other languages
+ * - `2000-03-15T05:20:10+05:45`: With a positive or negative offset, the default JSON encoded format in some other languages
+ * - `2000-03-15T05:20:10+0000`: With a zero offset without a colon
+ * - `2000-03-15T05:20:10`: Without a trailing 'Z' symbol
+ * - `2000-03-15T05:20:10.1234567`: Up to 7 digits in milliseconds field. Only first 3 are taken into account since JS does not allow fractional milliseconds
+ * - `2000-03-15 05:20:10`: With a space instead of a 'T' separator for APIs returning a SQL date without reformatting
+ *
+ * For convenience and ease of use these other input types are also supported
+ * via [toDate]{@link https://date-fns.org/docs/toDate}:
+ *
+ * - A `Date` instance will be cloned
+ * - A `number` will be treated as a timestamp
+ *
+ * Any other input type or invalid date strings will return an `Invalid Date`.
+ *
+ * @param argument A fully formed ISO8601 date string to convert
+ * @returns the parsed date in the local time zone
+ */
+export default function parseJSON(dateString: string): Date {
+  const parts = dateString.match(
+    /(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d{0,7}))?(?:Z|(.)(\d{2}):?(\d{2})?)?/,
+  );
+  if (parts) {
+    // Group 8 matches the sign
+    return new Date(
+      Date.UTC(
+        +(parts[1] as string),
+        +(parts[2] as string) - 1,
+        +(parts[3] as string),
+        +(parts[4] as string) - (+(parts[9] as string) || 0) * (parts[8] == '-' ? -1 : 1),
+        +(parts[5] as string) - (+(parts[10] as string) || 0) * (parts[8] == '-' ? -1 : 1),
+        +(parts[6] as string),
+        +((parts[7] || '0') + '00').substring(0, 3),
+      ),
+    );
+  }
+  return new Date(NaN);
+}

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

@@ -0,0 +1,32 @@
+import getDay from '../getDay/index';
+import subDays from '../subDays/index';
+import type { Day } from '../types';
+
+/**
+ * @name previousDay
+ * @category Weekday Helpers
+ * @summary When is the previous day of the week?
+ *
+ * @description
+ * When is the previous day of the week? 0-6 the day of the week, 0 represents Sunday.
+ *
+ * @param date - the date to check
+ * @param day - day of the week
+ * @returns - the date is the previous day of week
+ *
+ * @example
+ * // When is the previous Monday before Mar, 20, 2020?
+ * const result = previousDay(new Date(2020, 2, 20), 1)
+ * //=> Mon Mar 16 2020 00:00:00
+ *
+ * @example
+ * // When is the previous Tuesday before Mar, 21, 2020?
+ * const result = previousDay(new Date(2020, 2, 21), 2)
+ * //=> Tue Mar 17 2020 00:00:00
+ */
+export default function previousDay<DateType extends Date>(date: DateType | number, day: Day): DateType {
+  let delta = getDay(date) - day;
+  if (delta <= 0) delta += 7;
+
+  return subDays(date, delta);
+}

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

@@ -0,0 +1,21 @@
+import previousDay from '../previousDay/index';
+
+/**
+ * @name previousFriday
+ * @category Weekday Helpers
+ * @summary When is the previous Friday?
+ *
+ * @description
+ * When is the previous Friday?
+ *
+ * @param date - the date to start counting from
+ * @returns the previous Friday
+ *
+ * @example
+ * // When is the previous Friday before Jun, 19, 2021?
+ * const result = previousFriday(new Date(2021, 5, 19))
+ * //=> Fri June 18 2021 00:00:00
+ */
+export default function previousFriday<DateType extends Date>(date: DateType | number): DateType {
+  return previousDay(date, 5);
+}

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

@@ -0,0 +1,21 @@
+import previousDay from '../previousDay/index';
+
+/**
+ * @name previousMonday
+ * @category Weekday Helpers
+ * @summary When is the previous Monday?
+ *
+ * @description
+ * When is the previous Monday?
+ *
+ * @param date - the date to start counting from
+ * @returns the previous Monday
+ *
+ * @example
+ * // When is the previous Monday before Jun, 18, 2021?
+ * const result = previousMonday(new Date(2021, 5, 18))
+ * //=> Mon June 14 2021 00:00:00
+ */
+export default function previousMonday<DateType extends Date>(date: DateType | number): DateType {
+  return previousDay(date, 1);
+}

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

@@ -0,0 +1,21 @@
+import previousDay from '../previousDay/index';
+
+/**
+ * @name previousSaturday
+ * @category Weekday Helpers
+ * @summary When is the previous Saturday?
+ *
+ * @description
+ * When is the previous Saturday?
+ *
+ * @param date - the date to start counting from
+ * @returns the previous Saturday
+ *
+ * @example
+ * // When is the previous Saturday before Jun, 20, 2021?
+ * const result = previousSaturday(new Date(2021, 5, 20))
+ * //=> Sat June 19 2021 00:00:00
+ */
+export default function previousSaturday<DateType extends Date>(date: DateType | number): DateType {
+  return previousDay(date, 6);
+}

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

@@ -0,0 +1,21 @@
+import previousDay from '../previousDay/index';
+
+/**
+ * @name previousSunday
+ * @category Weekday Helpers
+ * @summary When is the previous Sunday?
+ *
+ * @description
+ * When is the previous Sunday?
+ *
+ * @param date - the date to start counting from
+ * @returns the previous Sunday
+ *
+ * @example
+ * // When is the previous Sunday before Jun, 21, 2021?
+ * const result = previousSunday(new Date(2021, 5, 21))
+ * //=> Sun June 20 2021 00:00:00
+ */
+export default function previousSunday<DateType extends Date>(date: DateType | number): DateType {
+  return previousDay(date, 0);
+}

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

@@ -0,0 +1,21 @@
+import previousDay from '../previousDay/index';
+
+/**
+ * @name previousThursday
+ * @category Weekday Helpers
+ * @summary When is the previous Thursday?
+ *
+ * @description
+ * When is the previous Thursday?
+ *
+ * @param date - the date to start counting from
+ * @returns the previous Thursday
+ *
+ * @example
+ * // When is the previous Thursday before Jun, 18, 2021?
+ * const result = previousThursday(new Date(2021, 5, 18))
+ * //=> Thu June 17 2021 00:00:00
+ */
+export default function previousThursday<DateType extends Date>(date: DateType | number): DateType {
+  return previousDay(date, 4);
+}

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

@@ -0,0 +1,21 @@
+import previousDay from '../previousDay/index';
+
+/**
+ * @name previousTuesday
+ * @category Weekday Helpers
+ * @summary When is the previous Tuesday?
+ *
+ * @description
+ * When is the previous Tuesday?
+ *
+ * @param date - the date to start counting from
+ * @returns the previous Tuesday
+ *
+ * @example
+ * // When is the previous Tuesday before Jun, 18, 2021?
+ * const result = previousTuesday(new Date(2021, 5, 18))
+ * //=> Tue June 15 2021 00:00:00
+ */
+export default function previousTuesday<DateType extends Date>(date: DateType | number): DateType {
+  return previousDay(date, 2);
+}

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

@@ -0,0 +1,21 @@
+import previousDay from '../previousDay/index';
+
+/**
+ * @name previousWednesday
+ * @category Weekday Helpers
+ * @summary When is the previous Wednesday?
+ *
+ * @description
+ * When is the previous Wednesday?
+ *
+ * @param date - the date to start counting from
+ * @returns the previous Wednesday
+ *
+ * @example
+ * // When is the previous Wednesday before Jun, 18, 2021?
+ * const result = previousWednesday(new Date(2021, 5, 18))
+ * //=> Wed June 16 2021 00:00:00
+ */
+export default function previousWednesday<DateType extends Date>(date: DateType | number): DateType {
+  return previousDay(date, 3);
+}

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

@@ -0,0 +1,22 @@
+import { monthsInQuarter } from '../constants/index';
+
+/**
+ * @name quartersToMonths
+ * @category Conversion Helpers
+ * @summary Convert number of quarters to months.
+ *
+ * @description
+ * Convert a number of quarters to a full number of months.
+ *
+ * @param quarters - number of quarters to be converted
+ *
+ * @returns the number of quarters converted in months
+ *
+ * @example
+ * // Convert 2 quarters to months
+ * const result = quartersToMonths(2)
+ * //=> 6
+ */
+export default function quartersToMonths(quarters: number): number {
+  return Math.floor(quarters * monthsInQuarter);
+}

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

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

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

@@ -0,0 +1,59 @@
+import constructFrom from '../constructFrom/index';
+import toDate from '../toDate/index';
+import type { RoundingOptions } from '../types';
+import { getRoundingMethod } from '../_lib/roundingMethods/index';
+
+/**
+ * The {@link roundToNearestMinutes} function options.
+ */
+export interface RoundToNearestMinutesOptions extends RoundingOptions {
+  nearestTo?: number;
+}
+
+/**
+ * @name roundToNearestMinutes
+ * @category Minute Helpers
+ * @summary Rounds the given date to the nearest minute
+ *
+ * @description
+ * Rounds the given date to the nearest minute (or number of minutes).
+ * Rounds up when the given date is exactly between the nearest round minutes.
+ *
+ * @param date - the date to round
+ * @param options - an object with options.
+ * @returns the new date rounded to the closest minute
+ * @throws {RangeError} `options.nearestTo` must be between 1 and 30
+ *
+ * @example
+ * // Round 10 July 2014 12:12:34 to nearest minute:
+ * const result = roundToNearestMinutes(new Date(2014, 6, 10, 12, 12, 34))
+ * //=> Thu Jul 10 2014 12:13:00
+ *
+ * @example
+ * // Round 10 July 2014 12:07:30 to nearest quarter hour:
+ * const result = roundToNearestMinutes(new Date(2014, 6, 10, 12, 12, 34), { nearestTo: 15 })
+ * // rounds up because given date is exactly between 12:00:00 and 12:15:00
+ * //=> Thu Jul 10 2014 12:15:00
+ */
+export default function roundToNearestMinutes<DateType extends Date>(
+  dirtyDate: DateType | number,
+  options?: RoundToNearestMinutesOptions,
+): DateType {
+  const nearestTo = options?.nearestTo ?? 1;
+
+  if (nearestTo < 1 || nearestTo > 30) {
+    throw new RangeError('`options.nearestTo` must be between 1 and 30');
+  }
+
+  const date = toDate(dirtyDate);
+  const seconds = date.getSeconds(); // relevant if nearestTo is 1, which is the default case
+  const minutes = date.getMinutes() + seconds / 60;
+  const roundingMethod = getRoundingMethod(options?.roundingMethod);
+  const roundedMinutes = roundingMethod(minutes / nearestTo) * nearestTo;
+  const remainderMinutes = minutes % nearestTo;
+  const addedMinutes = Math.round(remainderMinutes / nearestTo) * nearestTo;
+
+  const result = constructFrom(date, date);
+  result.setMinutes(roundedMinutes + addedMinutes, 0, 0);
+  return result;
+}

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

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

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

@@ -0,0 +1,22 @@
+import { millisecondsInSecond } from '../constants/index';
+
+/**
+ * @name secondsToMilliseconds
+ * @category Conversion Helpers
+ * @summary Convert seconds to milliseconds.
+ *
+ * @description
+ * Convert a number of seconds to a full number of milliseconds.
+ *
+ * @param seconds - number of seconds to be converted
+ *
+ * @returns the number of seconds converted in milliseconds
+ *
+ * @example
+ * // Convert 2 seconds into milliseconds
+ * const result = secondsToMilliseconds(2)
+ * //=> 2000
+ */
+export default function secondsToMilliseconds(seconds: number): number {
+  return seconds * millisecondsInSecond;
+}