feat(date): introduce anytime (#2096)

5 files changed, 76 insertions, 5 deletions

diff --git a/docs/guide/upgrading.md b/docs/guide/upgrading.md
index a4bf7da1..03d1acb9 100644
--- a/docs/guide/upgrading.md
+++ b/docs/guide/upgrading.md
@@ -308,9 +308,9 @@ faker.number.float({ max: 100, precision: 0.01 }); // 35.21
 The method `faker.datatype.array` has been deprecated and will be removed in v9.
 If you need an array of useful values, you are better off creating your own one using `faker.helpers.multiple`.
 
-### `faker.datatype.datetime` deprecated in favor of `faker.date.between`
+### `faker.datatype.datetime` deprecated in favor of `faker.date.between` and `faker.date.anytime`
 
-The `datetime` method previously found in `faker.datatype` has been deprecated, use `faker.date.between` instead.
+The `datetime` method previously found in `faker.datatype` has been deprecated, use `faker.date.between` or `faker.date.anytime` instead.
 
 ### `allowLeadingZeros` behavior change in `faker.string.numeric`
 
diff --git a/src/modules/datatype/index.ts b/src/modules/datatype/index.ts
index e776784c..0c5fddc8 100644
--- a/src/modules/datatype/index.ts
+++ b/src/modules/datatype/index.ts
@@ -166,6 +166,7 @@ export class DatatypeModule {
    *    When not provided or larger than `8640000000000000`, `2100-01-01` is considered
    *    as maximum generated date. Defaults to `4102444800000`.
    *
+   * @see faker.date.anytime()
    * @see faker.date.between()
    *
    * @example
@@ -175,7 +176,7 @@ export class DatatypeModule {
    *
    * @since 5.5.0
    *
-   * @deprecated Use `faker.date.between({ from: min, to: max })` instead.
+   * @deprecated Use `faker.date.between({ from: min, to: max })` or `faker.date.anytime()` instead.
    */
   datetime(
     options:
@@ -201,7 +202,7 @@ export class DatatypeModule {
   ): Date {
     deprecated({
       deprecated: 'faker.datatype.datetime({ min, max })',
-      proposed: 'faker.date.between({ from, to })',
+      proposed: 'faker.date.between({ from, to }) or faker.date.anytime()',
       since: '8.0',
       until: '9.0',
     });
diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index ad8be056..feac3692 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -52,6 +52,41 @@ export class DateModule {
   }
 
   /**
+   * Generates a random date that can be either in the past or in the future.
+   *
+   * @param options The optional options object.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
+   *
+   * @see faker.date.between() For dates in a specific range.
+   * @see faker.date.past() For dates explicitly in the past.
+   * @see faker.date.future() For dates explicitly in the future.
+   *
+   * @example
+   * faker.date.anytime() // '2022-07-31T01:33:29.567Z'
+   *
+   * @since 8.0.0
+   */
+  anytime(
+    options: {
+      /**
+       * The date to use as reference point for the newly generated date.
+       *
+       * @default faker.defaultRefDate()
+       */
+      refDate?: string | Date | number;
+    } = {}
+  ): Date {
+    const { refDate } = options;
+
+    const date = toDate(refDate, this.faker.defaultRefDate);
+
+    return this.between({
+      from: new Date(date.getTime() - 1000 * 60 * 60 * 24 * 365),
+      to: new Date(date.getTime() + 1000 * 60 * 60 * 24 * 365),
+    });
+  }
+
+  /**
    * Generates a random date in the past.
    *
    * @param options The optional options object.
diff --git a/test/__snapshots__/date.spec.ts.snap b/test/__snapshots__/date.spec.ts.snap
index a42c8786..701c8cc7 100644
--- a/test/__snapshots__/date.spec.ts.snap
+++ b/test/__snapshots__/date.spec.ts.snap
@@ -1,5 +1,11 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`date > 42 > anytime > with only Date refDate 1`] = `2020-11-22T03:05:49.801Z`;
+
+exports[`date > 42 > anytime > with only number refDate 1`] = `2020-11-22T03:05:49.801Z`;
+
+exports[`date > 42 > anytime > with only string refDate 1`] = `2020-11-22T03:05:49.801Z`;
+
 exports[`date > 42 > between > with Date dates 1`] = `2021-03-15T19:30:57.091Z`;
 
 exports[`date > 42 > between > with mixed dates 1`] = `2021-03-15T19:30:57.091Z`;
@@ -121,6 +127,12 @@ exports[`date > 42 > weekday > with abbreviated = true and context = true 1`] =
 
 exports[`date > 42 > weekday > with context = true 1`] = `"Tuesday"`;
 
+exports[`date > 1211 > anytime > with only Date refDate 1`] = `2021-12-31T12:49:38.848Z`;
+
+exports[`date > 1211 > anytime > with only number refDate 1`] = `2021-12-31T12:49:38.848Z`;
+
+exports[`date > 1211 > anytime > with only string refDate 1`] = `2021-12-31T12:49:38.848Z`;
+
 exports[`date > 1211 > between > with Date dates 1`] = `2021-04-17T11:58:13.327Z`;
 
 exports[`date > 1211 > between > with mixed dates 1`] = `2021-04-17T11:58:13.327Z`;
@@ -243,6 +255,12 @@ exports[`date > 1211 > weekday > with abbreviated = true and context = true 1`]
 
 exports[`date > 1211 > weekday > with context = true 1`] = `"Saturday"`;
 
+exports[`date > 1337 > anytime > with only Date refDate 1`] = `2020-08-31T23:49:36.088Z`;
+
+exports[`date > 1337 > anytime > with only number refDate 1`] = `2020-08-31T23:49:36.088Z`;
+
+exports[`date > 1337 > anytime > with only string refDate 1`] = `2020-08-31T23:49:36.088Z`;
+
 exports[`date > 1337 > between > with Date dates 1`] = `2021-03-09T04:11:24.667Z`;
 
 exports[`date > 1337 > between > with mixed dates 1`] = `2021-03-09T04:11:24.667Z`;
diff --git a/test/date.spec.ts b/test/date.spec.ts
index bfa01e7d..d456b53c 100644
--- a/test/date.spec.ts
+++ b/test/date.spec.ts
@@ -13,6 +13,14 @@ const refDate = '2021-02-21T17:09:15.711Z';
 
 describe('date', () => {
   seededTests(faker, 'date', (t) => {
+    t.describe('anytime', (t) => {
+      t.it('with only string refDate', { refDate })
+        .it('with only Date refDate', { refDate: new Date(refDate) })
+        .it('with only number refDate', {
+          refDate: new Date(refDate).getTime(),
+        });
+    });
+
     t.describeEach(
       'past',
       'future'
@@ -188,12 +196,21 @@ describe('date', () => {
       });
 
       // No changes to these methods
-      t.skip('birthdate').skip('month').skip('weekday');
+      t.skip('anytime').skip('birthdate').skip('month').skip('weekday');
     });
   });
 
   describe(`random seeded tests for seed ${faker.seed()}`, () => {
     for (let i = 1; i <= NON_SEEDED_BASED_RUN; i++) {
+      describe('anytime()', () => {
+        it('should return a date', () => {
+          const actual = faker.date.anytime();
+
+          expect(actual).toBeDefined();
+          expect(actual).toBeInstanceOf(Date);
+        });
+      });
+
       describe('past()', () => {
         it('should return a date 5 years in the past', () => {
           const today = new Date();