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

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

2 files changed, 566 insertions, 59 deletions

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);
+            }
+          );
+        });
+      });
     }
   });
 });