refactor(date)!: unify signatures (#1534)

Co-authored-by: Eric Cheng <[email protected]>

4 files changed, 978 insertions, 78 deletions

diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index 673f0e33..a76b430f 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -1,10 +1,11 @@
 import type { Faker } from '../..';
 import type { DateEntryDefinition } from '../../definitions';
 import { FakerError } from '../../errors/faker-error';
+import { deprecated } from '../../internal/deprecated';
 
 /**
  * Converts date passed as a string, number or Date to a Date object.
- * If nothing or a non parseable value is passed, takes current date.
+ * If nothing or a non parsable value is passed, takes current date.
  *
  * @param date Date
  */
@@ -34,6 +35,23 @@ export class DateModule {
   /**
    * Generates a random date in the past.
    *
+   * @param options The optional options object.
+   * @param options.years The range of years the date may be in the past. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   *
+   * @see faker.date.recent()
+   *
+   * @example
+   * faker.date.past() // '2021-12-03T05:40:44.408Z'
+   * faker.date.past({ years: 10 }) // '2017-10-25T21:34:19.488Z'
+   * faker.date.past({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2017-08-18T02:59:12.350Z'
+   *
+   * @since 8.0.0
+   */
+  past(options?: { years?: number; refDate?: string | Date | number }): Date;
+  /**
+   * Generates a random date in the past.
+   *
    * @param years The range of years the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
@@ -45,8 +63,57 @@ export class DateModule {
    * faker.date.past(10, '2020-01-01T00:00:00.000Z') // '2017-08-18T02:59:12.350Z'
    *
    * @since 2.0.1
+   *
+   * @deprecated Use `faker.date.past({ years, refDate })` instead.
    */
-  past(years?: number, refDate?: string | Date | number): Date {
+  past(years?: number, refDate?: string | Date | number): Date;
+  /**
+   * Generates a random date in the past.
+   *
+   * @param options The optional options object.
+   * @param options.years The range of years the date may be in the past. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   * @param legacyRefDate Deprecated, use `options.refDate` instead.
+   *
+   * @see faker.date.recent()
+   *
+   * @example
+   * faker.date.past() // '2021-12-03T05:40:44.408Z'
+   * faker.date.past({ years: 10 }) // '2017-10-25T21:34:19.488Z'
+   * faker.date.past({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2017-08-18T02:59:12.350Z'
+   *
+   * @since 8.0.0
+   */
+  past(
+    options?:
+      | number
+      | {
+          years?: number;
+          refDate?: string | Date | number;
+        },
+    legacyRefDate?: string | Date | number
+  ): Date;
+  past(
+    options:
+      | number
+      | {
+          years?: number;
+          refDate?: string | Date | number;
+        } = {},
+    legacyRefDate?: string | Date | number
+  ): Date {
+    if (typeof options === 'number') {
+      deprecated({
+        deprecated: 'faker.date.past(years, refDate)',
+        proposed: 'faker.date.past({ years, refDate })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { years: options };
+    }
+
+    const { years = 1, refDate = legacyRefDate } = options;
+
     if (years <= 0) {
       throw new FakerError('Years must be greater than 0.');
     }
@@ -54,7 +121,7 @@ export class DateModule {
     const date = toDate(refDate);
     const range = {
       min: 1000,
-      max: (years ?? 1) * 365 * 24 * 3600 * 1000,
+      max: years * 365 * 24 * 3600 * 1000,
     };
 
     let past = date.getTime();
@@ -67,6 +134,23 @@ export class DateModule {
   /**
    * Generates a random date in the future.
    *
+   * @param options The optional options object.
+   * @param options.years The range of years the date may be in the future. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   *
+   * @see faker.date.soon()
+   *
+   * @example
+   * faker.date.future() // '2022-11-19T05:52:49.100Z'
+   * faker.date.future({ years: 10 }) // '2030-11-23T09:38:28.710Z'
+   * faker.date.future({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-12-13T22:45:10.252Z'
+   *
+   * @since 8.0.0
+   */
+  future(options?: { years?: number; refDate?: string | Date | number }): Date;
+  /**
+   * Generates a random date in the future.
+   *
    * @param years The range of years the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
@@ -78,8 +162,57 @@ export class DateModule {
    * faker.date.future(10, '2020-01-01T00:00:00.000Z') // '2020-12-13T22:45:10.252Z'
    *
    * @since 2.0.1
+   *
+   * @deprecated Use `faker.date.future({ years, refDate })` instead.
+   */
+  future(years?: number, refDate?: string | Date | number): Date;
+  /**
+   * Generates a random date in the future.
+   *
+   * @param options The optional options object.
+   * @param options.years The range of years the date may be in the future. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   * @param legacyRefDate Deprecated, use `options.refDate` instead.
+   *
+   * @see faker.date.soon()
+   *
+   * @example
+   * faker.date.future() // '2022-11-19T05:52:49.100Z'
+   * faker.date.future({ years: 10 }) // '2030-11-23T09:38:28.710Z'
+   * faker.date.future({ years: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-12-13T22:45:10.252Z'
+   *
+   * @since 8.0.0
    */
-  future(years?: number, refDate?: string | Date | number): Date {
+  future(
+    options?:
+      | number
+      | {
+          years?: number;
+          refDate?: string | Date | number;
+        },
+    legacyRefDate?: string | Date | number
+  ): Date;
+  future(
+    options:
+      | number
+      | {
+          years?: number;
+          refDate?: string | Date | number;
+        } = {},
+    legacyRefDate?: string | Date | number
+  ): Date {
+    if (typeof options === 'number') {
+      deprecated({
+        deprecated: 'faker.date.future(years, refDate)',
+        proposed: 'faker.date.future({ years, refDate })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { years: options };
+    }
+
+    const { years = 1, refDate = legacyRefDate } = options;
+
     if (years <= 0) {
       throw new FakerError('Years must be greater than 0.');
     }
@@ -87,7 +220,7 @@ export class DateModule {
     const date = toDate(refDate);
     const range = {
       min: 1000,
-      max: (years ?? 1) * 365 * 24 * 3600 * 1000,
+      max: years * 365 * 24 * 3600 * 1000,
     };
 
     let future = date.getTime();
@@ -100,6 +233,22 @@ export class DateModule {
   /**
    * Generates a random date between the given boundaries.
    *
+   * @param options The optional options object.
+   * @param options.from The early date boundary.
+   * @param options.to The late date boundary.
+   *
+   * @example
+   * faker.date.between({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' }) // '2026-05-16T02:22:53.002Z'
+   *
+   * @since 8.0.0
+   */
+  between(options: {
+    from: string | Date | number;
+    to: string | Date | number;
+  }): Date;
+  /**
+   * Generates a random date between the given boundaries.
+   *
    * @param from The early date boundary.
    * @param to The late date boundary.
    *
@@ -107,8 +256,57 @@ export class DateModule {
    * faker.date.between('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z') // '2026-05-16T02:22:53.002Z'
    *
    * @since 2.0.1
+   *
+   * @deprecated Use `faker.date.between({ from, to })` instead.
+   */
+  between(from: string | Date | number, to: string | Date | number): Date;
+  /**
+   * Generates a random date between the given boundaries.
+   *
+   * @param options The optional options object.
+   * @param options.from The early date boundary.
+   * @param options.to The late date boundary.
+   * @param legacyTo Deprecated, use `options.to` instead.
+   *
+   * @example
+   * faker.date.between({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' }) // '2026-05-16T02:22:53.002Z'
+   *
+   * @since 8.0.0
    */
-  between(from: string | Date | number, to: string | Date | number): Date {
+  between(
+    options:
+      | string
+      | Date
+      | number
+      | {
+          from: string | Date | number;
+          to: string | Date | number;
+        },
+    legacyTo?: string | Date | number
+  ): Date;
+  between(
+    options:
+      | string
+      | Date
+      | number
+      | {
+          from: string | Date | number;
+          to: string | Date | number;
+        },
+    legacyTo?: string | Date | number
+  ): Date {
+    if (typeof options !== 'object' || options instanceof Date) {
+      deprecated({
+        deprecated: 'faker.date.between(from, to)',
+        proposed: 'faker.date.between({ from, to })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { from: options, to: legacyTo };
+    }
+
+    const { from, to } = options;
+
     const fromMs = toDate(from).getTime();
     const toMs = toDate(to).getTime();
     const dateOffset = this.faker.number.int(toMs - fromMs);
@@ -117,11 +315,36 @@ export class DateModule {
   }
 
   /**
-   * Generates n random dates between the given boundaries.
+   * Generates random dates between the given boundaries.
+   *
+   * @param options The optional options object.
+   * @param options.from The early date boundary.
+   * @param options.to The late date boundary.
+   * @param options.count The number of dates to generate. Defaults to `3`.
+   *
+   * @example
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' })
+   * // [
+   * //   2022-07-02T06:00:00.000Z,
+   * //   2024-12-31T12:00:00.000Z,
+   * //   2027-07-02T18:00:00.000Z
+   * // ]
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: 2 })
+   * // [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]
+   *
+   * @since 8.0.0
+   */
+  betweens(options: {
+    from: string | Date | number;
+    to: string | Date | number;
+    count?: number;
+  }): Date[];
+  /**
+   * Generates random dates between the given boundaries.
    *
    * @param from The early date boundary.
    * @param to The late date boundary.
-   * @param num The number of dates to generate. Defaults to `3`.
+   * @param count The number of dates to generate. Defaults to `3`.
    *
    * @example
    * faker.date.betweens('2020-01-01T00:00:00.000Z', '2030-01-01T00:00:00.000Z')
@@ -134,24 +357,99 @@ export class DateModule {
    * // [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]
    *
    * @since 5.4.0
+   *
+   * @deprecated Use `faker.date.betweens({ from, to, count })` instead.
    */
   betweens(
     from: string | Date | number,
     to: string | Date | number,
-    num: number = 3
+    count?: number
+  ): Date[];
+  /**
+   * Generates random dates between the given boundaries.
+   *
+   * @param options The optional options object.
+   * @param options.from The early date boundary.
+   * @param options.to The late date boundary.
+   * @param options.count The number of dates to generate. Defaults to `3`.
+   * @param legacyTo Deprecated, use `options.to` instead.
+   * @param legacyCount Deprecated, use `options.count` instead.
+   *
+   * @example
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' })
+   * // [
+   * //   2022-07-02T06:00:00.000Z,
+   * //   2024-12-31T12:00:00.000Z,
+   * //   2027-07-02T18:00:00.000Z
+   * // ]
+   * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z', count: 2 })
+   * // [ 2023-05-02T16:00:00.000Z, 2026-09-01T08:00:00.000Z ]
+   *
+   * @since 8.0.0
+   */
+  betweens(
+    options:
+      | string
+      | Date
+      | number
+      | {
+          from: string | Date | number;
+          to: string | Date | number;
+          count?: number;
+        },
+    legacyTo?: string | Date | number,
+    legacyCount?: number
+  ): Date[];
+  betweens(
+    options:
+      | string
+      | Date
+      | number
+      | {
+          from: string | Date | number;
+          to: string | Date | number;
+          count?: number;
+        },
+    legacyTo?: string | Date | number,
+    legacyCount: number = 3
   ): Date[] {
-    const dates: Date[] = [];
-
-    while (dates.length < num) {
-      dates.push(this.between(from, to));
+    if (typeof options !== 'object' || options instanceof Date) {
+      deprecated({
+        deprecated: 'faker.date.betweens(from, to, count)',
+        proposed: 'faker.date.betweens({ from, to, count })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { from: options, to: legacyTo, count: legacyCount };
     }
 
-    return dates.sort((a, b) => a.getTime() - b.getTime());
+    const { from, to, count = 3 } = options;
+
+    return Array.from({ length: count }, () => this.between({ from, to })).sort(
+      (a, b) => a.getTime() - b.getTime()
+    );
   }
 
   /**
    * Generates a random date in the recent past.
    *
+   * @param options The optional options object.
+   * @param options.days The range of days the date may be in the past. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   *
+   * @see faker.date.past()
+   *
+   * @example
+   * faker.date.recent() // '2022-02-04T02:09:35.077Z'
+   * faker.date.recent({ days: 10 }) // '2022-01-29T06:12:12.829Z'
+   * faker.date.recent({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2019-12-27T18:11:19.117Z'
+   *
+   * @since 8.0.0
+   */
+  recent(options?: { days?: number; refDate?: string | Date | number }): Date;
+  /**
+   * Generates a random date in the recent past.
+   *
    * @param days The range of days the date may be in the past. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
@@ -163,8 +461,47 @@ export class DateModule {
    * faker.date.recent(10, '2020-01-01T00:00:00.000Z') // '2019-12-27T18:11:19.117Z'
    *
    * @since 2.0.1
+   *
+   * @deprecated Use `faker.date.recent({ days, refDate })` instead.
+   */
+  recent(days?: number, refDate?: string | Date | number): Date;
+  /**
+   * Generates a random date in the recent past.
+   *
+   * @param options The optional options object.
+   * @param options.days The range of days the date may be in the past. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   * @param legacyRefDate Deprecated, use `options.refDate` instead.
+   *
+   * @see faker.date.past()
+   *
+   * @example
+   * faker.date.recent() // '2022-02-04T02:09:35.077Z'
+   * faker.date.recent({ days: 10 }) // '2022-01-29T06:12:12.829Z'
+   * faker.date.recent({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2019-12-27T18:11:19.117Z'
+   *
+   * @since 8.0.0
    */
-  recent(days?: number, refDate?: string | Date | number): Date {
+  recent(
+    options?: number | { days?: number; refDate?: string | Date | number },
+    legacyRefDate?: string | Date | number
+  ): Date;
+  recent(
+    options: number | { days?: number; refDate?: string | Date | number } = {},
+    legacyRefDate?: string | Date | number
+  ): Date {
+    if (typeof options === 'number') {
+      deprecated({
+        deprecated: 'faker.date.recent(days, refDate)',
+        proposed: 'faker.date.recent({ days, refDate })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { days: options };
+    }
+
+    const { days = 1, refDate = legacyRefDate } = options;
+
     if (days <= 0) {
       throw new FakerError('Days must be greater than 0.');
     }
@@ -172,7 +509,7 @@ export class DateModule {
     const date = toDate(refDate);
     const range = {
       min: 1000,
-      max: (days ?? 1) * 24 * 3600 * 1000,
+      max: days * 24 * 3600 * 1000,
     };
 
     let future = date.getTime();
@@ -185,6 +522,23 @@ export class DateModule {
   /**
    * Generates a random date in the near future.
    *
+   * @param options The optional options object.
+   * @param options.days The range of days the date may be in the future. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   *
+   * @see faker.date.future()
+   *
+   * @example
+   * faker.date.soon() // '2022-02-05T09:55:39.216Z'
+   * faker.date.soon({ days: 10 }) // '2022-02-11T05:14:39.138Z'
+   * faker.date.soon({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-01-01T02:40:44.990Z'
+   *
+   * @since 8.0.0
+   */
+  soon(options?: { days?: number; refDate?: string | Date | number }): Date;
+  /**
+   * Generates a random date in the near future.
+   *
    * @param days The range of days the date may be in the future. Defaults to `1`.
    * @param refDate The date to use as reference point for the newly generated date. Defaults to now.
    *
@@ -196,8 +550,47 @@ export class DateModule {
    * faker.date.soon(10, '2020-01-01T00:00:00.000Z') // '2020-01-01T02:40:44.990Z'
    *
    * @since 5.0.0
+   *
+   * @deprecated Use `faker.date.soon({ days, refDate })` instead.
+   */
+  soon(days?: number, refDate?: string | Date | number): Date;
+  /**
+   * Generates a random date in the near future.
+   *
+   * @param options The optional options object.
+   * @param options.days The range of days the date may be in the future. Defaults to `1`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to now.
+   * @param legacyRefDate Deprecated, use `options.refDate` instead.
+   *
+   * @see faker.date.future()
+   *
+   * @example
+   * faker.date.soon() // '2022-02-05T09:55:39.216Z'
+   * faker.date.soon({ days: 10 }) // '2022-02-11T05:14:39.138Z'
+   * faker.date.soon({ days: 10, refDate: '2020-01-01T00:00:00.000Z' }) // '2020-01-01T02:40:44.990Z'
+   *
+   * @since 8.0.0
    */
-  soon(days?: number, refDate?: string | Date | number): Date {
+  soon(
+    options?: number | { days?: number; refDate?: string | Date | number },
+    legacyRefDate?: string | Date | number
+  ): Date;
+  soon(
+    options: number | { days?: number; refDate?: string | Date | number } = {},
+    legacyRefDate?: string | Date | number
+  ): Date {
+    if (typeof options === 'number') {
+      deprecated({
+        deprecated: 'faker.date.soon(days, refDate)',
+        proposed: 'faker.date.soon({ days, refDate })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = { days: options };
+    }
+
+    const { days = 1, refDate = legacyRefDate } = options;
+
     if (days <= 0) {
       throw new FakerError('Days must be greater than 0.');
     }
@@ -205,7 +598,7 @@ export class DateModule {
     const date = toDate(refDate);
     const range = {
       min: 1000,
-      max: (days ?? 1) * 24 * 3600 * 1000,
+      max: days * 24 * 3600 * 1000,
     };
 
     let future = date.getTime();
diff --git a/src/modules/git/index.ts b/src/modules/git/index.ts
index 2ea65063..31df2518 100644
--- a/src/modules/git/index.ts
+++ b/src/modules/git/index.ts
@@ -136,7 +136,7 @@ export class GitModule {
     const { refDate } = options;
 
     const dateParts = GIT_DATE_FORMAT_BASE.format(
-      this.faker.date.recent(1, refDate)
+      this.faker.date.recent({ days: 1, refDate })
     )
       .replace(/,/g, '')
       .split(' ');
diff --git a/test/__snapshots__/date.spec.ts.snap b/test/__snapshots__/date.spec.ts.snap
index 9969cf73..8ac619a9 100644
--- a/test/__snapshots__/date.spec.ts.snap
+++ b/test/__snapshots__/date.spec.ts.snap
@@ -2,6 +2,8 @@
 
 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`;
+
 exports[`date > 42 > between > with string dates 1`] = `2021-03-15T19:30:57.091Z`;
 
 exports[`date > 42 > betweens > with Date dates 1`] = `
@@ -22,6 +24,14 @@ exports[`date > 42 > betweens > with Date dates and count 1`] = `
 ]
 `;
 
+exports[`date > 42 > betweens > with mixed dates 1`] = `
+[
+  2021-03-15T19:30:57.091Z,
+  2021-04-09T17:05:10.406Z,
+  2021-04-18T19:23:52.973Z,
+]
+`;
+
 exports[`date > 42 > betweens > with string dates 1`] = `
 [
   2021-03-15T19:30:57.091Z,
@@ -104,6 +114,8 @@ exports[`date > 42 > weekday > with context = true 1`] = `"Tuesday"`;
 
 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`;
+
 exports[`date > 1211 > between > with string dates 1`] = `2021-04-17T11:58:13.327Z`;
 
 exports[`date > 1211 > betweens > with Date dates 1`] = `
@@ -124,6 +136,14 @@ exports[`date > 1211 > betweens > with Date dates and count 1`] = `
 ]
 `;
 
+exports[`date > 1211 > betweens > with mixed dates 1`] = `
+[
+  2021-03-20T19:08:07.621Z,
+  2021-04-15T10:20:25.794Z,
+  2021-04-17T11:58:13.327Z,
+]
+`;
+
 exports[`date > 1211 > betweens > with string dates 1`] = `
 [
   2021-03-20T19:08:07.621Z,
@@ -206,6 +226,8 @@ exports[`date > 1211 > weekday > with context = true 1`] = `"Saturday"`;
 
 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`;
+
 exports[`date > 1337 > between > with string dates 1`] = `2021-03-09T04:11:24.667Z`;
 
 exports[`date > 1337 > betweens > with Date dates 1`] = `
@@ -226,6 +248,14 @@ exports[`date > 1337 > betweens > with Date dates and count 1`] = `
 ]
 `;
 
+exports[`date > 1337 > betweens > with mixed dates 1`] = `
+[
+  2021-03-03T01:51:22.512Z,
+  2021-03-09T04:11:24.667Z,
+  2021-03-26T18:53:00.564Z,
+]
+`;
+
 exports[`date > 1337 > betweens > with string dates 1`] = `
 [
   2021-03-03T01:51:22.512Z,
@@ -305,3 +335,219 @@ exports[`date > 1337 > weekday > with abbr = true 1`] = `"Mon"`;
 exports[`date > 1337 > weekday > with abbr = true and context = true 1`] = `"Mon"`;
 
 exports[`date > 1337 > weekday > with context = true 1`] = `"Monday"`;
+
+exports[`date > deprecated > 42 > between > with Date dates 1`] = `2021-03-15T19:30:57.091Z`;
+
+exports[`date > deprecated > 42 > between > with string dates 1`] = `2021-03-15T19:30:57.091Z`;
+
+exports[`date > deprecated > 42 > betweens > with Date dates 1`] = `
+[
+  2021-03-15T19:30:57.091Z,
+  2021-04-09T17:05:10.406Z,
+  2021-04-18T19:23:52.973Z,
+]
+`;
+
+exports[`date > deprecated > 42 > betweens > with Date dates and count 1`] = `
+[
+  2021-03-04T12:54:15.263Z,
+  2021-03-15T19:30:57.091Z,
+  2021-04-05T21:40:57.315Z,
+  2021-04-09T17:05:10.406Z,
+  2021-04-18T19:23:52.973Z,
+]
+`;
+
+exports[`date > deprecated > 42 > betweens > with string dates 1`] = `
+[
+  2021-03-15T19:30:57.091Z,
+  2021-04-09T17:05:10.406Z,
+  2021-04-18T19:23:52.973Z,
+]
+`;
+
+exports[`date > deprecated > 42 > betweens > with string dates and count 1`] = `
+[
+  2021-03-04T12:54:15.263Z,
+  2021-03-15T19:30:57.091Z,
+  2021-04-05T21:40:57.315Z,
+  2021-04-09T17:05:10.406Z,
+  2021-04-18T19:23:52.973Z,
+]
+`;
+
+exports[`date > deprecated > 42 > future > with only Date refDate 1`] = `2021-07-08T10:07:33.381Z`;
+
+exports[`date > deprecated > 42 > future > with only number refDate 1`] = `2021-07-08T10:07:33.381Z`;
+
+exports[`date > deprecated > 42 > future > with only string refDate 1`] = `2021-07-08T10:07:33.381Z`;
+
+exports[`date > deprecated > 42 > future > with value 1`] = `2024-11-19T18:52:06.785Z`;
+
+exports[`date > deprecated > 42 > past > with only Date refDate 1`] = `2020-10-08T00:10:58.041Z`;
+
+exports[`date > deprecated > 42 > past > with only number refDate 1`] = `2020-10-08T00:10:58.041Z`;
+
+exports[`date > deprecated > 42 > past > with only string refDate 1`] = `2020-10-08T00:10:58.041Z`;
+
+exports[`date > deprecated > 42 > past > with value 1`] = `2017-05-26T15:26:24.637Z`;
+
+exports[`date > deprecated > 42 > recent > with only Date refDate 1`] = `2021-02-21T08:09:54.820Z`;
+
+exports[`date > deprecated > 42 > recent > with only number refDate 1`] = `2021-02-21T08:09:54.820Z`;
+
+exports[`date > deprecated > 42 > recent > with only string refDate 1`] = `2021-02-21T08:09:54.820Z`;
+
+exports[`date > deprecated > 42 > recent > with value 1`] = `2021-02-17T23:15:52.427Z`;
+
+exports[`date > deprecated > 42 > soon > with only Date refDate 1`] = `2021-02-22T02:08:36.602Z`;
+
+exports[`date > deprecated > 42 > soon > with only number refDate 1`] = `2021-02-22T02:08:36.602Z`;
+
+exports[`date > deprecated > 42 > soon > with only string refDate 1`] = `2021-02-22T02:08:36.602Z`;
+
+exports[`date > deprecated > 42 > soon > with value 1`] = `2021-02-25T11:02:38.995Z`;
+
+exports[`date > deprecated > 1211 > between > with Date dates 1`] = `2021-04-17T11:58:13.327Z`;
+
+exports[`date > deprecated > 1211 > between > with string dates 1`] = `2021-04-17T11:58:13.327Z`;
+
+exports[`date > deprecated > 1211 > betweens > with Date dates 1`] = `
+[
+  2021-03-20T19:08:07.621Z,
+  2021-04-15T10:20:25.794Z,
+  2021-04-17T11:58:13.327Z,
+]
+`;
+
+exports[`date > deprecated > 1211 > betweens > with Date dates and count 1`] = `
+[
+  2021-03-07T00:34:12.770Z,
+  2021-03-20T19:08:07.621Z,
+  2021-04-08T15:12:37.581Z,
+  2021-04-15T10:20:25.794Z,
+  2021-04-17T11:58:13.327Z,
+]
+`;
+
+exports[`date > deprecated > 1211 > betweens > with string dates 1`] = `
+[
+  2021-03-20T19:08:07.621Z,
+  2021-04-15T10:20:25.794Z,
+  2021-04-17T11:58:13.327Z,
+]
+`;
+
+exports[`date > deprecated > 1211 > betweens > with string dates and count 1`] = `
+[
+  2021-03-07T00:34:12.770Z,
+  2021-03-20T19:08:07.621Z,
+  2021-04-08T15:12:37.581Z,
+  2021-04-15T10:20:25.794Z,
+  2021-04-17T11:58:13.327Z,
+]
+`;
+
+exports[`date > deprecated > 1211 > future > with only Date refDate 1`] = `2022-01-26T14:59:27.351Z`;
+
+exports[`date > deprecated > 1211 > future > with only number refDate 1`] = `2022-01-26T14:59:27.351Z`;
+
+exports[`date > deprecated > 1211 > future > with only string refDate 1`] = `2022-01-26T14:59:27.351Z`;
+
+exports[`date > deprecated > 1211 > future > with value 1`] = `2030-06-03T19:31:11.467Z`;
+
+exports[`date > deprecated > 1211 > past > with only Date refDate 1`] = `2020-03-19T19:19:04.071Z`;
+
+exports[`date > deprecated > 1211 > past > with only number refDate 1`] = `2020-03-19T19:19:04.071Z`;
+
+exports[`date > deprecated > 1211 > past > with only string refDate 1`] = `2020-03-19T19:19:04.071Z`;
+
+exports[`date > deprecated > 1211 > past > with value 1`] = `2011-11-12T14:47:19.955Z`;
+
+exports[`date > deprecated > 1211 > recent > with only Date refDate 1`] = `2021-02-20T18:52:11.498Z`;
+
+exports[`date > deprecated > 1211 > recent > with only number refDate 1`] = `2021-02-20T18:52:11.498Z`;
+
+exports[`date > deprecated > 1211 > recent > with only string refDate 1`] = `2021-02-20T18:52:11.498Z`;
+
+exports[`date > deprecated > 1211 > recent > with value 1`] = `2021-02-12T10:18:34.226Z`;
+
+exports[`date > deprecated > 1211 > soon > with only Date refDate 1`] = `2021-02-22T15:26:19.924Z`;
+
+exports[`date > deprecated > 1211 > soon > with only number refDate 1`] = `2021-02-22T15:26:19.924Z`;
+
+exports[`date > deprecated > 1211 > soon > with only string refDate 1`] = `2021-02-22T15:26:19.924Z`;
+
+exports[`date > deprecated > 1211 > soon > with value 1`] = `2021-03-02T23:59:57.196Z`;
+
+exports[`date > deprecated > 1337 > between > with Date dates 1`] = `2021-03-09T04:11:24.667Z`;
+
+exports[`date > deprecated > 1337 > between > with string dates 1`] = `2021-03-09T04:11:24.667Z`;
+
+exports[`date > deprecated > 1337 > betweens > with Date dates 1`] = `
+[
+  2021-03-03T01:51:22.512Z,
+  2021-03-09T04:11:24.667Z,
+  2021-03-26T18:53:00.564Z,
+]
+`;
+
+exports[`date > deprecated > 1337 > betweens > with Date dates and count 1`] = `
+[
+  2021-03-03T01:51:22.512Z,
+  2021-03-06T06:11:08.446Z,
+  2021-03-09T04:11:24.667Z,
+  2021-03-10T02:59:27.376Z,
+  2021-03-26T18:53:00.564Z,
+]
+`;
+
+exports[`date > deprecated > 1337 > betweens > with string dates 1`] = `
+[
+  2021-03-03T01:51:22.512Z,
+  2021-03-09T04:11:24.667Z,
+  2021-03-26T18:53:00.564Z,
+]
+`;
+
+exports[`date > deprecated > 1337 > betweens > with string dates and count 1`] = `
+[
+  2021-03-03T01:51:22.512Z,
+  2021-03-06T06:11:08.446Z,
+  2021-03-09T04:11:24.667Z,
+  2021-03-10T02:59:27.376Z,
+  2021-03-26T18:53:00.564Z,
+]
+`;
+
+exports[`date > deprecated > 1337 > future > with only Date refDate 1`] = `2021-05-28T08:29:26.637Z`;
+
+exports[`date > deprecated > 1337 > future > with only number refDate 1`] = `2021-05-28T08:29:26.637Z`;
+
+exports[`date > deprecated > 1337 > future > with only string refDate 1`] = `2021-05-28T08:29:26.637Z`;
+
+exports[`date > deprecated > 1337 > future > with value 1`] = `2023-10-06T02:30:58.333Z`;
+
+exports[`date > deprecated > 1337 > past > with only Date refDate 1`] = `2020-11-18T01:49:04.785Z`;
+
+exports[`date > deprecated > 1337 > past > with only number refDate 1`] = `2020-11-18T01:49:04.785Z`;
+
+exports[`date > deprecated > 1337 > past > with only string refDate 1`] = `2020-11-18T01:49:04.785Z`;
+
+exports[`date > deprecated > 1337 > past > with value 1`] = `2018-07-11T07:47:33.089Z`;
+
+exports[`date > deprecated > 1337 > recent > with only Date refDate 1`] = `2021-02-21T10:51:56.041Z`;
+
+exports[`date > deprecated > 1337 > recent > with only number refDate 1`] = `2021-02-21T10:51:56.041Z`;
+
+exports[`date > deprecated > 1337 > recent > with only string refDate 1`] = `2021-02-21T10:51:56.041Z`;
+
+exports[`date > deprecated > 1337 > recent > with value 1`] = `2021-02-19T02:16:05.653Z`;
+
+exports[`date > deprecated > 1337 > soon > with only Date refDate 1`] = `2021-02-21T23:26:35.381Z`;
+
+exports[`date > deprecated > 1337 > soon > with only number refDate 1`] = `2021-02-21T23:26:35.381Z`;
+
+exports[`date > deprecated > 1337 > soon > with only string refDate 1`] = `2021-02-21T23:26:35.381Z`;
+
+exports[`date > deprecated > 1337 > soon > with value 1`] = `2021-02-24T08:02:25.769Z`;
diff --git a/test/date.spec.ts b/test/date.spec.ts
index 365e2cab..d4436951 100644
--- a/test/date.spec.ts
+++ b/test/date.spec.ts
@@ -19,14 +19,26 @@ describe('date', () => {
   seededTests(faker, 'date', (t) => {
     t.describeEach(
       'past',
-      'recent',
-      'soon',
       'future'
     )((t) => {
-      t.it('with only string refDate', undefined, refDate)
-        .it('with only Date refDate', undefined, new Date(refDate))
-        .it('with value', 10, refDate)
-        .it('with only number refDate', undefined, new Date(refDate).getTime());
+      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(),
+        })
+        .it('with value', { years: 10, refDate });
+    });
+
+    t.describeEach(
+      'recent',
+      'soon'
+    )((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(),
+        })
+        .it('with value', { days: 10, refDate });
     });
 
     t.describeEach(
@@ -43,40 +55,43 @@ describe('date', () => {
     });
 
     t.describe('between', (t) => {
-      t.it(
-        'with string dates',
-        '2021-02-21T17:09:15.711Z',
-        '2021-04-21T17:11:17.711Z'
-      ).it(
-        'with Date dates',
-        new Date('2021-02-21T17:09:15.711Z'),
-        new Date('2021-04-21T17:11:17.711Z')
-      );
+      t.it('with string dates', {
+        from: '2021-02-21T17:09:15.711Z',
+        to: '2021-04-21T17:11:17.711Z',
+      })
+        .it('with Date dates', {
+          from: new Date('2021-02-21T17:09:15.711Z'),
+          to: new Date('2021-04-21T17:11:17.711Z'),
+        })
+        .it('with mixed dates', {
+          from: '2021-02-21T17:09:15.711Z',
+          to: new Date('2021-04-21T17:11:17.711Z'),
+        });
     });
 
     t.describe('betweens', (t) => {
-      t.it(
-        'with string dates',
-        '2021-02-21T17:09:15.711Z',
-        '2021-04-21T17:11:17.711Z'
-      )
-        .it(
-          'with Date dates',
-          new Date('2021-02-21T17:09:15.711Z'),
-          new Date('2021-04-21T17:11:17.711Z')
-        )
-        .it(
-          'with string dates and count',
-          '2021-02-21T17:09:15.711Z',
-          '2021-04-21T17:11:17.711Z',
-          5
-        )
-        .it(
-          'with Date dates and count',
-          new Date('2021-02-21T17:09:15.711Z'),
-          new Date('2021-04-21T17:11:17.711Z'),
-          5
-        );
+      t.it('with string dates', {
+        from: '2021-02-21T17:09:15.711Z',
+        to: '2021-04-21T17:11:17.711Z',
+      })
+        .it('with Date dates', {
+          from: new Date('2021-02-21T17:09:15.711Z'),
+          to: new Date('2021-04-21T17:11:17.711Z'),
+        })
+        .it('with mixed dates', {
+          from: '2021-02-21T17:09:15.711Z',
+          to: new Date('2021-04-21T17:11:17.711Z'),
+        })
+        .it('with string dates and count', {
+          from: '2021-02-21T17:09:15.711Z',
+          to: '2021-04-21T17:11:17.711Z',
+          count: 5,
+        })
+        .it('with Date dates and count', {
+          from: new Date('2021-02-21T17:09:15.711Z'),
+          to: new Date('2021-04-21T17:11:17.711Z'),
+          count: 5,
+        });
     });
 
     t.describe('birthdate', (t) => {
@@ -116,6 +131,66 @@ describe('date', () => {
     });
   });
 
+  describe('deprecated', () => {
+    seededTests(faker, 'date', (t) => {
+      t.describeEach(
+        'past',
+        'recent',
+        'soon',
+        'future'
+      )((t) => {
+        t.it('with only string refDate', undefined, refDate)
+          .it('with only Date refDate', undefined, new Date(refDate))
+          .it(
+            'with only number refDate',
+            undefined,
+            new Date(refDate).getTime()
+          )
+          .it('with value', 10, refDate);
+      });
+
+      t.describe('between', (t) => {
+        t.it(
+          'with string dates',
+          '2021-02-21T17:09:15.711Z',
+          '2021-04-21T17:11:17.711Z'
+        ).it(
+          'with Date dates',
+          new Date('2021-02-21T17:09:15.711Z'),
+          new Date('2021-04-21T17:11:17.711Z')
+        );
+      });
+
+      t.describe('betweens', (t) => {
+        t.it(
+          'with string dates',
+          '2021-02-21T17:09:15.711Z',
+          '2021-04-21T17:11:17.711Z'
+        )
+          .it(
+            'with Date dates',
+            new Date('2021-02-21T17:09:15.711Z'),
+            new Date('2021-04-21T17:11:17.711Z')
+          )
+          .it(
+            'with string dates and count',
+            '2021-02-21T17:09:15.711Z',
+            '2021-04-21T17:11:17.711Z',
+            5
+          )
+          .it(
+            'with Date dates and count',
+            new Date('2021-02-21T17:09:15.711Z'),
+            new Date('2021-04-21T17:11:17.711Z'),
+            5
+          );
+      });
+
+      // No changes to these methods
+      t.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('past()', () => {
@@ -124,7 +199,7 @@ describe('date', () => {
           const yearsAgo = new Date(today);
           yearsAgo.setFullYear(yearsAgo.getFullYear() - 5);
 
-          const date = faker.date.past(5);
+          const date = faker.date.past({ years: 5 });
 
           expect(date).lessThan(today);
           expect(date).greaterThanOrEqual(yearsAgo);
@@ -132,9 +207,9 @@ describe('date', () => {
 
         it('should throw an error when years = 0', () => {
           const refDate = new Date();
-          expect(() => faker.date.past(0, refDate.toISOString())).toThrow(
-            new FakerError('Years must be greater than 0.')
-          );
+          expect(() =>
+            faker.date.past({ years: 0, refDate: refDate.toISOString() })
+          ).toThrow(new FakerError('Years must be greater than 0.'));
         });
 
         it.each(converterMap)(
@@ -143,7 +218,10 @@ describe('date', () => {
             const refDate = new Date();
             refDate.setFullYear(refDate.getFullYear() + 5);
 
-            const date = faker.date.past(5, converter(refDate));
+            const date = faker.date.past({
+              years: 5,
+              refDate: converter(refDate),
+            });
 
             expect(date).lessThan(refDate);
             expect(date).greaterThan(new Date());
@@ -153,16 +231,16 @@ describe('date', () => {
 
       describe('future()', () => {
         it('should return a date 75 years into the future', () => {
-          const date = faker.date.future(75);
+          const date = faker.date.future({ years: 75 });
 
           expect(date).greaterThan(new Date());
         });
 
         it('should throw an error when years = 0', () => {
           const refDate = new Date();
-          expect(() => faker.date.future(0, refDate.toISOString())).toThrow(
-            new FakerError('Years must be greater than 0.')
-          );
+          expect(() =>
+            faker.date.future({ years: 0, refDate: refDate.toISOString() })
+          ).toThrow(new FakerError('Years must be greater than 0.'));
         });
 
         it.each(converterMap)(
@@ -170,7 +248,10 @@ describe('date', () => {
           (converter) => {
             const refDate = new Date(1880, 11, 9, 10, 0, 0, 0); // set the date beyond the usual calculation (to make sure this is working correctly)
 
-            const date = faker.date.future(75, converter(refDate));
+            const date = faker.date.future({
+              years: 75,
+              refDate: converter(refDate),
+            });
 
             // date should be after the date given, but before the current time
             expect(date).greaterThan(refDate);
@@ -186,7 +267,10 @@ describe('date', () => {
             const from = new Date(1990, 5, 7, 9, 11, 0, 0);
             const to = new Date(2000, 6, 8, 10, 12, 0, 0);
 
-            const date = faker.date.between(converter(from), converter(to));
+            const date = faker.date.between({
+              from: converter(from),
+              to: converter(to),
+            });
 
             expect(date).greaterThan(from);
             expect(date).lessThan(to);
@@ -201,7 +285,10 @@ describe('date', () => {
             const from = new Date(1990, 5, 7, 9, 11, 0, 0);
             const to = new Date(2000, 6, 8, 10, 12, 0, 0);
 
-            const dates = faker.date.betweens(converter(from), converter(to));
+            const dates = faker.date.betweens({
+              from: converter(from),
+              to: converter(to),
+            });
 
             expect(dates[0]).greaterThan(from);
             expect(dates[0]).lessThan(to);
@@ -213,16 +300,16 @@ describe('date', () => {
 
       describe('recent()', () => {
         it('should return a date N days from the recent past', () => {
-          const date = faker.date.recent(30);
+          const date = faker.date.recent({ days: 30 });
 
           expect(date).lessThanOrEqual(new Date());
         });
 
         it('should throw an error when days = 0', () => {
           const refDate = new Date();
-          expect(() => faker.date.recent(0, refDate.toISOString())).toThrow(
-            new FakerError('Days must be greater than 0.')
-          );
+          expect(() =>
+            faker.date.recent({ days: 0, refDate: refDate.toISOString() })
+          ).toThrow(new FakerError('Days must be greater than 0.'));
         });
 
         it.each(converterMap)(
@@ -235,7 +322,10 @@ describe('date', () => {
               refDate.getTime() - days * 24 * 60 * 60 * 1000
             );
 
-            const date = faker.date.recent(days, converter(refDate));
+            const date = faker.date.recent({
+              days,
+              refDate: converter(refDate),
+            });
 
             expect(
               lowerBound,
@@ -251,16 +341,16 @@ describe('date', () => {
 
       describe('soon()', () => {
         it('should return a date N days into the future', () => {
-          const date = faker.date.soon(30);
+          const date = faker.date.soon({ days: 30 });
 
           expect(date).greaterThanOrEqual(new Date());
         });
 
         it('should throw an error when days = 0', () => {
           const refDate = new Date();
-          expect(() => faker.date.soon(0, refDate.toISOString())).toThrow(
-            new FakerError('Days must be greater than 0.')
-          );
+          expect(() =>
+            faker.date.soon({ days: 0, refDate: refDate.toISOString() })
+          ).toThrow(new FakerError('Days must be greater than 0.'));
         });
 
         it.each(converterMap)(
@@ -273,7 +363,7 @@ describe('date', () => {
               refDate.getTime() + days * 24 * 60 * 60 * 1000
             );
 
-            const date = faker.date.soon(days, converter(refDate));
+            const date = faker.date.soon({ days, refDate: converter(refDate) });
 
             expect(
               date,
@@ -415,6 +505,177 @@ describe('date', () => {
           );
         });
       });
+
+      describe('deprecated', () => {
+        describe('past()', () => {
+          it('should return a date 5 years in the past', () => {
+            const today = new Date();
+            const yearsAgo = new Date(today);
+            yearsAgo.setFullYear(yearsAgo.getFullYear() - 5);
+
+            const date = faker.date.past(5);
+
+            expect(date).lessThan(today);
+            expect(date).greaterThanOrEqual(yearsAgo);
+          });
+
+          it('should throw an error when years = 0', () => {
+            const refDate = new Date();
+            expect(() => faker.date.past(0, refDate.toISOString())).toThrow(
+              new FakerError('Years must be greater than 0.')
+            );
+          });
+
+          it.each(converterMap)(
+            'should return a past date relative to given refDate',
+            (converter) => {
+              const refDate = new Date();
+              refDate.setFullYear(refDate.getFullYear() + 5);
+
+              const date = faker.date.past(5, converter(refDate));
+
+              expect(date).lessThan(refDate);
+              expect(date).greaterThan(new Date());
+            }
+          );
+        });
+
+        describe('future()', () => {
+          it('should return a date 75 years into the future', () => {
+            const date = faker.date.future(75);
+
+            expect(date).greaterThan(new Date());
+          });
+
+          it('should throw an error when years = 0', () => {
+            const refDate = new Date();
+            expect(() => faker.date.future(0, refDate.toISOString())).toThrow(
+              new FakerError('Years must be greater than 0.')
+            );
+          });
+
+          it.each(converterMap)(
+            'should return a date 75 years after the date given',
+            (converter) => {
+              const refDate = new Date(1880, 11, 9, 10, 0, 0, 0); // set the date beyond the usual calculation (to make sure this is working correctly)
+
+              const date = faker.date.future(75, converter(refDate));
+
+              // date should be after the date given, but before the current time
+              expect(date).greaterThan(refDate);
+              expect(date).lessThan(new Date());
+            }
+          );
+        });
+
+        describe('between()', () => {
+          it.each(converterMap)(
+            'should return a random date between the dates given',
+            (converter) => {
+              const from = new Date(1990, 5, 7, 9, 11, 0, 0);
+              const to = new Date(2000, 6, 8, 10, 12, 0, 0);
+
+              const date = faker.date.between(converter(from), converter(to));
+
+              expect(date).greaterThan(from);
+              expect(date).lessThan(to);
+            }
+          );
+        });
+
+        describe('betweens()', () => {
+          it.each(converterMap)(
+            'should return an array of 3 dates ( by default ) of sorted randoms dates between the dates given',
+            (converter) => {
+              const from = new Date(1990, 5, 7, 9, 11, 0, 0);
+              const to = new Date(2000, 6, 8, 10, 12, 0, 0);
+
+              const dates = faker.date.betweens(converter(from), converter(to));
+
+              expect(dates[0]).greaterThan(from);
+              expect(dates[0]).lessThan(to);
+              expect(dates[1]).greaterThan(dates[0]);
+              expect(dates[2]).greaterThan(dates[1]);
+            }
+          );
+        });
+
+        describe('recent()', () => {
+          it('should return a date N days from the recent past', () => {
+            const date = faker.date.recent(30);
+
+            expect(date).lessThanOrEqual(new Date());
+          });
+
+          it('should throw an error when days = 0', () => {
+            const refDate = new Date();
+            expect(() => faker.date.recent(0, refDate.toISOString())).toThrow(
+              new FakerError('Days must be greater than 0.')
+            );
+          });
+
+          it.each(converterMap)(
+            'should return a date N days from the recent past, starting from refDate',
+            (converter) => {
+              const days = 30;
+              const refDate = new Date(2120, 11, 9, 10, 0, 0, 0); // set the date beyond the usual calculation (to make sure this is working correctly)
+
+              const lowerBound = new Date(
+                refDate.getTime() - days * 24 * 60 * 60 * 1000
+              );
+
+              const date = faker.date.recent(days, converter(refDate));
+
+              expect(
+                lowerBound,
+                '`recent()` date should not be further back than `n` days ago'
+              ).lessThanOrEqual(date);
+              expect(
+                date,
+                '`recent()` date should not be ahead of the starting date reference'
+              ).lessThanOrEqual(refDate);
+            }
+          );
+        });
+
+        describe('soon()', () => {
+          it('should return a date N days into the future', () => {
+            const date = faker.date.soon(30);
+
+            expect(date).greaterThanOrEqual(new Date());
+          });
+
+          it('should throw an error when days = 0', () => {
+            const refDate = new Date();
+            expect(() => faker.date.soon(0, refDate.toISOString())).toThrow(
+              new FakerError('Days must be greater than 0.')
+            );
+          });
+
+          it.each(converterMap)(
+            'should return a date N days from the recent future, starting from refDate',
+            (converter) => {
+              const days = 30;
+              const refDate = new Date(1880, 11, 9, 10, 0, 0, 0); // set the date beyond the usual calculation (to make sure this is working correctly)
+
+              const upperBound = new Date(
+                refDate.getTime() + days * 24 * 60 * 60 * 1000
+              );
+
+              const date = faker.date.soon(days, converter(refDate));
+
+              expect(
+                date,
+                '`soon()` date should not be further ahead than `n` days ago'
+              ).lessThanOrEqual(upperBound);
+              expect(
+                refDate,
+                '`soon()` date should not be behind the starting date reference'
+              ).lessThanOrEqual(date);
+            }
+          );
+        });
+      });
     }
   });
 });