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

package/src/holidays/united-states/federal-reserve-bank/get-all-us-federal-reserve-bank-holidays.ts

@@ -0,0 +1,190 @@
+// holidays/united-states/federal-reserve-bank/get-all-us-federal-reserve-bank-holidays.ts
+
+import { formatUtc } from '../../../index';
+
+const YYYY_MM_DD_FORMAT = 'yyyy-MM-dd';
+
+const DAY_OF_THE_WEEK_SUNDAY = 0;
+const DAY_OF_THE_WEEK_MONDAY = 1;
+const DAY_OF_THE_WEEK_THURSDAY = 4;
+const DAY_OF_THE_WEEK_SATURDAY = 6;
+
+const MONTH_JANUARY = 0;
+const MONTH_FEBRUARY = 1;
+const MONTH_MAY = 4;
+const MONTH_JUNE = 5;
+const MONTH_JULY = 6;
+const MONTH_SEPTEMBER = 8;
+const MONTH_OCTOBER = 9;
+const MONTH_NOVEMBER = 10;
+const MONTH_DECEMBER = 11;
+
+const DATE_ONE = 1;
+const DATE_TWO = 2;
+const DATE_FOUR = 4;
+const DATE_FIVE = 5;
+const DATE_ELEVEN = 11;
+const DATE_TWELVE = 12;
+const DATE_NINETEEN = 19;
+const DATE_TWENTY = 20;
+const DATE_TWENTY_FIVE = 25;
+const DATE_TWENTY_SIX = 26;
+const DATE_THIRTY_ONE = 31;
+
+const OCCURRENCE_FIRST = 1;
+const OCCURRENCE_SECOND = 2;
+const OCCURRENCE_THIRD = 3;
+const OCCURRENCE_FOURTH = 4;
+
+const YEAR2021 = 2021;
+
+export interface FederalReserveBankHoliday {
+  name: string;
+  date: string;
+  observedOn?: string | undefined;
+}
+
+function getLastMondayOfMay(year: number) {
+  const lastDayOfMay = new Date(year, MONTH_MAY, DATE_THIRTY_ONE); // last day of may
+  const lastMondayOfMayDay =
+    lastDayOfMay.getUTCDate() -
+    (lastDayOfMay.getUTCDay() - 1 < 1 ? DAY_OF_THE_WEEK_SATURDAY : lastDayOfMay.getUTCDay() - 1);
+  return formatUtc(new Date(year, MONTH_MAY, lastMondayOfMayDay), YYYY_MM_DD_FORMAT);
+}
+
+function getNthOccurrenceOfDayOfTheWeekInMonth(nth: number, dayOfTheWeek: number, month: number, year: number) {
+  const date = new Date(year, month, DATE_ONE); // first day of the month
+  date.setUTCDate(1 + ((7 - date.getUTCDay() + dayOfTheWeek) % 7) + (nth - 1) * 7);
+  return formatUtc(date, YYYY_MM_DD_FORMAT);
+}
+
+/**
+ * @name getAllUSFederalReserveBankHolidays
+ * @summary Get all US Federal Rserve Bank Holidays for the year
+ *
+ * @description
+ * US Federal Reserve Bank is closed on the holidays outlined in https://www.federalreserve.gov/aboutthefed/k8.htm.
+ * If a holiday falls on a Sunday, it's observed the following Monday.
+ * This function calculates all the US Federal Reserve Bank holidays for a given year.
+ *
+ * @param year - the year for which US Federal Bank Holidays should be calculated for
+ * @returns list of holiday name and actual or observed date of US Federal Reserve Bank holidays for the given year
+ */
+export default function (year: number): FederalReserveBankHoliday[] {
+  const newYearsDay =
+    new Date(year, MONTH_JANUARY, DATE_ONE).getUTCDay() === DAY_OF_THE_WEEK_SUNDAY
+      ? {
+          name: `New Year's Day`,
+          date: formatUtc(new Date(year, MONTH_JANUARY, DATE_ONE), YYYY_MM_DD_FORMAT),
+          observedOn: formatUtc(new Date(year, MONTH_JANUARY, DATE_TWO), YYYY_MM_DD_FORMAT),
+        }
+      : {
+          name: `New Year's Day`,
+          date: formatUtc(new Date(year, MONTH_JANUARY, DATE_ONE), YYYY_MM_DD_FORMAT),
+        };
+
+  const martinLutherKingJrDay = {
+    name: 'Birthday of Martin Luther King, Jr.',
+    date: getNthOccurrenceOfDayOfTheWeekInMonth(OCCURRENCE_THIRD, DAY_OF_THE_WEEK_MONDAY, MONTH_JANUARY, year), // Birthday of Martin Luther King, Jr. is the Third Monday of January
+  };
+
+  const washingtonsBirthday = {
+    name: `Washington's Birthday`,
+    date: getNthOccurrenceOfDayOfTheWeekInMonth(OCCURRENCE_THIRD, DAY_OF_THE_WEEK_MONDAY, MONTH_FEBRUARY, year), // Washington's Birthday is the Third Monday of February
+  };
+
+  const memorialDay = {
+    name: 'Memorial Day',
+    date: getLastMondayOfMay(year), // Memorial Day is the Last Monday of May
+  };
+
+  const juneteenth =
+    new Date(year, MONTH_JUNE, DATE_NINETEEN).getUTCDay() === DAY_OF_THE_WEEK_SUNDAY
+      ? {
+          name: 'Juneteenth National Independence Day',
+          date: formatUtc(new Date(year, MONTH_JUNE, DATE_NINETEEN), YYYY_MM_DD_FORMAT),
+          observedOn: formatUtc(new Date(year, MONTH_JUNE, DATE_TWENTY), YYYY_MM_DD_FORMAT),
+        }
+      : {
+          name: 'Juneteenth National Independence Day',
+          date: formatUtc(new Date(year, MONTH_JUNE, DATE_NINETEEN), YYYY_MM_DD_FORMAT),
+        };
+
+  const independenceDay =
+    new Date(year, MONTH_JULY, DATE_FOUR).getUTCDay() === DAY_OF_THE_WEEK_SUNDAY
+      ? {
+          name: 'Independence Day',
+          date: formatUtc(new Date(year, MONTH_JULY, DATE_FOUR), YYYY_MM_DD_FORMAT),
+          observedOn: formatUtc(new Date(year, MONTH_JULY, DATE_FIVE), YYYY_MM_DD_FORMAT),
+        }
+      : {
+          name: 'Independence Day',
+          date: formatUtc(new Date(year, MONTH_JULY, DATE_FOUR), YYYY_MM_DD_FORMAT),
+        };
+
+  const laborDay = {
+    name: 'Labor Day',
+    date: getNthOccurrenceOfDayOfTheWeekInMonth(OCCURRENCE_FIRST, DAY_OF_THE_WEEK_MONDAY, MONTH_SEPTEMBER, year), // Labor Day is the First Monday of September
+  };
+
+  const columbusDay = {
+    name: 'Columbus Day',
+    date: getNthOccurrenceOfDayOfTheWeekInMonth(OCCURRENCE_SECOND, DAY_OF_THE_WEEK_MONDAY, MONTH_OCTOBER, year), // Columbus Day is the Second Monday of October
+  };
+
+  const veteransDay =
+    new Date(year, MONTH_NOVEMBER, DATE_ELEVEN).getUTCDay() === DAY_OF_THE_WEEK_SUNDAY
+      ? {
+          name: 'Veterans Day',
+          date: formatUtc(new Date(year, MONTH_NOVEMBER, DATE_ELEVEN), YYYY_MM_DD_FORMAT),
+          observedOn: formatUtc(new Date(year, MONTH_NOVEMBER, DATE_TWELVE), YYYY_MM_DD_FORMAT),
+        }
+      : {
+          name: 'Veterans Day',
+          date: formatUtc(new Date(year, MONTH_NOVEMBER, DATE_ELEVEN), YYYY_MM_DD_FORMAT),
+        };
+
+  const thanksGivingDay = {
+    name: 'Thanksgiving Day',
+    date: getNthOccurrenceOfDayOfTheWeekInMonth(OCCURRENCE_FOURTH, DAY_OF_THE_WEEK_THURSDAY, MONTH_NOVEMBER, year), // Thanksgiving Day is the Fourth Thursday of November
+  };
+
+  const christmasDay =
+    new Date(year, MONTH_DECEMBER, DATE_TWENTY_FIVE).getUTCDay() === DAY_OF_THE_WEEK_SUNDAY
+      ? {
+          name: 'Christmas Day',
+          date: formatUtc(new Date(year, MONTH_DECEMBER, DATE_TWENTY_FIVE), YYYY_MM_DD_FORMAT),
+          observedOn: formatUtc(new Date(year, MONTH_DECEMBER, DATE_TWENTY_SIX), YYYY_MM_DD_FORMAT),
+        }
+      : {
+          name: 'Christmas Day',
+          date: formatUtc(new Date(year, MONTH_DECEMBER, DATE_TWENTY_FIVE), YYYY_MM_DD_FORMAT),
+        };
+
+  return year >= YEAR2021
+    ? [
+        newYearsDay,
+        martinLutherKingJrDay,
+        washingtonsBirthday,
+        memorialDay,
+        juneteenth,
+        independenceDay,
+        laborDay,
+        columbusDay,
+        veteransDay,
+        thanksGivingDay,
+        christmasDay,
+      ]
+    : [
+        newYearsDay,
+        martinLutherKingJrDay,
+        washingtonsBirthday,
+        memorialDay,
+        independenceDay,
+        laborDay,
+        columbusDay,
+        veteransDay,
+        thanksGivingDay,
+        christmasDay,
+      ];
+}

