Confusing documentation around isValid()/toDate()

[pleunv]

The docs for isValid currently state the following:

Returns false if argument is Invalid Date and true otherwise. Argument is converted to Date using toDate. See toDate Invalid Date is a Date, whose time value is NaN.

with a type of

function isValid(
  date: unknown
): boolean

Going to the toDate docs we see the following:

Convert the given argument to an instance of Date.
If the argument is an instance of Date, the function returns its clone.
If the argument is a number, it is treated as a timestamp.
If the argument is none of the above, the function returns Invalid Date.
Note: all Date arguments passed to any date-fns function is processed by toDate.

Stating that the input can be either Date or number. However, the type is as follows:

function toDate<[DateType extends Date>(
  argument: string | number | DateType
): DateType

Implying that string should work as well. Upon testing, toDate('2024-02-13T09:42:53.057Z') correctly parses as "Tue Feb 13 2024 10:42:53 GMT+0100" leading me to believe that:

• The docs for toDate() do not correctly reflect that it also supports ISO strings as input, while the types do.
• Since isValid() refers to toDate() for its behavior, ISO strings should also be valid input for isValid().

The latter, however, appears to be an incorrect assumption as isValid('2024-02-13T09:42:53.057Z') returns false rather than true, which is also reflected by the implementation:

date-fns/src/isValid/index.ts

Lines 37 to 43 in 6f44a16

	export function isValid(date: unknown): boolean {
	if (!isDate(date) && typeof date !== "number") {
	return false;
	}
	const _date = toDate(date);
	return !isNaN(Number(_date));
	}

Based on the above I'm inclined to think the isValid() documentation shouldn't point to toDate() but instead just state that the input is expected to be either a date object or a number in order to validate. I also think a big source of confusion is the fact that the the isValid argument is typed as unknown. I get why since you can throw any value at it, but at the same time it hides critical information and might even be considered an anti-pattern in TS unless you're working with numbers, since any date object will be valid by default. And especially since v3 now allows string input pretty much everywhere, the current behavior of isValid is a bit unexpected:

All functions that accept date arguments now also accept strings.

Happy to help out if we find common ground 🙂.