feat(date): introduce faker.defaultRefDate and setDefaultRefDate (#1757)

Co-authored-by: Shinigami <chrissi92@hotmail.de>

Author: ST-DDT

scripts/apidoc.ts

@@ -1,4 +1,5 @@
 import { resolve } from 'path';
+import { faker } from '../src';
 import {
   writeApiPagesIndex,
   writeApiSearchIndex,
@@ -13,6 +14,7 @@ const pathOutputJson = resolve(pathOutputDir, 'typedoc.json');
 
 async function build(): Promise<void> {
   await initMarkdownRenderer();
+  faker.setDefaultRefDate(Date.UTC(2023, 0, 1));
 
   const app = newTypeDocApp();
 

src/faker.ts

@@ -51,6 +51,7 @@ export class Faker {
   locales: UsedLocales;
   private _locale: UsableLocale;
   private _localeFallback: UsableLocale;
+  private _defaultRefDate: () => Date = () => new Date();
 
   get locale(): UsableLocale {
     return this._locale;
@@ -80,6 +81,30 @@ export class Faker {
     this._localeFallback = localeFallback;
   }
 
+  /**
+   * Gets a new reference date used to generate relative dates.
+   */
+  get defaultRefDate(): () => Date {
+    return this._defaultRefDate;
+  }
+
+  /**
+   * Sets the `refDate` source to use if no `refDate` date is passed to the date methods.
+   *
+   * @param dateOrSource The function or the static value used to generate the `refDate` date instance.
+   * The function must return a new valid `Date` instance for every call.
+   * Defaults to `() => new Date()`.
+   */
+  setDefaultRefDate(
+    dateOrSource: string | Date | number | (() => Date) = () => new Date()
+  ): void {
+    if (typeof dateOrSource === 'function') {
+      this._defaultRefDate = dateOrSource;
+    } else {
+      this._defaultRefDate = () => new Date(dateOrSource);
+    }
+  }
+
   readonly definitions: LocaleDefinition = this.initDefinitions();
 
   /** @internal */

src/modules/date/index.ts

@@ -5,14 +5,18 @@ import { deprecated } from '../../internal/deprecated';
 
 /**
  * Converts date passed as a string, number or Date to a Date object.
- * If nothing or a non parsable value is passed, takes current date.
+ * If nothing or a non parsable value is passed, then it will take the value from the given fallback.
  *
- * @param date Date
+ * @param date The date to convert.
+ * @param fallback The fallback date to use if the passed date is not valid.
  */
-function toDate(date?: string | Date | number): Date {
+function toDate(
+  date?: string | Date | number,
+  fallback: () => Date = () => new Date()
+): Date {
   date = new Date(date);
   if (isNaN(date.valueOf())) {
-    date = new Date();
+    date = fallback();
   }
 
   return date;
@@ -38,7 +42,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.recent()
    *
@@ -59,15 +63,15 @@ export class DateModule {
     /**
      * The date to use as reference point for the newly generated date.
      *
-     * @default new Date()
+     * @default faker.defaultRefDate()
      */
     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 `new Date()`.
+   * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.recent()
    *
@@ -86,7 +90,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
    * @see faker.date.recent()
@@ -111,7 +115,7 @@ export class DateModule {
           /**
            * The date to use as reference point for the newly generated date.
            *
-           * @default new Date()
+           * @default faker.defaultRefDate()
            */
           refDate?: string | Date | number;
         },
@@ -142,7 +146,7 @@ export class DateModule {
       throw new FakerError('Years must be greater than 0.');
     }
 
-    const date = toDate(refDate);
+    const date = toDate(refDate, this.faker.defaultRefDate);
     const range = {
       min: 1000,
       max: years * 365 * 24 * 3600 * 1000,
@@ -160,7 +164,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.soon()
    *
@@ -181,15 +185,15 @@ export class DateModule {
     /**
      * The date to use as reference point for the newly generated date.
      *
-     * @default new Date()
+     * @default faker.defaultRefDate()
      */
     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 `new Date()`.
+   * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.soon()
    *
@@ -208,7 +212,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
    * @see faker.date.soon()
@@ -233,7 +237,7 @@ export class DateModule {
           /**
            * The date to use as reference point for the newly generated date.
            *
-           * @default new Date()
+           * @default faker.defaultRefDate()
            */
           refDate?: string | Date | number;
         },
@@ -264,7 +268,7 @@ export class DateModule {
       throw new FakerError('Years must be greater than 0.');
     }
 
-    const date = toDate(refDate);
+    const date = toDate(refDate, this.faker.defaultRefDate);
     const range = {
       min: 1000,
       max: years * 365 * 24 * 3600 * 1000,
@@ -552,7 +556,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.past()
    *
@@ -573,15 +577,15 @@ export class DateModule {
     /**
      * The date to use as reference point for the newly generated date.
      *
-     * @default new Date()
+     * @default faker.defaultRefDate()
      */
     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 `new Date()`.
+   * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.past()
    *
@@ -600,7 +604,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
    * @see faker.date.past()
@@ -625,7 +629,7 @@ export class DateModule {
           /**
            * The date to use as reference point for the newly generated date.
            *
-           * @default new Date()
+           * @default faker.defaultRefDate()
            */
           refDate?: string | Date | number;
         },
@@ -651,7 +655,7 @@ export class DateModule {
       throw new FakerError('Days must be greater than 0.');
     }
 
-    const date = toDate(refDate);
+    const date = toDate(refDate, this.faker.defaultRefDate);
     const range = {
       min: 1000,
       max: days * 24 * 3600 * 1000,
@@ -669,7 +673,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.future()
    *
@@ -690,15 +694,15 @@ export class DateModule {
     /**
      * The date to use as reference point for the newly generated date.
      *
-     * @default new Date()
+     * @default faker.defaultRefDate()
      */
     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 `new Date()`.
+   * @param refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    *
    * @see faker.date.future()
    *
@@ -717,7 +721,7 @@ export class DateModule {
    *
    * @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 `new Date()`.
+   * @param options.refDate The date to use as reference point for the newly generated date. Defaults to `faker.defaultRefDate()`.
    * @param legacyRefDate Deprecated, use `options.refDate` instead.
    *
    * @see faker.date.future()
@@ -742,7 +746,7 @@ export class DateModule {
           /**
            * The date to use as reference point for the newly generated date.
            *
-           * @default new Date()
+           * @default faker.defaultRefDate()
            */
           refDate?: string | Date | number;
         },
@@ -768,7 +772,7 @@ export class DateModule {
       throw new FakerError('Days must be greater than 0.');
     }
 
-    const date = toDate(refDate);
+    const date = toDate(refDate, this.faker.defaultRefDate);
     const range = {
       min: 1000,
       max: days * 24 * 3600 * 1000,
@@ -938,7 +942,7 @@ export class DateModule {
       /**
        * The date to use as reference point for the newly generated date.
        *
-       * @default new Date()
+       * @default faker.defaultRefDate()
        */
       refDate?: string | Date | number;
     } = {}

src/modules/git/index.ts

@@ -143,7 +143,7 @@ export class GitModule {
    * Generates a date string for a git commit using the same format as `git log`.
    *
    * @param options The optional options object.
-   * @param options.refDate The date to use as reference point for the commit. Defaults to `new Date()`.
+   * @param options.refDate The date to use as reference point for the commit. Defaults to `faker.defaultRefDate()`.
    *
    * @example
    * faker.git.commitDate() // 'Mon Nov 7 14:40:58 2022 +0600'
@@ -156,12 +156,12 @@ export class GitModule {
       /**
        * The date to use as reference point for the commit.
        *
-       * @default new Date()
+       * @default faker.defaultRefDate()
        */
       refDate?: string | Date | number;
     } = {}
   ): string {
-    const { refDate = new Date() } = options;
+    const { refDate = this.faker.defaultRefDate() } = options;
 
     const dateParts = GIT_DATE_FORMAT_BASE.format(
       this.faker.date.recent({ days: 1, refDate })

test/date.spec.ts

@@ -732,4 +732,32 @@ describe('date', () => {
       });
     }
   });
+
+  describe('refDateSource', () => {
+    afterEach(() => {
+      faker.setDefaultRefDate();
+    });
+
+    it('should use the refDateSource when refDate is not provided (with function)', () => {
+      faker.setDefaultRefDate(() => new Date(Date.UTC(2020, 0, 1)));
+      faker.seed(20200101);
+      const date = faker.date.past();
+      expect(date).toEqual(new Date('2019-02-25T21:52:41.824Z'));
+
+      faker.seed(20200101);
+      const date2 = faker.date.past();
+      expect(date2).toEqual(new Date('2019-02-25T21:52:41.824Z'));
+    });
+
+    it('should use the refDateSource when refDate is not provided (with value)', () => {
+      faker.setDefaultRefDate(Date.UTC(2020, 0, 1));
+      faker.seed(20200101);
+      const date = faker.date.past();
+      expect(date).toEqual(new Date('2019-02-25T21:52:41.824Z'));
+
+      faker.seed(20200101);
+      const date2 = faker.date.past();
+      expect(date2).toEqual(new Date('2019-02-25T21:52:41.824Z'));
+    });
+  });
 });

test/faker.spec.ts

@@ -141,4 +141,18 @@ describe('faker', () => {
       expect(actual).toBe('Oriental');
     });
   });
+
+  describe('defaultRefDate', () => {
+    it('should be a defined', () => {
+      expect(faker.defaultRefDate).toBeDefined();
+    });
+
+    it('should be a date in the very recent past', () => {
+      const start = Date.now();
+      const refDate = faker.defaultRefDate().getTime();
+      const end = Date.now();
+      expect(refDate).toBeGreaterThanOrEqual(start);
+      expect(refDate).toBeLessThanOrEqual(end);
+    });
+  });
 });