Add getFirstDayOfYear function (#63)

Author: neolusc

CHANGELOG.md

@@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Unnecessary dev-dependencies
 
+### Added
+
+- `getFirstDayOfYear` date utility function
+
 ## [1.2.2] - 2025-04-04
 
 ### Changed

src/lib/date.spec.ts

@@ -8,6 +8,7 @@ import {
   getNextBusinessDate,
   getStartOfDay,
   getEndOfDay,
+  getFirstDayOfYear,
   getLastDayOfYear,
 } from "./date";
 
@@ -132,6 +133,21 @@ describe("date tests", () => {
     expect(getEndOfDay(date).getTime()).toBe(expected.getTime());
   });
 
+  test.each([
+    [null as unknown as Date, new Date(Number.NaN)],
+    [undefined as unknown as Date, new Date(Number.NaN)],
+    [42 as unknown as Date, new Date(Number.NaN)],
+    ["test" as unknown as Date, new Date(Number.NaN)],
+  ])("getFirstDayOfYear", (date, expected) => {
+    expect(getFirstDayOfYear(date).getTime()).toBe(expected.getTime());
+  });
+
+  test("getFirstDayOfYear all days", () => {
+    for (let date = new Date(2024, 0, 1); date < new Date(2025, 0, 1); date.setDate(date.getDate() + 1)) {
+      expect(getFirstDayOfYear(date).getTime()).toBe(new Date(2024, 0, 1, 0, 0, 0, 0).getTime());
+    }
+  });
+
   test.each([
     [null as unknown as Date, new Date(Number.NaN)],
     [undefined as unknown as Date, new Date(Number.NaN)],

src/lib/date.ts

@@ -95,6 +95,15 @@ export function getEndOfDay(date: Date): Date {
   return dateIsValid(date) ? endOfDay(date) : new Date(Number.NaN);
 }
 
+/**
+ * Get the first day of a year for the given date
+ * @param date The date
+ * @returns The first day of the date year
+ */
+export function getFirstDayOfYear(date: Date): Date {
+  return dateIsValid(date) ? new Date(date.getFullYear(), 0, 1) : new Date(Number.NaN);
+}
+
 /**
  * Get the last day of a year for the given date
  * @param date The date