Why does `diff()` method output positive/negative instead of absolute values?

[mirumirumi]

Describe the bug I always have a hard time fixing bugs, forgetting that the diff() method can be negative. I think the problem is that the name of the method seems to get absolute values.

Expected behavior What do you think about this?

Information

• Day.js Version [v1.11.9]

[kavish5]

You've pointed out a common point of confusion where the diff() method's result can be negative, which may not be immediately clear from the method's name. This behavior can lead to misunderstandings and bugs, especially for those who expect diff() to return absolute values.

I would like to highlight you that this enhancement, even if accepted by maintainers, would take time to merge into main code base. A temporary work around for you could be to have a utility function in your code base, say absDiff which calls diff function and wrap it under an abs function so your bug can be controlled permanently.

Proposed Enhancement A suggestion here is to introduce an absolute parameter to the diff() method. It provides a way to explicitly control the behavior of the method, allowing users to opt-in for absolute values when needed.

Suggested Implementation We could enhance the diff() method signature to include an optional absolute parameter:

diff(date, unit, absolute = false)

date: The date to compare with. unit: The type of unit to diff (e.g., 'day', 'month'). absolute: Optional boolean parameter. When set to true, the method returns an absolute value of the difference.

Default Behavior and Backward Compatibility The default value of absolute would be false to ensure backward compatibility. This way, existing codebases using Day.js will continue to function as expected, without any changes.

Example Usage const diffValue = dayjs('2023-01-01').diff('2022-12-01', 'day', true); // Returns an absolute value

Additional Ideas and Considerations Documentation Update: We should update the documentation to clearly explain the new parameter and provide examples of both usages. Community Feedback: It would be beneficial to gather feedback from the Day.js community on this proposed change, as it affects a commonly used method. Alternative Naming: As an alternative, consider introducing a new method (e.g., absDiff) that always returns an absolute value. This approach would avoid altering the existing diff() method's signature.

Seeking Input I'm open to feedback and additional ideas from the community regarding this proposed enhancement. Our goal is to make Day.js more intuitive and user-friendly, and community input is invaluable in achieving this.

[mirumirumi]

To address this issue while maintaining backward compatibility, I would prefer to create a new method with a different name (e.g. diffAbs()). This would be an option for developers who are new to dayjs or starting a new project. In the very distant future, diff() could be made @deprecated.

More options to the diff() method will not solve the problem if you eventually forget it, and the code will be longer.