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

package/src/date-fns-tz/toDate/index.ts

@@ -0,0 +1,442 @@
+import getTimezoneOffsetInMilliseconds from '../../date-fns/_lib/getTimezoneOffsetInMilliseconds';
+import tzParseTimezone from '../_lib/tzParseTimezone';
+import tzPattern from '../_lib/tzPattern';
+import type { OptionsWithTZ } from '../types';
+
+const MILLISECONDS_IN_HOUR = 3600000;
+const MILLISECONDS_IN_MINUTE = 60000;
+const DEFAULT_ADDITIONAL_DIGITS = 2;
+
+const patterns = {
+  dateTimePattern: /^([0-9W+-]+)(T| )(.*)/,
+  datePattern: /^([0-9W+-]+)(.*)/,
+  plainTime: /:/,
+
+  // year tokens
+  YY: /^(\d{2})$/,
+  YYY: [
+    /^([+-]\d{2})$/, // 0 additional digits
+    /^([+-]\d{3})$/, // 1 additional digit
+    /^([+-]\d{4})$/, // 2 additional digits
+  ],
+  YYYY: /^(\d{4})/,
+  YYYYY: [
+    /^([+-]\d{4})/, // 0 additional digits
+    /^([+-]\d{5})/, // 1 additional digit
+    /^([+-]\d{6})/, // 2 additional digits
+  ],
+
+  // date tokens
+  MM: /^-(\d{2})$/,
+  DDD: /^-?(\d{3})$/,
+  MMDD: /^-?(\d{2})-?(\d{2})$/,
+  Www: /^-?W(\d{2})$/,
+  WwwD: /^-?W(\d{2})-?(\d{1})$/,
+
+  HH: /^(\d{2}([.,]\d*)?)$/,
+  HHMM: /^(\d{2}):?(\d{2}([.,]\d*)?)$/,
+  HHMMSS: /^(\d{2}):?(\d{2}):?(\d{2}([.,]\d*)?)$/,
+
+  // time zone tokens (to identify the presence of a tz)
+  timeZone: tzPattern,
+};
+
+/**
+ * @name toDate
+ * @category Common Helpers
+ * @summary Convert the given argument to an instance of Date.
+ *
+ * @description
+ * Convert the given argument to an instance of Date.
+ *
+ * If the argument is an instance of Date, the function returns its clone.
+ *
+ * If the argument is a number, it is treated as a timestamp.
+ *
+ * If an argument is a string, the function tries to parse it.
+ * Function accepts complete ISO 8601 formats as well as partial implementations.
+ * ISO 8601: http://en.wikipedia.org/wiki/ISO_8601
+ * If the function cannot parse the string or the values are invalid, it returns Invalid Date.
+ *
+ * If the argument is none of the above, the function returns Invalid Date.
+ *
+ * **Note**: *all* Date arguments passed to any *date-fns* function is processed by `toDate`.
+ * All *date-fns* functions will throw `RangeError` if `options.additionalDigits` is not 0, 1, 2 or undefined.
+ *
+ * @param {Date|String|Number} argument - the value to convert
+ * @param {OptionsWithTZ} [options] - the object with options. See [Options]{@link https://date-fns.org/docs/Options}
+ * @param {0|1|2} [options.additionalDigits=2] - the additional number of digits in the extended year format
+ * @param {String} [options.timeZone=''] - used to specify the IANA time zone offset of a date String.
+ * @returns {Date} the parsed date in the local time zone
+ * @throws {TypeError} 1 argument required
+ * @throws {RangeError} `options.additionalDigits` must be 0, 1 or 2
+ *
+ * @example
+ * // Convert string '2014-02-11T11:30:30' to date:
+ * var result = toDate('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:
+ * var result = toDate('+02014101', {additionalDigits: 1})
+ * //=> Fri Apr 11 2014 00:00:00
+ */
+export default function toDate(argument: Date | string | number, dirtyOptions?: OptionsWithTZ): Date {
+  if (arguments.length < 1) {
+    throw new TypeError('1 argument required, but only ' + arguments.length + ' present');
+  }
+
+  if (argument === null) {
+    return new Date(NaN);
+  }
+
+  var options = dirtyOptions || ({} as OptionsWithTZ);
+
+  var additionalDigits = options.additionalDigits == null ? DEFAULT_ADDITIONAL_DIGITS : options.additionalDigits;
+  if (additionalDigits !== 2 && additionalDigits !== 1 && additionalDigits !== 0) {
+    throw new RangeError('additionalDigits must be 0, 1 or 2');
+  }
+
+  // Clone the date
+  if (
+    argument instanceof Date ||
+    (typeof argument === 'object' && Object.prototype.toString.call(argument) === '[object Date]')
+  ) {
+    // Prevent the date to lose the milliseconds when passed to new Date() in IE10
+    return new Date(argument.getTime());
+  } else if (typeof argument === 'number' || Object.prototype.toString.call(argument) === '[object Number]') {
+    return new Date(argument);
+  } else if (!(typeof argument === 'string' || Object.prototype.toString.call(argument) === '[object String]')) {
+    return new Date(NaN);
+  }
+
+  var dateStrings = splitDateString(argument);
+
+  var parseYearResult = parseYear(dateStrings.date, additionalDigits);
+  var year = parseYearResult.year;
+  var restDateString = parseYearResult.restDateString as string;
+
+  var date = parseDate(restDateString, year);
+
+  if (Number.isNaN(date)) {
+    return new Date(NaN);
+  }
+
+  if (date) {
+    var timestamp = date.getTime();
+    var time: number | null = 0;
+    var offset;
+
+    if (dateStrings.time) {
+      time = parseTime(dateStrings.time);
+
+      if (Number.isNaN(time)) {
+        return new Date(NaN);
+      }
+    }
+
+    if (dateStrings.timeZone || options.timeZone) {
+      offset = tzParseTimezone((dateStrings.timeZone || options.timeZone) as string, new Date(timestamp + (time ?? 0)));
+      if (isNaN(offset)) {
+        return new Date(NaN);
+      }
+    } else {
+      // get offset accurate to hour in time zones that change offset
+      offset = getTimezoneOffsetInMilliseconds(new Date(timestamp + (time ?? 0)));
+      offset = getTimezoneOffsetInMilliseconds(new Date(timestamp + (time ?? 0) + offset));
+    }
+
+    return new Date(timestamp + (time ?? 0) + offset);
+  } else {
+    return new Date(NaN);
+  }
+}
+
+function splitDateString(dateString: string) {
+  const dateStrings = {} as { date: string; time: string; timeZone: string };
+  let parts = patterns.dateTimePattern.exec(dateString);
+  let timeString;
+
+  if (!parts) {
+    parts = patterns.datePattern.exec(dateString);
+    if (parts) {
+      dateStrings.date = parts[1] as string;
+      timeString = parts[2];
+    } else {
+      dateStrings.date = null as unknown as string;
+      timeString = dateString;
+    }
+  } else {
+    dateStrings.date = parts[1] as string;
+    timeString = parts[3];
+  }
+
+  if (timeString) {
+    const token = patterns.timeZone.exec(timeString);
+    if (token) {
+      dateStrings.time = timeString.replace(token[1] as string, '');
+      dateStrings.timeZone = (token[1] as string).trim();
+    } else {
+      dateStrings.time = timeString;
+    }
+  }
+
+  return dateStrings;
+}
+
+function parseYear(dateString: string, additionalDigits: number) {
+  const patternYYY = patterns.YYY[additionalDigits];
+  const patternYYYYY = patterns.YYYYY[additionalDigits];
+
+  let token;
+
+  // YYYY or ±YYYYY
+  token = patterns.YYYY.exec(dateString) || patternYYYYY?.exec(dateString);
+  if (token) {
+    const yearString = token[1] as string;
+    return {
+      year: parseInt(yearString, 10),
+      restDateString: dateString.slice(yearString.length),
+    };
+  }
+
+  // YY or ±YYY
+  token = patterns.YY.exec(dateString) || patternYYY?.exec(dateString);
+  if (token) {
+    const centuryString = token[1] as string;
+    return {
+      year: parseInt(centuryString, 10) * 100,
+      restDateString: dateString.slice(centuryString.length),
+    };
+  }
+
+  // Invalid ISO-formatted year
+  return {
+    year: null,
+  };
+}
+
+function parseDate(dateString: string, year: number | null) {
+  // Invalid ISO-formatted year
+  if (year === null) {
+    return null;
+  }
+
+  var token;
+  var date;
+  var month;
+  var week;
+
+  // YYYY
+  if (dateString.length === 0) {
+    date = new Date(0);
+    date.setUTCFullYear(year);
+    return date;
+  }
+
+  // YYYY-MM
+  token = patterns.MM.exec(dateString);
+  if (token) {
+    date = new Date(0);
+    month = parseInt(token[1] as string, 10) - 1;
+
+    if (!validateDate(year, month)) {
+      return new Date(NaN);
+    }
+
+    date.setUTCFullYear(year, month);
+    return date;
+  }
+
+  // YYYY-DDD or YYYYDDD
+  token = patterns.DDD.exec(dateString);
+  if (token) {
+    date = new Date(0);
+    var dayOfYear = parseInt(token[1] as string, 10);
+
+    if (!validateDayOfYearDate(year, dayOfYear)) {
+      return new Date(NaN);
+    }
+
+    date.setUTCFullYear(year, 0, dayOfYear);
+    return date;
+  }
+
+  // yyyy-MM-dd or YYYYMMDD
+  token = patterns.MMDD.exec(dateString);
+  if (token) {
+    date = new Date(0);
+    month = parseInt(token[1] as string, 10) - 1;
+    var day = parseInt(token[2] as string, 10);
+
+    if (!validateDate(year, month, day)) {
+      return new Date(NaN);
+    }
+
+    date.setUTCFullYear(year, month, day);
+    return date;
+  }
+
+  // YYYY-Www or YYYYWww
+  token = patterns.Www.exec(dateString);
+  if (token) {
+    week = parseInt(token[1] as string, 10) - 1;
+
+    if (!validateWeekDate(year, week)) {
+      return new Date(NaN);
+    }
+
+    return dayOfISOWeekYear(year, week);
+  }
+
+  // YYYY-Www-D or YYYYWwwD
+  token = patterns.WwwD.exec(dateString);
+  if (token) {
+    week = parseInt(token[1] as string, 10) - 1;
+    var dayOfWeek = parseInt(token[2] as string, 10) - 1;
+
+    if (!validateWeekDate(year, week, dayOfWeek)) {
+      return new Date(NaN);
+    }
+
+    return dayOfISOWeekYear(year, week, dayOfWeek);
+  }
+
+  // Invalid ISO-formatted date
+  return null;
+}
+
+function parseTime(timeString: string) {
+  var token;
+  var hours;
+  var minutes;
+
+  // hh
+  token = patterns.HH.exec(timeString);
+  if (token) {
+    hours = parseFloat((token[1] as string).replace(',', '.'));
+
+    if (!validateTime(hours)) {
+      return NaN;
+    }
+
+    return (hours % 24) * MILLISECONDS_IN_HOUR;
+  }
+
+  // hh:mm or hhmm
+  token = patterns.HHMM.exec(timeString);
+  if (token) {
+    hours = parseInt(token[1] as string, 10);
+    minutes = parseFloat((token[2] as string).replace(',', '.'));
+
+    if (!validateTime(hours, minutes)) {
+      return NaN;
+    }
+
+    return (hours % 24) * MILLISECONDS_IN_HOUR + minutes * MILLISECONDS_IN_MINUTE;
+  }
+
+  // hh:mm:ss or hhmmss
+  token = patterns.HHMMSS.exec(timeString);
+  if (token) {
+    hours = parseInt(token[1] as string, 10);
+    minutes = parseInt(token[2] as string, 10);
+    var seconds = parseFloat((token[3] as string).replace(',', '.'));
+
+    if (!validateTime(hours, minutes, seconds)) {
+      return NaN;
+    }
+
+    return (hours % 24) * MILLISECONDS_IN_HOUR + minutes * MILLISECONDS_IN_MINUTE + seconds * 1000;
+  }
+
+  // Invalid ISO-formatted time
+  return null;
+}
+
+function dayOfISOWeekYear(isoWeekYear: number, week?: number, day?: number) {
+  week = week || 0;
+  day = day || 0;
+  var date = new Date(0);
+  date.setUTCFullYear(isoWeekYear, 0, 4);
+  var fourthOfJanuaryDay = date.getUTCDay() || 7;
+  var diff = week * 7 + day + 1 - fourthOfJanuaryDay;
+  date.setUTCDate(date.getUTCDate() + diff);
+  return date;
+}
+
+// Validation functions
+
+var DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+var DAYS_IN_MONTH_LEAP_YEAR = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+function isLeapYearIndex(year: number) {
+  return year % 400 === 0 || (year % 4 === 0 && year % 100 !== 0);
+}
+
+function validateDate(year: number, month: number, date?: number) {
+  if (month < 0 || month > 11) {
+    return false;
+  }
+
+  if (date != null) {
+    if (date < 1) {
+      return false;
+    }
+
+    var isLeapYear = isLeapYearIndex(year);
+    if (isLeapYear && date > (DAYS_IN_MONTH_LEAP_YEAR[month] as number)) {
+      return false;
+    }
+    if (!isLeapYear && date > (DAYS_IN_MONTH[month] as number)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function validateDayOfYearDate(year: number, dayOfYear: number) {
+  if (dayOfYear < 1) {
+    return false;
+  }
+
+  var isLeapYear = isLeapYearIndex(year);
+  if (isLeapYear && dayOfYear > 366) {
+    return false;
+  }
+  if (!isLeapYear && dayOfYear > 365) {
+    return false;
+  }
+
+  return true;
+}
+
+function validateWeekDate(_year: number, week: number, day?: number) {
+  if (week < 0 || week > 52) {
+    return false;
+  }
+
+  if (day != null && (day < 0 || day > 6)) {
+    return false;
+  }
+
+  return true;
+}
+
+function validateTime(hours?: number, minutes?: number, seconds?: number) {
+  if (hours != null && (hours < 0 || hours >= 25)) {
+    return false;
+  }
+
+  if (minutes != null && (minutes < 0 || minutes >= 60)) {
+    return false;
+  }
+
+  if (seconds != null && (seconds < 0 || seconds >= 60)) {
+    return false;
+  }
+
+  return true;
+}

package/src/date-fns-tz/types.ts

@@ -0,0 +1,14 @@
+import type { Locale } from '../date-fns/locale/types';
+
+export type OptionsWithTZ = {
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+  additionalDigits?: 0 | 1 | 2;
+  timeZone: string;
+  locale?: Locale;
+  includeSeconds?: boolean;
+  addSuffix?: boolean;
+  unit?: 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year';
+  roundingMethod?: 'floor' | 'ceil' | 'round';
+  awareOfUnicodeTokens?: boolean;
+};

package/src/date-fns-tz/utcToZonedTime/index.ts

@@ -0,0 +1,49 @@
+import tzParseTimezone from '../_lib/tzParseTimezone';
+import toDate from '../toDate';
+import type { OptionsWithTZ } from '../types';
+
+/**
+ * @name utcToZonedTime
+ * @category Time Zone Helpers
+ * @summary Get a date/time representing local time in a given time zone from the UTC date
+ *
+ * @description
+ * Returns a date instance with values representing the local time in the time zone
+ * specified of the UTC time from the date provided. In other words, when the new date
+ * is formatted it will show the equivalent hours in the target time zone regardless
+ * of the current system time zone.
+ *
+ * @param {Date|String|Number} date - the date with the relevant UTC time
+ * @param {String} timeZone - the time zone to get local time for, can be an offset or IANA time zone
+ * @param {OptionsWithTZ} [options] - the object with options. See [Options]{@link https://date-fns.org/docs/Options}
+ * @param {0|1|2} [options.additionalDigits=2] - passed to `toDate`. See [toDate]{@link https://date-fns.org/docs/toDate}
+ * @returns {Date} the new date with the equivalent time in the time zone
+ * @throws {TypeError} 2 arguments required
+ * @throws {RangeError} `options.additionalDigits` must be 0, 1 or 2
+ *
+ * @example
+ * // In June 10am UTC is 6am in New York (-04:00)
+ * const result = utcToZonedTime('2014-06-25T10:00:00.000Z', 'America/New_York')
+ * //=> Jun 25 2014 06:00:00
+ */
+export default function utcToZonedTime(
+  dirtyDate: Date | string | number,
+  timeZone: string,
+  options?: OptionsWithTZ
+): Date {
+  const date = toDate(dirtyDate, options);
+
+  const offsetMilliseconds = tzParseTimezone(timeZone, date, true);
+
+  const d = new Date(date.getTime() - offsetMilliseconds);
+
+  const resultDate = new Date(0);
+
+  resultDate.setFullYear(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+
+  resultDate.setHours(d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds(), d.getUTCMilliseconds());
+
+  // this hack is required because setHours doesn't work for hours that are spring-forward
+  (resultDate as any)[Symbol.for('UTCHours')] = d.getUTCHours();
+  return resultDate;
+}

package/src/date-fns-tz/zonedTimeToUtc/index.ts

@@ -0,0 +1,54 @@
+import cloneObject from '../../date-fns/_lib/cloneObject';
+import toDate from '../toDate';
+import tzPattern from '../_lib/tzPattern';
+import tzParseTimezone from '../_lib/tzParseTimezone';
+import newDateUTC from '../_lib/newDateUTC';
+import type { OptionsWithTZ } from '../types';
+
+/**
+ * @name zonedTimeToUtc
+ * @category Time Zone Helpers
+ * @summary Get the UTC date/time from a date representing local time in a given time zone
+ *
+ * @description
+ * Returns a date instance with the UTC time of the provided date of which the values
+ * represented the local time in the time zone specified. In other words, if the input
+ * date represented local time in time zone, the timestamp of the output date will
+ * give the equivalent UTC of that local time regardless of the current system time zone.
+ *
+ * @param {Date|String|Number} date - the date with values representing the local time
+ * @param {String} timeZone - the time zone of this local time, can be an offset or IANA time zone
+ * @param {OptionsWithTZ} [options] - the object with options. See [Options]{@link https://date-fns.org/docs/Options}
+ * @param {0|1|2} [options.additionalDigits=2] - passed to `toDate`. See [toDate]{@link https://date-fns.org/docs/toDate}
+ * @returns {Date} the new date with the equivalent time in the time zone
+ * @throws {TypeError} 2 arguments required
+ * @throws {RangeError} `options.additionalDigits` must be 0, 1 or 2
+ *
+ * @example
+ * // In June 10am in Los Angeles is 5pm UTC
+ * const result = zonedTimeToUtc(new Date(2014, 5, 25, 10, 0, 0), 'America/Los_Angeles')
+ * //=> 2014-06-25T17:00:00.000Z
+ */
+export default function zonedTimeToUtc(date: Date | string | number, timeZone: string, options: OptionsWithTZ): Date {
+  if (typeof date === 'string' && !date.match(tzPattern)) {
+    const extendedOptions = cloneObject(options);
+    extendedOptions.timeZone = timeZone;
+    return toDate(date, extendedOptions);
+  }
+
+  const d = toDate(date, options);
+
+  const utc = newDateUTC(
+    d.getFullYear(),
+    d.getMonth(),
+    d.getDate(),
+    d.getHours(),
+    d.getMinutes(),
+    d.getSeconds(),
+    d.getMilliseconds()
+  ).getTime();
+
+  const offsetMilliseconds = tzParseTimezone(timeZone, new Date(utc));
+
+  return new Date(utc + offsetMilliseconds);
+}

package/src/format-utc.ts

@@ -0,0 +1,7 @@
+// format-utc.ts
+
+import { tzFormat, tzUtcToZonedTime } from './date-fns-tz';
+
+export default function (date: Date | string | number, format: string): string {
+  return tzFormat(tzUtcToZonedTime(date, 'UTC'), format, { timeZone: 'UTC' });
+}

package/src/holidays/united-states/federal-reserve-bank/add-federal-reserve-bank-business-days.ts

@@ -0,0 +1,23 @@
+// holidays/united-states/federal-reserve-bank/add-federal-reserve-bank-business-days.ts
+
+import isFederalReserveBankHoliday from './is-federal-reserve-bank-holiday';
+
+export default function (date: Date, amount: number): Date {
+  if (Number.isNaN(amount)) {
+    throw new TypeError('Invalid Amount');
+  }
+
+  const endDate = new Date(date);
+  const hours = date.getUTCHours();
+
+  let count = 0;
+  while (count < amount) {
+    endDate.setUTCDate(endDate.getUTCDate() + 1);
+    if (!isFederalReserveBankHoliday(endDate)) {
+      count++;
+    }
+  }
+
+  endDate.setUTCHours(hours);
+  return endDate;
+}