fix(diff): allow .diff(unit) shorthand for diffing with current time

[Ayo1984]

Summary

This PR adds shorthand support for calling .diff(unit) as equivalent to .diff(dayjs(), unit).

Problem

The documentation suggests that if no date is supplied, .diff() compares with the current time.
However, calling .diff('days') or .diff('hours') currently treats the string as a date, resulting in Invalid Date → NaN.

Solution

• Detect when .diff() is called with a single recognized unit string (e.g. 'days').
• Fully backward compatible — date-like strings continue to be parsed as dates.
• Added test cases.

Example

// Before (returns NaN)
dayjs('2025-01-10').diff('days')

// After
dayjs('2025-01-10').diff('days') // same as dayjs('2025-01-10').diff(dayjs(), 'days')


----
###

Resolves #2943

[dominik-deak]

👌

[Ayo1984]

@iamkun this is pretty small

[iamkun]

Thanks for the contribution! Really appreciate the effort to make the API feel more intuitive.

After checking the behavior in Moment.js, it turns out that Moment does not support this shorthand syntax either — you always need to provide a comparison date as the first argument to .diff(). For example:

moment('2025-01-10').diff('days') // invalid → tries to parse "days" as a date
moment('2025-01-10').diff(moment(), 'days') // ✅ valid usage

So in order to stay consistent with Moment.js (and to avoid unexpected implicit behavior), maybe, Day.js has also required a comparison date to be passed explicitly.

Could you share which specific part of that documentation gave you this impression?

https://day.js.org/docs/en/display/difference

[Ayo1984]

Thank you for the feedback, didn't realise MomentJS was still being used as a benchmark

I think the lack of compile time error must have made the issue creator confused, we can mark this PR as closed

[iamkun]

You can actually see that most of the Day.js unit tests use Moment.js results as a reference — a lot of community members also adopt Day.js as a drop-in replacement for Moment.js.
So keeping the core API behavior aligned between the two libraries makes sense and is probably the best long-term direction for consistency and developer expectations.

At the same time, I think we could improve the developer experience by adding an error or warning for this specific case in the https://day.js.org/docs/en/plugin/dev-helper dev helper plugin.
That would help developers quickly spot incorrect usages like .diff('days') and understand why it’s invalid.

What do you think about that approach?

[Ayo1984]

I see
And yeah, updating the dev helper plugin will be the best choice of action here
I'll create a PR for it if it's not already in your list of plans

[iamkun]

Really excited for your PR! Appreciate you taking this on. 🙌

[Ayo1984]

Just created a PR for that in #2948 , happy to close this afterwards

[Ayo1984]

closed as addressed, solution available in #2948