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

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

1 files changed, 320 insertions, 59 deletions

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