@checkdigit/time 3.0.0-PR.17-5aaf → 4.0.0-PR.18-81a3

package/src/date-fns/getMilliseconds/test.mts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { getMilliseconds } from './index';
+
+describe('getMilliseconds', () => {
+  it('returns the milliseconds of the given date', () => {
+    const result = getMilliseconds(new Date(2012, 1 /* Feb */, 29, 11, 45, 5, 123));
+    expect(result).toBe(123);
+  });
+
+  it('accepts a timestamp', () => {
+    const result = getMilliseconds(new Date(2014, 3 /* Apr */, 2, 23, 30, 42, 500).getTime());
+    expect(result).toBe(500);
+  });
+
+  it('returns NaN if the given date is invalid', () => {
+    const result = getMilliseconds(new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});

package/src/date-fns/getMinutes/index.ts

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name getMinutes
@@ -8,16 +8,19 @@ import toDate from '../toDate/index';
  * @description
  * Get the minutes of the given date.
  *
- * @param date - the given date
- * @returns the minutes
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The given date
+ *
+ * @returns The minutes
  *
  * @example
  * // Get the minutes of 29 February 2012 11:45:05:
  * const result = getMinutes(new Date(2012, 1, 29, 11, 45, 5))
  * //=> 45
  */
-export default function getMinutes<DateType extends Date>(dirtyDate: DateType | number): number {
-  const date = toDate(dirtyDate);
-  const minutes = date.getMinutes();
+export function getMinutes<DateType extends Date>(date: DateType | number | string): number {
+  const _date = toDate(date);
+  const minutes = _date.getMinutes();
   return minutes;
 }

package/src/date-fns/getMinutes/test.mts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { getMinutes } from './index';
+
+describe('getMinutes', () => {
+  it('returns the minutes of the given date', () => {
+    const result = getMinutes(new Date(2012, 1 /* Feb */, 29, 11, 45, 5));
+    expect(result).toBe(45);
+  });
+
+  it('accepts a timestamp', () => {
+    const result = getMinutes(new Date(2014, 3 /* Apr */, 2, 23, 30).getTime());
+    expect(result).toBe(30);
+  });
+
+  it('returns NaN if the given date is invalid', () => {
+    const result = getMinutes(new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});

package/src/date-fns/getMonth/index.ts

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name getMonth
@@ -8,16 +8,19 @@ import toDate from '../toDate/index';
  * @description
  * Get the month of the given date.
  *
- * @param date - the given date
- * @returns the month
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The given date
+ *
+ * @returns The month index (0-11)
  *
  * @example
  * // Which month is 29 February 2012?
  * const result = getMonth(new Date(2012, 1, 29))
  * //=> 1
  */
-export default function getMonth<DateType extends Date>(dirtyDate: DateType | number): number {
-  const date = toDate(dirtyDate);
-  const month = date.getMonth();
+export function getMonth<DateType extends Date>(date: DateType | number | string): number {
+  const _date = toDate(date);
+  const month = _date.getMonth();
   return month;
 }

package/src/date-fns/getMonth/test.mts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { getMonth } from './index';
+
+describe('getMonth', () => {
+  it('returns the month of the given date', () => {
+    const result = getMonth(new Date(2012, 1 /* Feb */, 29));
+    expect(result).toBe(1);
+  });
+
+  it('accepts a timestamp', () => {
+    const result = getMonth(new Date(2014, 3 /* Apr */, 2).getTime());
+    expect(result).toBe(3);
+  });
+
+  it('returns NaN if the given date is invalid', () => {
+    const result = getMonth(new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});

package/src/date-fns/getOverlappingDaysInIntervals/index.ts

@@ -1,5 +1,6 @@
+import { getTimezoneOffsetInMilliseconds } from '../_lib/getTimezoneOffsetInMilliseconds/index';
 import { millisecondsInDay } from '../constants/index';
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 import type { Interval } from '../types';
 
 /**
@@ -8,13 +9,19 @@ import type { Interval } from '../types';
  * @summary Get the number of days that overlap in two time intervals
  *
  * @description
- * Get the number of days that overlap in two time intervals
+ * Get the number of days that overlap in two time intervals. It uses the time
+ * between dates to calculate the number of days, rounding it up to include
+ * partial days.
  *
- * @param intervalLeft - the first interval to compare. See [Interval]{@link docs/Interval}
- * @param intervalRight - the second interval to compare. See [Interval]{@link docs/Interval}
- * @returns the number of days that overlap in two time intervals
- * @throws {RangeError} The start of an interval cannot be after its end
- * @throws {RangeError} Date in interval cannot be `Invalid Date`
+ * Two equal 0-length intervals will result in 0. Two equal 1ms intervals will
+ * result in 1.
+ *
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param intervalLeft - The first interval to compare.
+ * @param intervalRight - The second interval to compare.
+ *
+ * @returns The number of days that overlap in two time intervals
  *
  * @example
  * // For overlapping time intervals adds 1 for each started overlapping day:
@@ -33,31 +40,23 @@ import type { Interval } from '../types';
  * //=> 0
  */
 
-export default function getOverlappingDaysInIntervals<DateType extends Date>(
+export function getOverlappingDaysInIntervals<DateType extends Date>(
   intervalLeft: Interval<DateType>,
   intervalRight: Interval<DateType>,
 ): number {
-  const leftStartTime = toDate(intervalLeft.start).getTime();
-  const leftEndTime = toDate(intervalLeft.end).getTime();
-  const rightStartTime = toDate(intervalRight.start).getTime();
-  const rightEndTime = toDate(intervalRight.end).getTime();
-
-  // Throw an exception if start date is after end date or if any date is `Invalid Date`
-  if (!(leftStartTime <= leftEndTime && rightStartTime <= rightEndTime)) {
-    throw new RangeError('Invalid interval');
-  }
-
-  const isOverlapping = leftStartTime < rightEndTime && rightStartTime < leftEndTime;
-
-  if (!isOverlapping) {
-    return 0;
-  }
-
-  const overlapStartDate = rightStartTime < leftStartTime ? leftStartTime : rightStartTime;
+  const [leftStart, leftEnd] = [+toDate(intervalLeft.start), +toDate(intervalLeft.end)].sort((a, b) => a - b);
+  const [rightStart, rightEnd] = [+toDate(intervalRight.start), +toDate(intervalRight.end)].sort((a, b) => a - b);
 
-  const overlapEndDate = rightEndTime > leftEndTime ? leftEndTime : rightEndTime;
+  // Prevent NaN result if intervals don't overlap at all.
+  const isOverlapping = leftStart! < rightEnd! && rightStart! < leftEnd!;
+  if (!isOverlapping) return 0;
 
-  const differenceInMs = overlapEndDate - overlapStartDate;
+  // Remove the timezone offset to negate the DST effect on calculations.
+  const overlapLeft = rightStart! < leftStart! ? leftStart : rightStart;
+  const left = overlapLeft! - getTimezoneOffsetInMilliseconds(overlapLeft!);
+  const overlapRight = rightEnd! > leftEnd! ? leftEnd : rightEnd;
+  const right = overlapRight! - getTimezoneOffsetInMilliseconds(overlapRight!);
 
-  return Math.ceil(differenceInMs / millisecondsInDay);
+  // Ceil the number to include partial days too.
+  return Math.ceil((right - left) / millisecondsInDay);
 }

package/src/date-fns/getOverlappingDaysInIntervals/test.mts

@@ -0,0 +1,243 @@
+/* eslint-env mocha */
+
+import { describe, expect, it } from 'vitest';
+import { getOverlappingDaysInIntervals } from './index';
+
+describe('getOverlappingDaysInIntervals', () => {
+  const initialIntervalStart = new Date(2016, 10, 10, 13, 0, 0);
+  const initialIntervalEnd = new Date(2016, 11, 3, 15, 0, 0);
+
+  describe("when the time intervals don't overlap", () => {
+    it('returns 0 for a valid non overlapping interval before another interval', () => {
+      const earlierIntervalStart = new Date(2016, 9, 25);
+      const earlierIntervalEnd = new Date(2016, 10, 9);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: earlierIntervalStart, end: earlierIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it('returns 0 for a valid non overlapping interval after another interval', () => {
+      const laterIntervalStart = new Date(2016, 11, 4);
+      const laterIntervalEnd = new Date(2016, 11, 9);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: laterIntervalStart, end: laterIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it('returns 0 for a non overlapping same-day interval', () => {
+      const sameDayIntervalStart = new Date(2016, 11, 4, 9, 0, 0);
+      const sameDayIntervalEnd = new Date(2016, 11, 4, 18, 0, 0);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: sameDayIntervalStart, end: sameDayIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it('returns 0 for an interval differing by a few hours', () => {
+      const oneDayOverlappingIntervalStart = new Date(2016, 11, 3, 18, 0, 0);
+      const oneDayOverlappingIntervalEnd = new Date(2016, 11, 14, 13, 0, 0);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        {
+          start: oneDayOverlappingIntervalStart,
+          end: oneDayOverlappingIntervalEnd,
+        },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it("returns 0 for an interval with the same startDateTime as the initial time intervals's endDateTime", () => {
+      const oneDayOverlapIntervalStart = new Date(2016, 11, 3, 15, 0, 0);
+      const oneDayOverlapIntervalEnd = new Date(2016, 11, 14, 13, 0, 0);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: oneDayOverlapIntervalStart, end: oneDayOverlapIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it("returns 0 for an interval with the same endDateTime as the initial time interval's startDateTime", () => {
+      const oneDayOverlapIntervalStart = new Date(2016, 10, 3, 15, 0, 0);
+      const oneDayOverlapIntervalEnd = new Date(2016, 10, 10, 13, 0, 0);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: oneDayOverlapIntervalStart, end: oneDayOverlapIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+  });
+
+  describe('when the time intervals overlap', () => {
+    it('rounds up the result to include each started overlapping day', () => {
+      const includedIntervalStart = new Date(2016, 10, 14, 9, 0, 0);
+      const includedIntervalEnd = new Date(2016, 10, 15, 18, 0, 0);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: includedIntervalStart, end: includedIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(2);
+    });
+
+    it('returns the correct value for an interval included within another interval', () => {
+      const includedIntervalStart = new Date(2016, 10, 14);
+      const includedIntervalEnd = new Date(2016, 10, 15);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: includedIntervalStart, end: includedIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(1);
+    });
+
+    it('returns the correct value for an interval overlapping at the end', () => {
+      const endOverlappingIntervalStart = new Date(2016, 10, 5);
+      const endOverlappingIntervalEnd = new Date(2016, 10, 14);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: endOverlappingIntervalStart, end: endOverlappingIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(4);
+    });
+
+    it('returns the correct value for an interval overlapping at the beginning', () => {
+      const startOverlappingIntervalStart = new Date(2016, 10, 20);
+      const startOverlappingIntervalEnd = new Date(2016, 11, 14);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        {
+          start: startOverlappingIntervalStart,
+          end: startOverlappingIntervalEnd,
+        },
+      );
+      expect(numOverlappingDays).toBe(14);
+    });
+
+    it('returns the correct value for an interval including another interval', () => {
+      const includingIntervalStart = new Date(2016, 10, 5);
+      const includingIntervalEnd = new Date(2016, 11, 15);
+
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: initialIntervalStart, end: initialIntervalEnd },
+        { start: includingIntervalStart, end: includingIntervalEnd },
+      );
+      expect(numOverlappingDays).toBe(24);
+    });
+
+    it('considers equal 0-lenght intervals not overlapping', () => {
+      const date = new Date(2016, 10, 15);
+      const numOverlappingDays = getOverlappingDaysInIntervals({ start: date, end: date }, { start: date, end: date });
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it('considers equal 1ms-length intervals overlapping', () => {
+      const start = new Date(2016, 10, 15);
+      const end = new Date(2016, 10, 15, 0, 0, 0, 1);
+      const numOverlappingDays = getOverlappingDaysInIntervals({ start, end }, { start, end });
+      expect(numOverlappingDays).toBe(1);
+    });
+  });
+
+  it('accepts a timestamp', () => {
+    const initialIntervalStart = new Date(2016, 10, 10, 13, 0, 0).getTime();
+    const initialIntervalEnd = new Date(2016, 11, 3, 15, 0, 0).getTime();
+
+    const endOverlappingIntervalStart = new Date(2016, 10, 5).getTime();
+    const endOverlappingIntervalEnd = new Date(2016, 10, 14).getTime();
+
+    const numOverlappingDays = getOverlappingDaysInIntervals(
+      { start: initialIntervalStart, end: initialIntervalEnd },
+      { start: endOverlappingIntervalStart, end: endOverlappingIntervalEnd },
+    );
+    expect(numOverlappingDays).toBe(4);
+  });
+
+  it('normalizes the left interval if its start date is after the end date', () => {
+    const initialIntervalStart = new Date(2016, 10, 10, 13, 0, 0);
+    const initialIntervalEnd = new Date(2016, 11, 3, 15, 0, 0);
+
+    const endOverlappingIntervalStart = new Date(2016, 10, 5);
+    const endOverlappingIntervalEnd = new Date(2016, 10, 14);
+
+    const numOverlappingDays = getOverlappingDaysInIntervals(
+      { start: initialIntervalEnd, end: initialIntervalStart },
+      { start: endOverlappingIntervalStart, end: endOverlappingIntervalEnd },
+    );
+    expect(numOverlappingDays).toBe(4);
+  });
+
+  it('normalizes the right interval if its start date is after the end date', () => {
+    const initialIntervalStart = new Date(2016, 10, 10, 13, 0, 0);
+    const initialIntervalEnd = new Date(2016, 11, 3, 15, 0, 0);
+
+    const endOverlappingIntervalStart = new Date(2016, 10, 5);
+    const endOverlappingIntervalEnd = new Date(2016, 10, 14);
+
+    const numOverlappingDays = getOverlappingDaysInIntervals(
+      { start: initialIntervalStart, end: initialIntervalEnd },
+      { start: endOverlappingIntervalEnd, end: endOverlappingIntervalStart },
+    );
+    expect(numOverlappingDays).toBe(4);
+  });
+
+  describe('one of the dates is `Invalid Date`', () => {
+    it('returns 0 if the start date of the initial time interval is `Invalid Date`', () => {
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: new Date(NaN), end: new Date(2016, 10, 3) },
+        { start: new Date(2016, 10, 5), end: new Date(2016, 10, 15) },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it('throws an exception if the end date of the initial time interval is `Invalid Date`', () => {
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: new Date(2016, 10, 3), end: new Date(NaN) },
+        { start: new Date(2016, 10, 5), end: new Date(2016, 10, 15) },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it('returns 0 if the start date of the compared time interval is `Invalid Date`', () => {
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: new Date(2016, 10, 3), end: new Date(2016, 10, 7) },
+        { start: new Date(NaN), end: new Date(2016, 10, 5) },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+
+    it('returns 0 if the end date of the compared time interval is `Invalid Date`', () => {
+      const numOverlappingDays = getOverlappingDaysInIntervals(
+        { start: new Date(2016, 10, 3), end: new Date(2016, 10, 7) },
+        { start: new Date(2016, 10, 5), end: new Date(NaN) },
+      );
+      expect(numOverlappingDays).toBe(0);
+    });
+  });
+
+  it('properly sorts the dates', () => {
+    const result = getOverlappingDaysInIntervals(
+      {
+        start: new Date(2001, 8 /* Sep */, 1, 16),
+        end: new Date(2023, 11 /* Dec */, 20, 16),
+      },
+      {
+        start: new Date(2023, 11 /* Dec */, 21, 16),
+        end: new Date(2001, 8 /* Sep */, 9, 16),
+      },
+    );
+    expect(result).toBe(8137);
+  });
+});

package/src/date-fns/getQuarter/index.ts

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name getQuarter
@@ -8,16 +8,19 @@ import toDate from '../toDate/index';
  * @description
  * Get the year quarter of the given date.
  *
- * @param date - the given date
- * @returns the quarter
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The given date
+ *
+ * @returns The quarter
  *
  * @example
  * // Which quarter is 2 July 2014?
  * const result = getQuarter(new Date(2014, 6, 2))
  * //=> 3
  */
-export default function getQuarter<DateType extends Date>(dirtyDate: DateType | number): number {
-  const date = toDate(dirtyDate);
-  const quarter = Math.floor(date.getMonth() / 3) + 1;
+export function getQuarter<DateType extends Date>(date: DateType | number | string): number {
+  const _date = toDate(date);
+  const quarter = Math.trunc(_date.getMonth() / 3) + 1;
   return quarter;
 }

package/src/date-fns/getQuarter/test.mts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { getQuarter } from './index';
+
+describe('getQuarter', () => {
+  it('returns the quarter of the given date', () => {
+    const result = getQuarter(new Date(2014, 6 /* Jul */, 2));
+    expect(result).toBe(3);
+  });
+
+  it('accepts a timestamp', () => {
+    const result = getQuarter(new Date(2014, 3 /* Apr */, 2).getTime());
+    expect(result).toBe(2);
+  });
+
+  it('returns NaN if the given date is invalid', () => {
+    const result = getQuarter(new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});

package/src/date-fns/getSeconds/index.ts

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name getSeconds
@@ -8,16 +8,19 @@ import toDate from '../toDate/index';
  * @description
  * Get the seconds of the given date.
  *
- * @param date - the given date
- * @returns the seconds
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The given date
+ *
+ * @returns The seconds
  *
  * @example
  * // Get the seconds of 29 February 2012 11:45:05.123:
  * const result = getSeconds(new Date(2012, 1, 29, 11, 45, 5, 123))
  * //=> 5
  */
-export default function getSeconds<DateType extends Date>(dirtyDate: DateType | number): number {
-  const date = toDate(dirtyDate);
-  const seconds = date.getSeconds();
+export function getSeconds<DateType extends Date>(date: DateType | number | string): number {
+  const _date = toDate(date);
+  const seconds = _date.getSeconds();
   return seconds;
 }

package/src/date-fns/getSeconds/test.mts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { getSeconds } from './index';
+
+describe('getSeconds', () => {
+  it('returns the seconds of the given date', () => {
+    const result = getSeconds(new Date(2012, 1 /* Feb */, 29, 11, 45, 5, 123));
+    expect(result).toBe(5);
+  });
+
+  it('accepts a timestamp', () => {
+    const result = getSeconds(new Date(2014, 3 /* Apr */, 2, 23, 30, 42).getTime());
+    expect(result).toBe(42);
+  });
+
+  it('returns NaN if the given date is invalid', () => {
+    const result = getSeconds(new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});

package/src/date-fns/getTime/index.ts

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name getTime
@@ -8,16 +8,19 @@ import toDate from '../toDate/index';
  * @description
  * Get the milliseconds timestamp of the given date.
  *
- * @param date - the given date
- * @returns the timestamp
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The given date
+ *
+ * @returns The timestamp
  *
  * @example
  * // Get the timestamp of 29 February 2012 11:45:05.123:
  * const result = getTime(new Date(2012, 1, 29, 11, 45, 5, 123))
  * //=> 1330515905123
  */
-export default function getTime<DateType extends Date>(dirtyDate: DateType | number): number {
-  const date = toDate(dirtyDate);
-  const timestamp = date.getTime();
+export function getTime<DateType extends Date>(date: DateType | number | string): number {
+  const _date = toDate(date);
+  const timestamp = _date.getTime();
   return timestamp;
 }

package/src/date-fns/getTime/test.mts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { getTime } from './index';
+
+describe('getTime', () => {
+  it('returns the timestamp of the given date', () => {
+    const timestamp = 1483228800000;
+    const result = getTime(new Date(timestamp));
+    expect(result).toBe(timestamp);
+  });
+
+  it('accepts a timestamp (and returns it unchanged)', () => {
+    const timestamp = 804643200000;
+    const result = getTime(timestamp);
+    expect(result).toBe(timestamp);
+  });
+
+  it('returns NaN if the given date is invalid', () => {
+    const result = getTime(new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});

package/src/date-fns/getUnixTime/index.ts

@@ -1,4 +1,4 @@
-import getTime from '../getTime/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name getUnixTime
@@ -8,14 +8,17 @@ import getTime from '../getTime/index';
  * @description
  * Get the seconds timestamp of the given date.
  *
- * @param date - the given date
- * @returns the timestamp
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The given date
+ *
+ * @returns The timestamp
  *
  * @example
  * // Get the timestamp of 29 February 2012 11:45:05 CET:
  * const result = getUnixTime(new Date(2012, 1, 29, 11, 45, 5))
  * //=> 1330512305
  */
-export default function getUnixTime<DateType extends Date>(dirtyDate: DateType | number): number {
-  return Math.floor(getTime(dirtyDate) / 1000);
+export function getUnixTime<DateType extends Date>(date: DateType | number | string): number {
+  return Math.trunc(+toDate(date) / 1000);
 }

package/src/date-fns/getUnixTime/test.mts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { getUnixTime } from './index';
+
+describe('getUnixTime', () => {
+  it('returns the timestamp of the given date', () => {
+    const timestamp = 1483228800000;
+    const result = getUnixTime(new Date(timestamp));
+    expect(result).toBe(1483228800);
+  });
+
+  it('accepts a timestamp (and returns it unchanged)', () => {
+    const timestamp = 804643200000;
+    const result = getUnixTime(timestamp);
+    expect(result).toBe(804643200);
+  });
+
+  it('returns NaN if the given date is invalid', () => {
+    const result = getUnixTime(new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+
+  it('seconds timestamp handles negative numbers', () => {
+    expect(getUnixTime(new Date(1001))).toBe(1);
+    expect(getUnixTime(new Date(-1001))).toBe(-1);
+  });
+});