isDate() type guard

[BarryThePenguin]

Is it possible to add a type guard for isDate() in the TypeScript definitions?

I looked at previous issues and couldn't see any previous discussion. It doesn't look like it was considered in the implementation #754

- function isDate(value: any): boolean
+ function isDate(value: any): value is Date

I looked at putting a PR together, but wasn't confident making changes to the script that builds the type definitions

[imballinst]

hi @BarryThePenguin!

I think this may be related but I might be wrong -- @kossnocorp is working on this typescriptify branch. When it's finished, this isDate function https://github.com/date-fns/date-fns/blob/typescriptify/src/isDate/index.ts will have value: Date as the parameter, so is guaranteed to be a Date object. CMIIW @kossnocorp.

[icehaunter]

I filed a similar issue about isValid: #1880. @maximillianfx wanted to tackle that, so I am mentioning him.

@imballinst, the file you linked still returns boolean, which means it might not act as a typeguard. TS might infer that from value instanceof Date, I didn't test, but I think that it would be better to be explicit. TS doc specifies type guard as value is Date, which would imply boolean return, but also would mark the passed-in argument as a Date for that branch of code.

Moreover, for the code you've linked, I would specify the incoming type as value: unknown to not rely on implicit any, but that is slightly beyond the current discussion

[maximillianfx]

Thanks @icehaunter , I'll check it out.

[imballinst]

TS doc specifies type guard as value is Date, which would imply boolean return, but also would mark the passed-in argument as a Date for that branch of code.

@icehaunter ah, gotcha! Yes, that is a great point, I didn't see that before. I 💯 agree with the part of being explicit, it's really useful for assertions in a code-branch.

[adenvt]

any update for this issue??

[imballinst]

This should be fixed in the recent Typescript-ifying effort, I think?

date-fns/src/isDate/index.ts

Lines 39 to 47 in b500440

	export default function isDate(value: unknown): value is Date {
	requiredArgs(1, arguments)
	return (
	value instanceof Date ||
	(typeof value === 'object' &&
	Object.prototype.toString.call(value) === '[object Date]')
	)
	}

[tan75]

@adenvt @imballinst
thats correct - this function has already been migrated to TS.

[dodas]

Hey @tan75 !
When is this expected to be released? Looks like it isn't out in 2.21.1.
Thanks.

[fturmel]

@dodas @tan75

I just investigated this. While the type guard is implemented in the isDate source code, the TS types published on npm for this project are generated with a custom system based off the jsdocs definitions.

Some changes would have to be made to that system so it understands TS type guards but doesn't mess up documentation or Flow types generation. Maybe by introducing a custom jsdoc tag that would take precedent over @returns for TS types only? Or have that system understand that TS type guards are equivalent to booleans for docs/Flow?

date-fns/src/isDate/index.ts

Lines 15 to 16 in ea3f050

	* @param {*} value - the value to check
	* @returns {boolean} true if the given value is a date

date-fns/src/isDate/index.ts

Line 39 in ea3f050

export default function isDate(value: unknown): value is Date {

date-fns/typings.d.ts

Line 636 in ea3f050

function isDate(value: any): boolean

[fturmel]

Also regarding #1880, I don't think isValid should implement a similar type guard since the argument passed could be a numerical timestamp and return true.

See the truth table in the docs: https://date-fns.org/docs/isValid

[RuckieOfficial]

Why is it closed? It still returns boolean instead of Date object.

In this generated file is boolean returned:
https://github.com/date-fns/date-fns/blob/typescriptify/src/isDate/index.ts#L36

and in this definition it is fine:

date-fns/src/isDate/index.ts

Lines 39 to 47 in b500440

	export default function isDate(value: unknown): value is Date {
	requiredArgs(1, arguments)
	return (
	value instanceof Date ||
	(typeof value === 'object' &&
	Object.prototype.toString.call(value) === '[object Date]')
	)
	}

It is probably due to this typescript generate definition: https://github.com/date-fns/date-fns/blob/b500440132b69fdf2b430743cf86bbc929b60307/scripts/build/_lib/typings/typeScript.js#L142C57-L142C57