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

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

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name closestIndexTo
@@ -8,9 +8,12 @@ import toDate from '../toDate/index';
  * @description
  * Return an index of the closest date from the array comparing to the given date.
  *
- * @param dateToCompare - the date to compare with
- * @param datesArray - the array to search
- * @returns an index of the date closest to the given date or undefined if no valid value is given
+ * @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 dateToCompare - The date to compare with
+ * @param dates - The array to search
+ *
+ * @returns An index of the date closest to the given date or undefined if no valid value is given
  *
  * @example
  * // Which date is closer to 6 September 2015?
@@ -23,19 +26,19 @@ import toDate from '../toDate/index';
  * const result = closestIndexTo(dateToCompare, datesArray)
  * //=> 1
  */
-export default function closestIndexTo<DateType extends Date>(
-  dirtyDateToCompare: DateType | number,
-  datesArray: Array<DateType | number>,
+export function closestIndexTo<DateType extends Date>(
+  dateToCompare: DateType | number | string,
+  dates: Array<DateType | number | string>,
 ): number | undefined {
-  const dateToCompare = toDate(dirtyDateToCompare);
+  const date = toDate(dateToCompare);
 
-  if (isNaN(Number(dateToCompare))) return NaN;
+  if (isNaN(Number(date))) return NaN;
 
-  const timeToCompare = dateToCompare.getTime();
+  const timeToCompare = date.getTime();
 
   let result: number | undefined;
   let minDistance: number;
-  datesArray.forEach(function (dirtyDate, index) {
+  dates.forEach(function (dirtyDate, index) {
     const currentDate = toDate(dirtyDate);
 
     if (isNaN(Number(currentDate))) {

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { closestIndexTo } from './index';
+
+describe('closestIndexTo', () => {
+  it('returns the date index from the given array closest to the given date', () => {
+    const date = new Date(2014, 6 /* Jul */, 2);
+    const result = closestIndexTo(date, [new Date(2015, 7 /* Aug */, 31), new Date(2012, 6 /* Jul */, 2)]);
+    expect(result).toBe(0);
+  });
+
+  it('works if the closest date from the given array is before the given date', () => {
+    const date = new Date(2014, 6 /* Jul */, 2, 6, 30, 4, 500);
+    const result = closestIndexTo(date, [
+      new Date(2014, 6 /* Jul */, 2, 6, 30, 5, 900),
+      new Date(2014, 6 /* Jul */, 2, 6, 30, 3, 900),
+      new Date(2014, 6 /* Jul */, 2, 6, 30, 10),
+    ]);
+    expect(result).toBe(1);
+  });
+
+  it('accepts timestamps', () => {
+    const date = new Date(2014, 6 /* Jul */, 2).getTime();
+    const result = closestIndexTo(date, [
+      new Date(2015, 7 /* Aug */, 31).getTime(),
+      new Date(2012, 6 /* Jul */, 2).getTime(),
+    ]);
+    expect(result).toBe(0);
+  });
+
+  it('returns undefined if the given array is empty', () => {
+    const date = new Date(2014, 6 /* Jul */, 2).getTime();
+    const result = closestIndexTo(date, []);
+    expect(result).toBe(undefined);
+  });
+
+  it('returns NaN if the given date is `Invalid Date`', () => {
+    const date = new Date(NaN);
+    const result = closestIndexTo(date, [new Date(2015, 7 /* Aug */, 31), new Date(2012, 6 /* Jul */, 2)]);
+    expect(result != null && isNaN(result)).toBe(true);
+  });
+
+  it('returns NaN if any date in the given array is `Invalid Date`', () => {
+    const date = new Date(2014, 6 /* Jul */, 2);
+    const result = closestIndexTo(date, [
+      new Date(2015, 7 /* Aug */, 31),
+      new Date(NaN),
+      new Date(2012, 6 /* Jul */, 2),
+    ]);
+    expect(result != null && isNaN(result)).toBe(true);
+  });
+});

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

@@ -1,5 +1,5 @@
-import constructFrom from '../constructFrom/index';
-import toDate from '../toDate/index';
+import { constructFrom } from '../constructFrom/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name closestTo
@@ -9,9 +9,12 @@ import toDate from '../toDate/index';
  * @description
  * Return a date from the array closest to the given date.
  *
- * @param dateToCompare - the date to compare with
- * @param datesArray - the array to search
- * @returns the date from the array closest to the given date or undefined if no valid value is given
+ * @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 dateToCompare - The date to compare with
+ * @param dates - The array to search
+ *
+ * @returns The date from the array closest to the given date or undefined if no valid value is given
  *
  * @example
  * // Which date is closer to 6 September 2015: 1 January 2000 or 1 January 2030?
@@ -22,23 +25,23 @@ import toDate from '../toDate/index';
  * ])
  * //=> Tue Jan 01 2030 00:00:00
  */
-export default function closestTo<DateType extends Date>(
-  dirtyDateToCompare: DateType | number,
-  datesArray: Array<DateType | number>,
+export function closestTo<DateType extends Date>(
+  dateToCompare: DateType | number | string,
+  dates: Array<DateType | number | string>,
 ): DateType | undefined {
-  const dateToCompare = toDate(dirtyDateToCompare);
+  const date = toDate(dateToCompare);
 
-  if (isNaN(Number(dateToCompare))) return constructFrom(dirtyDateToCompare, NaN);
+  if (isNaN(Number(date))) return constructFrom(dateToCompare, NaN);
 
-  const timeToCompare = dateToCompare.getTime();
+  const timeToCompare = date.getTime();
 
   let result: DateType | undefined;
   let minDistance: number;
-  datesArray.forEach((dirtyDate) => {
+  dates.forEach((dirtyDate) => {
     const currentDate = toDate(dirtyDate);
 
     if (isNaN(Number(currentDate))) {
-      result = constructFrom(dirtyDateToCompare, NaN);
+      result = constructFrom(dateToCompare, NaN);
       minDistance = NaN;
       return;
     }

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

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { closestTo } from './index';
+
+describe('closestTo', () => {
+  it('returns the date from the given array closest to the given date', () => {
+    const date = new Date(2014, 6 /* Jul */, 2);
+    const result = closestTo(date, [new Date(2015, 7 /* Aug */, 31), new Date(2012, 6 /* Jul */, 2)]);
+    expect(result).toEqual(new Date(2015, 7 /* Aug */, 31));
+  });
+
+  it('works if the closest date from the given array is before the given date', () => {
+    const date = new Date(2014, 6 /* Jul */, 2, 6, 30, 4, 500);
+    const result = closestTo(date, [
+      new Date(2014, 6 /* Jul */, 2, 6, 30, 5, 900),
+      new Date(2014, 6 /* Jul */, 2, 6, 30, 3, 900),
+      new Date(2014, 6 /* Jul */, 2, 6, 30, 10),
+    ]);
+    expect(result).toEqual(new Date(2014, 6 /* Jul */, 2, 6, 30, 3, 900));
+  });
+
+  it('accepts timestamps', () => {
+    const date = new Date(2014, 6 /* Jul */, 2).getTime();
+    const result = closestTo(date, [
+      new Date(2015, 7 /* Aug */, 31).getTime(),
+      new Date(2012, 6 /* Jul */, 2).getTime(),
+    ]);
+    expect(result).toEqual(new Date(2015, 7 /* Aug */, 31));
+  });
+
+  it('returns undefined if the given array is empty', () => {
+    const date = new Date(2014, 6 /* Jul */, 2).getTime();
+    const result = closestTo(date, []);
+    expect(result).toEqual(undefined);
+  });
+
+  it('returns `Invalid Date` if the given date is `Invalid Date`', () => {
+    const date = new Date(NaN);
+    const result = closestTo(date, [new Date(2015, 7 /* Aug */, 31), new Date(2012, 6 /* Jul */, 2)]);
+
+    expect(result instanceof Date && isNaN(result.getTime())).toBe(true);
+  });
+
+  it('returns `Invalid Date` if any date in the given array is `Invalid Date`', () => {
+    const date = new Date(2014, 6 /* Jul */, 2);
+    const result = closestTo(date, [new Date(2015, 7 /* Aug */, 31), new Date(NaN), new Date(2012, 6 /* Jul */, 2)]);
+
+    expect(result instanceof Date && isNaN(result.getTime())).toBe(true);
+  });
+});

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

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name compareAsc
@@ -9,9 +9,12 @@ import toDate from '../toDate/index';
  * Compare the two dates and return 1 if the first date is after the second,
  * -1 if the first date is before the second or 0 if dates are equal.
  *
- * @param dateLeft - the first date to compare
- * @param dateRight - the second date to compare
- * @returns the result of the comparison
+ * @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 dateLeft - The first date to compare
+ * @param dateRight - The second date to compare
+ *
+ * @returns The result of the comparison
  *
  * @example
  * // Compare 11 February 1987 and 10 July 1989:
@@ -31,14 +34,14 @@ import toDate from '../toDate/index';
  * //   Sun Jul 02 1995 00:00:00
  * // ]
  */
-export default function compareAsc<DateType extends Date>(
-  dirtyDateLeft: DateType | number,
-  dirtyDateRight: DateType | number,
+export function compareAsc<DateType extends Date>(
+  dateLeft: DateType | number | string,
+  dateRight: DateType | number | string,
 ): number {
-  const dateLeft = toDate(dirtyDateLeft);
-  const dateRight = toDate(dirtyDateRight);
+  const _dateLeft = toDate(dateLeft);
+  const _dateRight = toDate(dateRight);
 
-  const diff = dateLeft.getTime() - dateRight.getTime();
+  const diff = _dateLeft.getTime() - _dateRight.getTime();
 
   if (diff < 0) {
     return -1;

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { compareAsc } from './index';
+
+describe('compareAsc', () => {
+  it('returns 0 if the given dates are equal', () => {
+    const result = compareAsc(new Date(1989, 6 /* Jul */, 10), new Date(1989, 6 /* Jul */, 10));
+    expect(result).toBe(0);
+  });
+
+  it('returns -1 if the first date is before the second one', () => {
+    const result = compareAsc(new Date(1987, 1 /* Feb */, 11), new Date(1989, 6 /* Jul */, 10));
+    expect(result).toBe(-1);
+  });
+
+  it('returns 1 if the first date is after the second one', () => {
+    const result = compareAsc(new Date(1989, 6 /* Jul */, 10), new Date(1987, 1 /* Feb */, 11));
+    expect(result).toBe(1);
+  });
+
+  it('sorts the dates array in the chronological order when function is passed as the argument to Array.prototype.sort()', () => {
+    const unsortedArray = [
+      new Date(1995, 6 /* Jul */, 2),
+      new Date(1987, 1 /* Feb */, 11),
+      new Date(1989, 6 /* Jul */, 10),
+    ];
+
+    const sortedArray = [
+      new Date(1987, 1 /* Feb */, 11),
+      new Date(1989, 6 /* Jul */, 10),
+      new Date(1995, 6 /* Jul */, 2),
+    ];
+
+    unsortedArray.sort(compareAsc);
+    const result = unsortedArray;
+
+    expect(result).toEqual(sortedArray);
+  });
+
+  it('accepts timestamps', () => {
+    const result = compareAsc(new Date(1987, 1 /* Feb */, 11).getTime(), new Date(1989, 6 /* Jul */, 10).getTime());
+    expect(result).toBe(-1);
+  });
+
+  it('returns NaN if the first date is `Invalid Date`', () => {
+    const result = compareAsc(new Date(NaN), new Date(1989, 6 /* Jul */, 10));
+    expect(isNaN(result)).toBe(true);
+  });
+
+  it('returns NaN if the second date is `Invalid Date`', () => {
+    const result = compareAsc(new Date(1989, 6 /* Jul */, 10), new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+
+  it('returns NaN if the both dates are `Invalid Date`', () => {
+    const result = compareAsc(new Date(NaN), new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});

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

@@ -1,4 +1,4 @@
-import toDate from '../toDate/index';
+import { toDate } from '../toDate/index';
 
 /**
  * @name compareDesc
@@ -9,9 +9,12 @@ import toDate from '../toDate/index';
  * Compare the two dates and return -1 if the first date is after the second,
  * 1 if the first date is before the second or 0 if dates are equal.
  *
- * @param dateLeft - the first date to compare
- * @param dateRight - the second date to compare
- * @returns the result of the comparison
+ * @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 dateLeft - The first date to compare
+ * @param dateRight - The second date to compare
+ *
+ * @returns The result of the comparison
  *
  * @example
  * // Compare 11 February 1987 and 10 July 1989 reverse chronologically:
@@ -31,14 +34,14 @@ import toDate from '../toDate/index';
  * //   Wed Feb 11 1987 00:00:00
  * // ]
  */
-export default function compareDesc<DateType extends Date>(
-  dirtyDateLeft: DateType | number,
-  dirtyDateRight: DateType | number,
+export function compareDesc<DateType extends Date>(
+  dateLeft: DateType | number | string,
+  dateRight: DateType | number | string,
 ): number {
-  const dateLeft = toDate(dirtyDateLeft);
-  const dateRight = toDate(dirtyDateRight);
+  const _dateLeft = toDate(dateLeft);
+  const _dateRight = toDate(dateRight);
 
-  const diff = dateLeft.getTime() - dateRight.getTime();
+  const diff = _dateLeft.getTime() - _dateRight.getTime();
 
   if (diff > 0) {
     return -1;

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { compareDesc } from './index';
+
+describe('compareDesc', () => {
+  it('returns 0 if the given dates are equal', () => {
+    const result = compareDesc(new Date(1989, 6 /* Jul */, 10), new Date(1989, 6 /* Jul */, 10));
+    expect(result).toBe(0);
+  });
+
+  it('returns 1 if the first date is before the second one', () => {
+    const result = compareDesc(new Date(1987, 1 /* Feb */, 11), new Date(1989, 6 /* Jul */, 10));
+    expect(result).toBe(1);
+  });
+
+  it('returns -1 if the first date is after the second one', () => {
+    const result = compareDesc(new Date(1989, 6 /* Jul */, 10), new Date(1987, 1 /* Feb */, 11));
+    expect(result).toBe(-1);
+  });
+
+  it('sorts the dates array in the reverse chronological order when function is passed as the argument to Array.prototype.sort()', () => {
+    const unsortedArray = [
+      new Date(1995, 6 /* Jul */, 2),
+      new Date(1987, 1 /* Feb */, 11),
+      new Date(1989, 6 /* Jul */, 10),
+    ];
+
+    const sortedArray = [
+      new Date(1995, 6 /* Jul */, 2),
+      new Date(1989, 6 /* Jul */, 10),
+      new Date(1987, 1 /* Feb */, 11),
+    ];
+
+    unsortedArray.sort(compareDesc);
+    const result = unsortedArray;
+
+    expect(result).toEqual(sortedArray);
+  });
+
+  it('accepts timestamps', () => {
+    const result = compareDesc(new Date(1987, 1 /* Feb */, 11).getTime(), new Date(1989, 6 /* Jul */, 10).getTime());
+    expect(result).toBe(1);
+  });
+
+  it('returns NaN if the first date is `Invalid Date`', () => {
+    const result = compareDesc(new Date(NaN), new Date(1989, 6 /* Jul */, 10));
+    expect(isNaN(result)).toBe(true);
+  });
+
+  it('returns NaN if the second date is `Invalid Date`', () => {
+    const result = compareDesc(new Date(1989, 6 /* Jul */, 10), new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+
+  it('returns NaN if the both dates are `Invalid Date`', () => {
+    const result = compareDesc(new Date(1989, 6 /* Jul */, 10), new Date(NaN));
+    expect(isNaN(result)).toBe(true);
+  });
+});