refactor(datatype): deprecate datetime (#2053)

Author: Shinigami92

docs/guide/upgrading.md

@@ -274,6 +274,10 @@ faker.number.float({ max: 100, precision: 0.01 }); // 35.21
 The method `faker.datatype.array` has been deprecated and will be removed in v9.
 If you need an array of useful values, you are better off creating your own one using `faker.helpers.multiple`.
 
+### `faker.datatype.datetime` deprecated in favor of `faker.date.between`
+
+The `datetime` method previously found in `faker.datatype` has been deprecated, use `faker.date.between` instead.
+
 ### `allowLeadingZeros` behavior change in `faker.string.numeric`
 
 The `allowLeadingZeros` boolean parameter in `faker.string.numeric` (in the new `string` module) now defaults to `true`. `faker.string.numeric` will now generate numeric strings that could have leading zeros by default.

src/modules/datatype/index.ts

@@ -166,12 +166,16 @@ export class DatatypeModule {
    *    When not provided or larger than `8640000000000000`, `2100-01-01` is considered
    *    as maximum generated date. Defaults to `4102444800000`.
    *
+   * @see faker.date.between()
+   *
    * @example
    * faker.datatype.datetime() // '2089-04-17T18:03:24.956Z'
    * faker.datatype.datetime(1893456000000) // '2022-03-28T07:00:56.876Z'
    * faker.datatype.datetime({ min: 1577836800000, max: 1893456000000 }) // '2021-09-12T07:13:00.255Z'
    *
    * @since 5.5.0
+   *
+   * @deprecated Use `faker.date.between({ from: min, to: max })` instead.
    */
   datetime(
     options:
@@ -195,6 +199,13 @@ export class DatatypeModule {
           max?: number;
         } = {}
   ): Date {
+    deprecated({
+      deprecated: 'faker.datatype.datetime({ min, max })',
+      proposed: 'faker.date.between({ from, to })',
+      since: '8.0',
+      until: '9.0',
+    });
+
     const minMax = 8640000000000000;
 
     let min = typeof options === 'number' ? undefined : options.min;
@@ -208,7 +219,7 @@ export class DatatypeModule {
       max = Date.UTC(2100, 0);
     }
 
-    return new Date(this.faker.number.int({ min, max }));
+    return this.faker.date.between({ from: min, to: max });
   }
 
   /**