feat: optional date arguments for functions (#58)

* isAfter, isBefore and diffMilliseconds now accept null/undefined to allow comparison with `now`

* isBefore & isAfter doc change from now -> the current time
changed isEqual to accept 1 optional date

* all diff* functions now accept optional date arguments

* all add* functions now support optional date argument.
tests for them are combined with the ones for diff

* same* now also support optional date arguments

* nearestDay now accepts optional date input

* *end, *start, yearDays, monthDays & dayOfYear now support optional date input

* offset, removeOffset, tzDate, fill & createPartMap now support optional date input
added 'the' before current * were missing

* added isFuture & isPast

* fix sameSecond inputDateA to Maybe

* yearStart inputDate to maybe type

* export isFuture & isPast

* jsdoc change for MaybeDateInput to use `current time` instead of `now`

Author: WilcoSp

.prettierrc

@@ -1,5 +1,7 @@
 {
   "tabWidth": 2,
   "useTabs": false,
-  "semi": false
+  "semi": false,
+  "printWidth": 90,
+  "trailingComma": "es5"
 }

src/__tests__/addDay.spec.ts

@@ -14,4 +14,6 @@ describe("addDay", () => {
   it("gets the next day by providing specified negative number of days", () => {
     expect(addDay("2022-01-01", -5).toISOString()).toBe("2021-12-27T05:00:00.000Z")
   })
+
+  // test with the current time is at diffDays
 })

src/__tests__/addHour.spec.ts

@@ -4,9 +4,7 @@ process.env.TZ = "America/New_York"
 
 describe("addHour", () => {
   it("can increment a normal hour", () => {
-    expect(addHour("2022-01-01T00:00:00Z").toISOString()).toBe(
-      "2022-01-01T01:00:00.000Z"
-    )
+    expect(addHour("2022-01-01T00:00:00Z").toISOString()).toBe("2022-01-01T01:00:00.000Z")
   })
   it("can increment the last hours of the day into a new day", () => {
     expect(addHour("2022-01-01T23:11:00Z", 3).toISOString()).toBe(
@@ -18,4 +16,6 @@ describe("addHour", () => {
       "2021-12-31T19:11:00.000Z"
     )
   })
+
+  // test with the current time is at diffHours.
 })

src/__tests__/addMinute.spec.ts

@@ -18,4 +18,6 @@ describe("addMinute", () => {
       "2021-12-31T23:10:00.000Z"
     )
   })
+
+  // test with the current time is at diffMinutes.
 })

src/__tests__/addMonth.spec.ts

@@ -4,45 +4,35 @@ process.env.TZ = "America/New_York"
 
 describe("addMonth", () => {
   it("gets the next month on the first", () => {
-    expect(addMonth("2022-01-01").toISOString()).toBe(
-      "2022-02-01T05:00:00.000Z"
-    )
+    expect(addMonth("2022-01-01").toISOString()).toBe("2022-02-01T05:00:00.000Z")
   })
   it("can overflow a month month when the next month has fewer days", () => {
-    expect(addMonth("2000-01-31", 1, true).toISOString()).toBe(
-      "2000-03-02T05:00:00.000Z"
-    )
+    expect(addMonth("2000-01-31", 1, true).toISOString()).toBe("2000-03-02T05:00:00.000Z")
   })
   it("goe to the same day of the month on the next month", () => {
-    expect(addMonth("2000-06-04").toISOString()).toBe(
-      "2000-07-04T04:00:00.000Z"
-    )
+    expect(addMonth("2000-06-04").toISOString()).toBe("2000-07-04T04:00:00.000Z")
   })
 
   it("can add multiple months by passing a second argument", () => {
-    expect(addMonth("2000-01-01", 2).toISOString()).toBe(
-      "2000-03-01T05:00:00.000Z"
-    )
+    expect(addMonth("2000-01-01", 2).toISOString()).toBe("2000-03-01T05:00:00.000Z")
   })
 
   it("can add years months by passing a second argument", () => {
-    expect(addMonth("2000-01-01", 25).toISOString()).toBe(
-      "2002-02-01T05:00:00.000Z"
-    )
+    expect(addMonth("2000-01-01", 25).toISOString()).toBe("2002-02-01T05:00:00.000Z")
   })
   it("can prevent month overflow with third argument", () => {
     expect(addMonth("2020-01-31", 1, false).toISOString()).toBe(
       "2020-02-29T05:00:00.000Z"
     )
   })
   it("can subtract multiple months", () => {
-    expect(addMonth("2020-01-31", -2).toISOString()).toBe(
-      "2019-11-30T05:00:00.000Z"
-    )
+    expect(addMonth("2020-01-31", -2).toISOString()).toBe("2019-11-30T05:00:00.000Z")
   })
   it("can subtract multiple months and allow overflow", () => {
     expect(addMonth("2020-01-31", -2, true).toISOString()).toBe(
       "2019-12-01T05:00:00.000Z"
     )
   })
+
+  // test with the current time is at diffMonths.
 })

