feat(earliest): normalize DateTime before returning result

BREAKING CHANGE: The `earliest` functions now
throw `Error` if both specified DateTimes
contain numeric fields that are non-finite.

BREAKING CHANGE: The type parameters of the
`earliest` functions have been removed. These
functions now always either return a valid
DateTime or throw.

Author: djcsdy

index.ts

@@ -544,23 +544,32 @@ export function afterOrEqualFn(b: DateTimeOptions): (a: DateTimeOptions) => bool
  * Curried variant of {@link dateTimeAfterOrEqual}. */
 export const dateTimeAfterOrEqualFn = afterOrEqualFn;
 
-/** Compares two {@link DateTime}s and returns the earlier of the two. */
-export function earliest<T extends DateTimeOptions, U extends DateTimeOptions>(a: T, b: U): T | U {
-    return after(a, b) ? b : a;
+/** Compares two {@link DateTime}s and returns the earlier of the two.
+ *
+ * @throws {Error} if both specified `DateTime`s contain numeric fields that
+ *   are non-finite. */
+export function earliest(a: DateTimeOptions, b: DateTimeOptions): DateTime {
+    const as = toReferenceSeconds(a);
+    const bs = toReferenceSeconds(b);
+    return fromReferenceSeconds(as < bs ? as : bs);
 }
 
 /** Compares two {@link DateTime}s and returns the earlier of the two.
  *
  * Alias of {@link earliest}, useful for disambiguation from similar functions
- * that operate on other date/time types. */
+ * that operate on other date/time types.
+ *
+ * @throws {Error} if both specified `DateTime`s contain numeric fields that
+ *   are non-finite. */
 export const earliestDateTime = earliest;
 
 /** Compares two {@link DateTime}s and returns the earlier of the two.
  *
- * Curried variant of {@link earliest}. */
-export function earliestFn<T extends DateTimeOptions, U extends DateTimeOptions>(
-    b: U
-): (a: T) => T | U {
+ * Curried variant of {@link earliest}.
+ *
+ * @throws {Error} if both specified `DateTime`s contain numeric fields that
+ *   are non-finite. */
+export function earliestFn(b: DateTimeOptions): (a: DateTimeOptions) => DateTime {
     return a => earliest(a, b);
 }