package/src/holidays/united-states/federal-reserve-bank/index.ts

@@ -0,0 +1,6 @@
+// holidays/united-states/federal-reserve-bank/index.ts
+
+export { default as addUSFederalReserveBankBusinessDays } from './add-us-federal-reserve-bank-business-days';
+export { default as getAllUSFederalReserveBankHolidays } from './get-all-us-federal-reserve-bank-holidays';
+export { default as isUSFederalReserveBankClosed } from './is-us-federal-reserve-bank-closed';
+export { type PlainDate } from './plain-date';

package/src/holidays/united-states/federal-reserve-bank/is-us-federal-reserve-bank-closed.ts

@@ -0,0 +1,36 @@
+// holidays/united-states/federal-reserve-bank/is-us-federal-reserve-bank-closed.ts
+
+import { formatUtc } from '../../../index';
+
+import { getAllUSFederalReserveBankHolidays, PlainDate } from './index';
+
+const DAY_OF_THE_WEEK_SUNDAY = 0;
+const DAY_OF_THE_WEEK_SATURDAY = 6;
+
+/**
+ * @name isUSFederalReserveBankClosed
+ * @summary Is the US Federal Reserve Bank Closed?
+ *
+ * @description
+ * US Federal Reserve Bank is closed on United States weekends and holidays outlined in
+ * https://www.federalreserve.gov/aboutthefed/k8.htm. This function checks if the US Federal Reserve Bank is closed
+ * on a given date.
+ *
+ * @param plainDate - the date to be checked
+ * @returns boolean indicating if the US Federal Reserve Bank is closed on a given date
+ */
+export default function (plainDate: PlainDate): boolean {
+  const date = new Date(plainDate.year, plainDate.month, plainDate.date);
+  const year = date.getUTCFullYear();
+  const day = date.getUTCDay();
+  const formattedDate = formatUtc(date, 'yyyy-MM-dd');
+  const allUSFederalReserveBankHolidays = getAllUSFederalReserveBankHolidays(year);
+
+  return (
+    day === DAY_OF_THE_WEEK_SATURDAY ||
+    day === DAY_OF_THE_WEEK_SUNDAY ||
+    allUSFederalReserveBankHolidays.some(
+      (holiday) => holiday.date === formattedDate || holiday.observedOn === formattedDate,
+    )
+  );
+}