src/__tests__/addSecond.spec.ts

@@ -18,4 +18,6 @@ describe("addSecond", () => {
       "2021-12-31T23:59:30.000Z"
     )
   })
+
+  // test with the current time is at diffSeconds.
 })

src/__tests__/addYear.spec.ts

@@ -16,4 +16,6 @@ describe("addYear", () => {
   it("can overflow the day of the month on leap year", () => {
     expect(addYear("2000-02-29").toISOString()).toBe("2001-02-28T05:00:00.000Z")
   })
+
+  // test with the current time is at diffYears
 })

src/__tests__/dayEnd.spec.ts

@@ -4,8 +4,11 @@ process.env.TZ = "America/New_York"
 
 describe("dayEnd", () => {
   it("can become the end of the day", () => {
-    expect(dayEnd("2023-02-22T12:00:00Z").toISOString()).toBe(
-      "2023-02-23T04:59:59.999Z"
-    )
+    expect(dayEnd("2023-02-22T12:00:00Z").toISOString()).toBe("2023-02-23T04:59:59.999Z")
+  })
+  it("can become the end of the current day", () => {
+    const compare = new Date()
+    compare.setHours(23, 59, 59, 999)
+    expect(dayEnd()).toEqual(compare)
   })
 })

src/__tests__/dayOfYear.spec.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from "vitest"
 import { dayOfYear } from "../dayOfYear"
+import { yearStart } from "../yearStart"
+import { diffDays } from "../diffDays"
 process.env.TZ = "America/New_York"
 
 describe("dayOfYear", () => {
@@ -9,4 +11,9 @@ describe("dayOfYear", () => {
   it("can find the number of days in a year", () => {
     expect(dayOfYear("2020-08-01")).toBe(214)
   })
+
+  it("can find the number of days of the current day", () => {
+    const start = yearStart()
+    expect(dayOfYear()).toBe(diffDays(null, start) + 1)
+  })
 })

src/__tests__/dayStart.spec.ts

@@ -8,4 +8,10 @@ describe("dayStart", () => {
       "2023-02-22T05:00:00.000Z"
     )
   })
+
+  it("gets the start of the day", () => {
+    const compare = new Date()
+    compare.setHours(0, 0, 0, 0)
+    expect(dayStart()).toEqual(compare)
+  })
 })

src/__tests__/diffDays.spec.ts

@@ -1,20 +1,24 @@
 import { describe, expect, it } from "vitest"
 import { diffDays } from "../diffDays"
+import { addDay } from "../addDay"
 
 describe("differenceInDays", () => {
   it("difference is 3 days", () => {
     expect(diffDays("2024-04-10", "2024-04-07")).toBe(3)
   })
 
   it("difference is 2 days", () => {
-    expect(
-      diffDays("2024-04-10T09:50:00.000Z", "2024-04-07T15:28:00.000Z")
-    ).toBe(2)
+    expect(diffDays("2024-04-10T09:50:00.000Z", "2024-04-07T15:28:00.000Z")).toBe(2)
   })
 
   it("difference is 3 days by using round", () => {
     expect(
       diffDays("2024-04-10T09:50:00.000Z", "2024-04-07T15:28:00.000Z", "round")
     ).toBe(3)
   })
+
+  it("different should be -64 hours compared to the current time", () => {
+    const compare = addDay(null, -28)
+    expect(diffDays(compare)).toBe(-28)
+  })
 })

