499/get holiday (#500)

* refactor(#499): use valueAsDate for isHoliday

* feat(#499): add getHoliday helper

* docs(#499): update readme

* test(#499): add timezones checks

Author: MauricioRobayo

README.md

@@ -245,7 +245,7 @@ Returns `true` if the given date is a colombian holiday, otherwise returns `fals
 ```js
 import { isHoliday } from "colombian-holidays/lib/utils/isHoliday";
 
-const date = new Date("2018-01-01T05:00:00.000Z");
+const date = new Date("2018-01-01");
 
 if (isHoliday(date)) {
   console.log("it is a colombian holiday");
@@ -254,6 +254,32 @@ if (isHoliday(date)) {
 }
 ```
 
+### getHoliday
+
+Similar to `isHoliday` but will return the corresponding holiday for a given date or `null` if there is no matching holiday.
+
+```js
+import { getHoliday } from "colombian-holidays/lib/utils/getHoliday";
+
+const date = new Date("2018-01-01");
+
+const newYear = getHoliday(date);
+/*
+  {
+    celebrationDate: "2018-01-01",
+    date: "2018-01-01",
+    name: { en: "New Year's Day", es: "Año Nuevo" },
+    nextMonday: false,
+  }
+*/
+```
+
+To get the values as date use the options argument:
+
+```js
+const newYearAsDate = getHoliday(date, { valueAsDate: true });
+```
+
 ### holidaysWithinInterval
 
 Returns an array with the colombian holidays within two dates:
@@ -264,6 +290,7 @@ import { holidaysWithinInterval } from "colombian-holidays/lib/utils/holidaysWit
 const start = new Date("2021-01-01");
 const end = new Date("2021-01-11");
 const holidays = holidaysWithinInterval({ start, end });
+// const holidays = holidaysWithinInterval({ start, end, valueAsDate: true });
 ```
 
 returns:

src/helpers.ts

@@ -51,7 +51,7 @@ function generateUtcStringFromDateParts(
   )}`;
 }
 
-function generateUtcStringFromDate(date: Date): string {
+export function generateUtcStringFromDate(date: Date): string {
   return generateUtcStringFromDateParts(
     date.getUTCFullYear(),
     date.getUTCMonth() + 1,

src/utils/getHoliday.test.ts

@@ -0,0 +1,49 @@
+import timezone_mock, { TimeZone } from "timezone-mock";
+import { getHoliday } from "./getHoliday";
+
+const timezones: TimeZone[] = [
+  "US/Pacific",
+  "US/Eastern",
+  "Brazil/East",
+  "UTC",
+  "Europe/London",
+  "Australia/Adelaide",
+];
+
+afterEach(() => {
+  timezone_mock.unregister();
+});
+
+describe("test getHoliday", () => {
+  describe.each(timezones)("%p", (timezone) => {
+    timezone_mock.register(timezone);
+
+    it(`should return holiday for a holiday date object`, () => {
+      const expectedHoliday = {
+        celebrationDate: "2018-01-01",
+        date: "2018-01-01",
+        name: { en: "New Year's Day", es: "Año Nuevo" },
+        nextMonday: false,
+      };
+      const holiday = getHoliday(new Date("2018-01-01"));
+      expect(holiday).toEqual(expectedHoliday);
+    });
+
+    it(`should return holiday with values as dates for a holiday date object`, () => {
+      const expectedHoliday = {
+        celebrationDate: new Date("2018-01-01T00:00:00.000Z"),
+        date: new Date("2018-01-01T00:00:00.000Z"),
+        name: { en: "New Year's Day", es: "Año Nuevo" },
+        nextMonday: false,
+      };
+      const holiday = getHoliday(new Date("2018-01-01"), {
+        valueAsDate: true,
+      });
+      expect(holiday).toEqual(expectedHoliday);
+    });
+  });
+
+  it(`should return false for a non holiday date object`, () => {
+    expect(getHoliday(new Date("2018-01-02T05:00:00.000Z"))).toBe(null);
+  });
+});

src/utils/getHoliday.ts

@@ -0,0 +1,35 @@
+import colombianHolidays from "..";
+import { generateUtcStringFromDate } from "../helpers";
+import { ColombianHoliday, ColombianHolidayWithNativeDate } from "../types";
+import { isSameDate } from "./helpers";
+
+export function getHoliday(
+  date: Date,
+  options: { valueAsDate: true }
+): ColombianHolidayWithNativeDate;
+export function getHoliday(
+  date: Date,
+  options?: undefined | { valueAsDate: false }
+): ColombianHoliday;
+export function getHoliday(
+  date: Date,
+  options: { valueAsDate: boolean } = { valueAsDate: false }
+): ColombianHoliday | ColombianHolidayWithNativeDate | null {
+  const { valueAsDate } = options;
+  const holiday = colombianHolidays({
+    year: date.getUTCFullYear(),
+    valueAsDate: true,
+  }).find(({ celebrationDate }) => isSameDate(celebrationDate, date));
+  if (!holiday) {
+    return null;
+  }
+
+  if (valueAsDate) {
+    return holiday;
+  }
+  return {
+    ...holiday,
+    date: generateUtcStringFromDate(holiday.date),
+    celebrationDate: generateUtcStringFromDate(holiday.celebrationDate),
+  };
+}

src/utils/helpers.ts

@@ -0,0 +1,7 @@
+export function isSameDate(date1: Date, date2: Date): boolean {
+  return (
+    date1.getUTCDate() === date2.getUTCDate() &&
+    date1.getUTCMonth() === date2.getUTCMonth() &&
+    date1.getUTCFullYear() === date2.getUTCFullYear()
+  );
+}

src/utils/isHoliday.test.ts

@@ -1,10 +1,29 @@
+import timezone_mock, { TimeZone } from "timezone-mock";
 import { isHoliday } from "./isHoliday";
 
+const timezones: TimeZone[] = [
+  "US/Pacific",
+  "US/Eastern",
+  "Brazil/East",
+  "UTC",
+  "Europe/London",
+  "Australia/Adelaide",
+];
+
+afterEach(() => {
+  timezone_mock.unregister();
+});
+
 describe("test isHoliday", () => {
-  it(`should return true for a holiday date object`, () => {
-    expect(isHoliday(new Date("2018-01-01T05:00:00.000Z"))).toBe(true);
-  });
-  it(`should return false for a non holiday date object`, () => {
-    expect(isHoliday(new Date("2018-01-02T05:00:00.000Z"))).toBe(false);
+  describe.each(timezones)("%p", (timezone) => {
+    timezone_mock.register(timezone);
+
+    it(`should return true for a holiday date object`, () => {
+      expect(isHoliday(new Date("2018-01-01"))).toBe(true);
+    });
+
+    it(`should return false for a non holiday date object`, () => {
+      expect(isHoliday(new Date("2018-01-02"))).toBe(false);
+    });
   });
 });

src/utils/isHoliday.ts

@@ -1,14 +1,9 @@
 import colombianHolidays from "..";
+import { isSameDate } from "./helpers";
 
 export function isHoliday(date: Date): boolean {
-  return colombianHolidays({ year: date.getUTCFullYear() }).some(
-    ({ celebrationDate }) => {
-      const d = new Date(celebrationDate);
-      return (
-        d.getUTCDate() === date.getUTCDate() &&
-        d.getUTCMonth() === date.getUTCMonth() &&
-        d.getUTCFullYear() === date.getUTCFullYear()
-      );
-    }
-  );
+  return colombianHolidays({
+    year: date.getUTCFullYear(),
+    valueAsDate: true,
+  }).some(({ celebrationDate }) => isSameDate(celebrationDate, date));
 }