package/src/holidays/united-states/federal-reserve-bank/plain-date.ts

@@ -0,0 +1,7 @@
+// holidays/united-states/federal-reserve-bank/plain-date.ts
+
+export interface PlainDate {
+  year: number;
+  month: number;
+  date: number;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// index.ts
+
+export * as Temporal from './temporal';
+
+// export all date-fns functions
+export * from './date-fns';
+
+// export all date-fns-tz functions
+export * from './date-fns-tz';
+
+// export local date-fns-tz helper functions
+export { default as formatUtc } from './format-utc';
+
+// export all holidays functions
+export * from './holidays';

package/src/instant.ts

@@ -0,0 +1,129 @@
+// instant.ts
+
+export type ComparisonResult = -1 | 0 | 1;
+
+const YEAR_DIGITS = 4;
+
+const THOUSAND_DIGITS = 3;
+const MILLION_DIGITS = 6;
+const BILLION_DIGITS = 9;
+
+const THOUSAND = 10 ** THOUSAND_DIGITS;
+const MILLION = 10 ** MILLION_DIGITS;
+const BILLION = 10 ** BILLION_DIGITS;
+
+const extraRegEx = /\.\d\d\d(?<extra>\d+)Z$/u;
+
+/**
+ * Partial implementation of Temporal.Instant, part of the new TC39 Temporal proposal.
+ *
+ * See docs here: https://tc39.es/proposal-temporal/docs/instant.html
+ */
+export class Instant {
+  constructor(private readonly nanoseconds: bigint) {}
+
+  static fromEpochSeconds(epochSeconds: number): Instant {
+    return new Instant(BigInt(epochSeconds) * BigInt(BILLION));
+  }
+
+  static fromEpochMilliseconds(epochMilliseconds: number): Instant {
+    return new Instant(BigInt(BigInt(epochMilliseconds) * BigInt(MILLION)));
+  }
+
+  static fromEpochMicroseconds(epochMicroseconds: bigint): Instant {
+    return new Instant(BigInt(BigInt(epochMicroseconds) * BigInt(THOUSAND)));
+  }
+
+  static fromEpochNanoseconds(epochNanoseconds: bigint): Instant {
+    return new Instant(epochNanoseconds);
+  }
+
+  static from(item: Instant | string): Instant {
+    if (item instanceof Instant) {
+      return item;
+    }
+    const extra = extraRegEx.exec(item)?.groups?.['extra'] ?? '';
+    const extraDigits = BigInt(extra) * BigInt(10 ** (MILLION_DIGITS - extra.length));
+    const nanoseconds = BigInt(new Date(item).getTime()) * BigInt(MILLION) + extraDigits;
+    return new Instant(nanoseconds);
+  }
+
+  static compare(one: { epochNanoseconds: bigint }, two: { epochNanoseconds: bigint }): ComparisonResult {
+    if (one.epochNanoseconds > two.epochNanoseconds) {
+      return 1;
+    }
+    if (one.epochNanoseconds < two.epochNanoseconds) {
+      return -1;
+    }
+    return 0;
+  }
+
+  get epochSeconds(): number {
+    if (this.nanoseconds < 0 && this.nanoseconds % BigInt(BILLION) !== 0n) {
+      return Number(this.nanoseconds / BigInt(BILLION)) - 1;
+    }
+    return Number(this.nanoseconds / BigInt(BILLION));
+  }
+
+  get epochMilliseconds(): number {
+    if (this.nanoseconds < 0 && this.nanoseconds % BigInt(MILLION) !== 0n) {
+      return Number(this.nanoseconds / BigInt(MILLION)) - 1;
+    }
+    return Number(this.nanoseconds / BigInt(MILLION));
+  }
+
+  get epochMicroseconds(): bigint {
+    if (this.nanoseconds < 0 && this.nanoseconds % BigInt(THOUSAND) !== 0n) {
+      return this.nanoseconds / BigInt(THOUSAND) - 1n;
+    }
+    return this.nanoseconds / BigInt(THOUSAND);
+  }
+
+  get epochNanoseconds(): bigint {
+    return this.nanoseconds;
+  }
+
+  equals(this: Instant, other: Instant): boolean {
+    return this.nanoseconds === other.epochNanoseconds;
+  }
+
+  toString(this: Instant): string {
+    let nanoseconds = Number(this.nanoseconds % BigInt(BILLION));
+    const epochMilliseconds =
+      Number((this.nanoseconds / BigInt(BILLION)) * BigInt(THOUSAND)) + Math.floor(Number(nanoseconds / MILLION));
+    nanoseconds = Number((this.nanoseconds < BigInt(0) ? BILLION : 0) + nanoseconds);
+    const millisecond = Math.floor(nanoseconds / MILLION) % THOUSAND;
+    const microsecond = Math.floor(nanoseconds / THOUSAND) % THOUSAND;
+    const nanosecond = Math.floor(nanoseconds) % THOUSAND;
+
+    const item = new Date(epochMilliseconds);
+    const year = item.getUTCFullYear();
+    const month = item.getUTCMonth() + 1;
+    const day = item.getUTCDate();
+    const hour = item.getUTCHours();
+    const minute = item.getUTCMinutes();
+    const second = item.getUTCSeconds();
+
+    let fraction = `${millisecond * MILLION + microsecond * THOUSAND + nanosecond}`.padStart(BILLION_DIGITS, '0');
+    while (fraction.endsWith('0')) {
+      fraction = fraction.slice(0, -1);
+    }
+    if (fraction.length > 0) {
+      fraction = `.${fraction}`;
+    }
+    return `${year.toString().padStart(YEAR_DIGITS, '0')}-${month.toString().padStart(2, '0')}-${day
+      .toString()
+      .padStart(2, '0')}T${hour.toString().padStart(2, '0')}:${minute.toString().padStart(2, '0')}:${second
+      .toString()
+      .padStart(2, '0')}${fraction}Z`;
+  }
+
+  toJSON(this: Instant): string {
+    return this.toString();
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  valueOf(): never {
+    throw new TypeError('use compare() or equals() to compare Temporal.Instant');
+  }
+}

package/src/now.ts

@@ -0,0 +1,46 @@
+// now.ts
+
+import { Instant } from './instant';
+
+/**
+ * Partial implementation of Temporal.now, part of the new TC39 Temporal proposal.  Currently only instant() is
+ * supported.
+ *
+ * See docs here: https://tc39.es/proposal-temporal/docs/now.html
+ */
+
+const MILLION = 1e6;
+
+let baseDateTime = BigInt(Date.now());
+let baseHighResolutionTime = process.hrtime.bigint();
+let priorEpochNanoseconds = BigInt(0);
+
+/**
+ * This returns ever-increasing millisecond-accurate current time values in nanosecond form.
+ *
+ * To simulate nanosecond current time, we take the millisecond based clock and supplement with the HR timer.
+ * Two invocations within the same millisecond will have an accurate nanosecond difference between them, so
+ * this is useful for ensuring unique timestamps in webservices where concurrent execution may be an issue.
+ */
+export function instant(): Instant {
+  const dateTime = BigInt(Date.now());
+
+  if (dateTime > baseDateTime) {
+    // We're in a new millisecond, so reset the base HR time.
+    // This makes sure we're always returning a value that is consistent with the built-in millisecond clock.
+    baseHighResolutionTime = process.hrtime.bigint();
+    baseDateTime = dateTime;
+  }
+
+  let epochNanoseconds =
+    dateTime * BigInt(MILLION) + ((process.hrtime.bigint() - baseHighResolutionTime) % BigInt(MILLION));
+
+  if (epochNanoseconds < priorEpochNanoseconds) {
+    // the HR offset has overflowed, so reset the base HR time
+    baseHighResolutionTime = process.hrtime.bigint();
+    epochNanoseconds = priorEpochNanoseconds + ((process.hrtime.bigint() - baseHighResolutionTime) % BigInt(MILLION));
+  }
+
+  priorEpochNanoseconds = epochNanoseconds;
+  return new Instant(epochNanoseconds);
+}

package/src/temporal.ts

@@ -0,0 +1,4 @@
+// temporal.ts
+
+export * from './instant';
+export * as Now from './now';

package/dist/date-fns-tz.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/date-fns.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/format-utc.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/holidays/united-states/federal-reserve-bank/add-us-federal-reserve-bank-business-days.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/holidays/united-states/federal-reserve-bank/get-all-us-federal-reserve-bank-holidays.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/holidays/united-states/federal-reserve-bank/index.d.ts

@@ -1,4 +0,0 @@
-export { default as addUSFederalReserveBankBusinessDays } from './add-us-federal-reserve-bank-business-days';
-export { default as getAllUSFederalReserveBankHolidays } from './get-all-us-federal-reserve-bank-holidays';
-export { default as isUSFederalReserveBankClosed } from './is-us-federal-reserve-bank-closed';
-export { PlainDate } from './plain-date';

package/dist/holidays/united-states/federal-reserve-bank/is-us-federal-reserve-bank-closed.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/holidays/united-states/federal-reserve-bank/plain-date.d.ts

@@ -1,5 +0,0 @@
-export type PlainDate = {
-    year: number;
-    month: number;
-    date: number;
-};

package/dist/holidays/united-states/federal-reserve-bank/subtract-us-federal-reserve-bank-business-days.spec.d.ts

@@ -1 +0,0 @@
-export {};