src/__tests__/diffHours.spec.ts

@@ -1,10 +1,14 @@
 import { describe, expect, it } from "vitest"
 import { diffHours } from "../diffHours"
+import { addHour } from "../addHour"
 
 describe("differenceInHours", () => {
   it("difference is 5 hours", () => {
-    expect(
-      diffHours("2024-04-07T15:28:00.000Z", "2024-04-07T09:50:00.000Z")
-    ).toBe(5)
+    expect(diffHours("2024-04-07T15:28:00.000Z", "2024-04-07T09:50:00.000Z")).toBe(5)
+  })
+
+  it("different should be -64 hours compared to the current time", () => {
+    const compare = addHour(null, 64)
+    expect(diffHours(null, compare)).toBe(-64)
   })
 })

src/__tests__/diffMilliseconds.spec.ts

@@ -1,10 +1,22 @@
 import { describe, it, expect } from "vitest"
 import { diffMilliseconds } from "../diffMilliseconds"
 
-describe("differenceInMilliseconds", () => {
+describe("diffMilliseconds", () => {
   it("difference is 257 milliseconds", () => {
-    expect(
-      diffMilliseconds("2024-04-07T09:10:48.257Z", "2024-04-07T09:10:48.000Z")
-    ).toBe(257)
+    expect(diffMilliseconds("2024-04-07T09:10:48.257Z", "2024-04-07T09:10:48.000Z")).toBe(
+      257
+    )
+  })
+
+  it("should be 5000 milleseconds difference compared to the current time", () => {
+    const now = new Date()
+    now.setMilliseconds(5000) // because the date function sets ms to 0, the test needs to test with increments of 1000
+    expect(diffMilliseconds(now)).toBe(5000)
+  })
+
+  it("should be -5000 milleseconds difference compared to the current time", () => {
+    const now = new Date()
+    now.setMilliseconds(5000)
+    expect(diffMilliseconds(null, now)).toBe(-5000)
   })
 })

src/__tests__/diffMinutes.spec.ts

@@ -1,19 +1,19 @@
 import { describe, it, expect } from "vitest"
 import { diffMinutes } from "../diffMinutes"
+import { addMinute } from "../addMinute"
 
 describe("differenceInMinutes", () => {
   it("difference is 18 minutes", () => {
-    expect(
-      diffMinutes("2024-04-07T09:28:30.050Z", "2024-04-07T09:10:00.000Z")
-    ).toBe(18)
+    expect(diffMinutes("2024-04-07T09:28:30.050Z", "2024-04-07T09:10:00.000Z")).toBe(18)
   })
   it("difference is 19 minutes by using ceil", () => {
     expect(
-      diffMinutes(
-        "2024-04-07T09:28:01.050Z",
-        "2024-04-07T09:10:00.000Z",
-        "ceil"
-      )
+      diffMinutes("2024-04-07T09:28:01.050Z", "2024-04-07T09:10:00.000Z", "ceil")
     ).toBe(19)
   })
+
+  it("different should be 23 minutes compared to the current time", () => {
+    const compare = addMinute(null, 23)
+    expect(diffMinutes(compare)).toBe(23)
+  })
 })

src/__tests__/diffMonths.spec.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest"
 import { diffMonths } from "../diffMonths"
+import { addMonth } from "../addMonth"
 
 describe("differenceInMonths", () => {
   it("should give 11 months", () => {
@@ -29,4 +30,9 @@ describe("differenceInMonths", () => {
   it("should also be a negative full month when swapped", () => {
     expect(diffMonths("2024-01-31", "2024-02-29")).toBe(-1)
   })
+
+  it("different should be 3 month compared to the current time", () => {
+    const compare = addMonth(null, 3)
+    expect(diffMonths(compare)).toBe(3)
+  })
 })

src/__tests__/diffSeconds.spec.ts

@@ -1,10 +1,14 @@
 import { describe, it, expect } from "vitest"
 import { diffSeconds } from "../diffSeconds"
+import { addSecond } from "../addSecond"
 
 describe("differenceInSeconds", () => {
   it("difference is 28 seconds", () => {
-    expect(
-      diffSeconds("2024-04-07T09:10:28.900Z", "2024-04-07T09:10:00.000Z")
-    ).toBe(28)
+    expect(diffSeconds("2024-04-07T09:10:28.900Z", "2024-04-07T09:10:00.000Z")).toBe(28)
+  })
+
+  it("different should be 50 seconds compared to the current time", () => {
+    const compare = addSecond(null, 50)
+    expect(diffSeconds(compare)).toBe(50)
   })
 })

src/__tests__/diffYears.spec.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, suite } from "vitest"
 import { diffYears } from "../diffYears"
+import { addYear } from "../addYear"
 
 describe("differenceInYears", () => {
   it("returns the amount of full years between dates", () => {
@@ -45,4 +46,9 @@ describe("differenceInYears", () => {
       expect(diffYears("2024-04-27", "2025-04-26")).toBe(0)
     })
   })
+
+  it("different should be 3 month compared to the current time", () => {
+    const compare = addYear(null, -6)
+    expect(diffYears(null, compare)).toBe(6)
+  })
 })

src/__tests__/hourEnd.spec.ts

@@ -4,8 +4,11 @@ process.env.TZ = "America/New_York"
 
 describe("hourEnd", () => {
   it("can become the end of the hour", () => {
-    expect(hourEnd("2023-02-22T12:30:00Z").toISOString()).toBe(
-      "2023-02-22T12:59:59.999Z"
-    )
+    expect(hourEnd("2023-02-22T12:30:00Z").toISOString()).toBe("2023-02-22T12:59:59.999Z")
+  })
+  it("can become the end of the current hour", () => {
+    const compare = new Date()
+    compare.setMinutes(59, 59, 999)
+    expect(hourEnd()).toEqual(compare)
   })
 })

src/__tests__/hourStart.spec.ts

@@ -8,4 +8,10 @@ describe("hourStart", () => {
       "2023-02-22T12:00:00.000Z"
     )
   })
+
+  it("can become the start of the current hour", () => {
+    const compare = new Date()
+    compare.setMinutes(0, 0, 0)
+    expect(hourStart()).toEqual(compare)
+  })
 })

src/__tests__/isAfter.spec.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest"
 import { isAfter } from "../isAfter"
+import { addDay } from "../addDay"
 process.env.TZ = "America/New_York"
 
 describe("isAfter", () => {
@@ -11,7 +12,14 @@ describe("isAfter", () => {
   })
   it("returns error if date is not valid", () => {
     expect(() => isAfter("invalid", "2022-01-01")).toThrowError(
-      "Non ISO 8601 compliant date",
+      "Non ISO 8601 compliant date"
     )
   })
+
+  it("returns false if date is in the past", () => {
+    expect(isAfter(addDay(new Date(), -1))).toBe(false)
+  })
+  it("returns true if date is in the future", () => {
+    expect(isAfter(addDay(new Date(), 1))).toBe(true)
+  })
 })

src/__tests__/isBefore.spec.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest"
 import { isBefore } from "../isBefore"
+import { addDay } from "../addDay"
 process.env.TZ = "America/New_York"
 
 describe("isBefore", () => {
@@ -11,7 +12,14 @@ describe("isBefore", () => {
   })
   it("returns error if date is not valid", () => {
     expect(() => isBefore("invalid", "2022-01-01")).toThrowError(
-      "Non ISO 8601 compliant date",
+      "Non ISO 8601 compliant date"
     )
   })
+
+  it("returns true if date is in the past", () => {
+    expect(isBefore(addDay(new Date(), -1))).toBe(true)
+  })
+  it("returns false if date is in the future", () => {
+    expect(isBefore(addDay(new Date(), 1))).toBe(false)
+  })
 })

src/__tests__/isEqual.spec.ts

@@ -11,7 +11,12 @@ describe("isEqual", () => {
   })
   it("returns error if date is not valid", () => {
     expect(() => isEqual("invalid", "2022-01-01")).toThrowError(
-      "Non ISO 8601 compliant date",
+      "Non ISO 8601 compliant date"
     )
   })
+
+  it("returns true because the create dated is the current time", () => {
+    expect(isEqual(null, new Date())).toBe(true)
+    expect(isEqual(new Date())).toBe(true)
+  })
 })