refactor(date)!: stricter error handling of between (#2719)

1 files changed, 31 insertions, 3 deletions

diff --git a/src/modules/date/index.ts b/src/modules/date/index.ts
index cc8b2d0a..19dea55c 100644
--- a/src/modules/date/index.ts
+++ b/src/modules/date/index.ts
@@ -155,10 +155,13 @@ export class SimpleDateModule extends SimpleModuleBase {
   /**
    * Generates a random date between the given boundaries.
    *
-   * @param options The optional options object.
+   * @param options The options object.
    * @param options.from The early date boundary.
    * @param options.to The late date boundary.
    *
+   * @throws If `from` or `to` are not provided.
+   * @throws If `from` is after `to`.
+   *
    * @example
    * faker.date.between({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' }) // '2026-05-16T02:22:53.002Z'
    *
@@ -174,10 +177,20 @@ export class SimpleDateModule extends SimpleModuleBase {
      */
     to: string | Date | number;
   }): Date {
+    // TODO @matthewmayer 2023-03-27: Consider removing in v10 as this check is only needed in JS
+    if (options == null || options.from == null || options.to == null) {
+      throw new FakerError(
+        'Must pass an options object with `from` and `to` values.'
+      );
+    }
+
     const { from, to } = options;
 
     const fromMs = toDate(from, 'from').getTime();
     const toMs = toDate(to, 'to').getTime();
+    if (fromMs > toMs) {
+      throw new FakerError('`from` date must be before `to` date.');
+    }
 
     return new Date(this.faker.number.int({ min: fromMs, max: toMs }));
   }
@@ -185,11 +198,14 @@ export class SimpleDateModule extends SimpleModuleBase {
   /**
    * Generates random dates between the given boundaries. The dates will be returned in an array sorted in chronological order.
    *
-   * @param options The optional options object.
+   * @param options The 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`.
    *
+   * @throws If `from` or `to` are not provided.
+   * @throws If `from` is after `to`.
+   *
    * @example
    * faker.date.betweens({ from: '2020-01-01T00:00:00.000Z', to: '2030-01-01T00:00:00.000Z' })
    * // [
@@ -235,8 +251,14 @@ export class SimpleDateModule extends SimpleModuleBase {
           max: number;
         };
   }): Date[] {
-    const { from, to, count = 3 } = options;
+    // TODO @matthewmayer 2023-03-27: Consider removing in v10 as this check is only needed in JS
+    if (options == null || options.from == null || options.to == null) {
+      throw new FakerError(
+        'Must pass an options object with `from` and `to` values.'
+      );
+    }
 
+    const { from, to, count = 3 } = options;
     return this.faker.helpers
       .multiple(() => this.between({ from, to }), { count })
       .sort((a, b) => a.getTime() - b.getTime());
@@ -433,6 +455,12 @@ export class SimpleDateModule extends SimpleModuleBase {
  *
  * For more control, any of these methods can be customized with further options, or use [`between()`](https://fakerjs.dev/api/date.html#between) to generate a single date between two dates, or [`betweens()`](https://fakerjs.dev/api/date.html#betweens) for multiple dates.
  *
+ * Dates can be specified as Javascript Date objects, strings or UNIX timestamps.
+ * For example to generate a date between 1st January 2000 and now, use:
+ * ```ts
+ * faker.date.between({ from: '2000-01-01', to: Date.now() });
+ * ```
+ *
  * You can generate random localized month and weekday names using [`month()`](https://fakerjs.dev/api/date.html#month) and [`weekday()`](https://fakerjs.dev/api/date.html#weekday).
  *
  * These methods have additional concerns about reproducibility, see [Reproducible Results](https://fakerjs.dev/guide/usage.html#reproducible-results).