feat(date): add ability to provide year range for past and future

[xDivisionByZerox]

Description

This PR fixes #3653.

Changes

• Add a small helper function to convert a number of years to is ms representation. This is mostly done for readability purposes.
• Extend the years argument in date.past() and date.future() to be able to provide a range
  • For the naming and JSDoc approach I took inspiration from the string module
  • year.max must be greater than years.min - this will be enforced by date.between() (the underlying implementation) as well, but I added an additional check to give a nicer error message
• Added throw tags to the JSDocs of the functions - these where previously missing even tho the functions were able to throw
• Added tests for the new behavior
  • Aligned the exist test of date.future with the one from date.past since they were more strict

Note

I quite enjoyed implementing an actual feature again. I would go ahead and implement the same feature for date.recent and date.soon in a separate PR if the team allows it.

Links

• past/future date functions to support min years #3653

[netlify]

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	c4772bf
🔍 Latest deploy log	https://app.netlify.com/projects/fakerjs/deploys/69d663876b9fde0008d0394c
😎 Deploy Preview	https://deploy-preview-3783.fakerjs.dev
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.89%. Comparing base (f4a1c3e) to head (c4772bf).
⚠️ Report is 1 commits behind head on next.

Additional details and impacted files

@@           Coverage Diff           @@
##             next    #3783   +/-   ##
=======================================
  Coverage   98.89%   98.89%           
=======================================
  Files         888      888           
  Lines        3065     3077   +12     
  Branches      556      546   -10     
=======================================
+ Hits         3031     3043   +12     
  Misses         30       30           
  Partials        4        4           

Files with missing lines	Coverage Δ
src/modules/date/index.ts	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ST-DDT]

We should apply the adjustments to recent and soon as well.

[xDivisionByZerox]

We should apply the adjustments to recent and soon as well.

As I said in the PR description, I would suggest providing an additional PR for this. Alternatively, the PR title could be extended even further.
All I want is that the concrete functions are named in the autogenerated changelog when releasing.

[ST-DDT]

As I said in the PR description, I would suggest providing an additional PR for this. Alternatively, the PR title could be extended even further.

Sorry, have missed that part of the description. Separate PR would be more clear.