refactor(commerce): price use options object (#1805)

1 files changed, 131 insertions, 4 deletions

diff --git a/src/modules/commerce/index.ts b/src/modules/commerce/index.ts
index 4afa8819..66f6d02c 100644
--- a/src/modules/commerce/index.ts
+++ b/src/modules/commerce/index.ts
@@ -1,4 +1,5 @@
 import type { Faker } from '../../faker';
+import { deprecated } from '../../internal/deprecated';
 
 /**
  * Module to generate commerce and product related entries.
@@ -44,6 +45,50 @@ export class CommerceModule {
   /**
    * Generates a price between min and max (inclusive).
    *
+   * @param options An options object. Defaults to `{}`.
+   * @param options.min The minimum price. Defaults to `1`.
+   * @param options.max The maximum price. Defaults to `1000`.
+   * @param options.dec The number of decimal places. Defaults to `2`.
+   * @param options.symbol The currency value to use. Defaults to `''`.
+   *
+   * @example
+   * faker.commerce.price() // 828.00
+   * faker.commerce.price({ min: 100 }) // 904.00
+   * faker.commerce.price({ min: 100, max: 200 }) // 154.00
+   * faker.commerce.price({ min: 100, max: 200, dec: 0 }) // 133
+   * faker.commerce.price({ min: 100, max: 200, dec: 0, symbol: '$' }) // $114
+   *
+   * @since 3.0.0
+   */
+  price(options?: {
+    /**
+     * The minimum price.
+     *
+     * @default 1
+     */
+    min?: number;
+    /**
+     * The maximum price.
+     *
+     * @default 1000
+     */
+    max?: number;
+    /**
+     * The number of decimal places.
+     *
+     * @default 2
+     */
+    dec?: number;
+    /**
+     * The currency value to use.
+     *
+     * @default ''
+     */
+    symbol?: string;
+  }): string;
+  /**
+   * Generates a price between min and max (inclusive).
+   *
    * @param min The minimum price. Defaults to `1`.
    * @param max The maximum price. Defaults to `1000`.
    * @param dec The number of decimal places. Defaults to `2`.
@@ -57,13 +102,95 @@ export class CommerceModule {
    * faker.commerce.price(100, 200, 0, '$') // $114
    *
    * @since 3.0.0
+   *
+   * @deprecated Use `faker.commerce.price({ min, max, dec, symbol })` instead.
+   */
+  price(min?: number, max?: number, dec?: number, symbol?: string): string;
+  /**
+   * Generates a price between min and max (inclusive).
+   *
+   * @param options The minimum price or on options object. Defaults to `{}`.
+   * @param options.min The minimum price. Defaults to `1`.
+   * @param options.max The maximum price. Defaults to `1000`.
+   * @param options.dec The number of decimal places. Defaults to `2`.
+   * @param options.symbol The currency value to use. Defaults to `''`.
+   * @param legacyMax The maximum price. This argument is deprecated. Defaults to `1000`.
+   * @param legacyDec The number of decimal places. This argument is deprecated. Defaults to `2`.
+   * @param legacySymbol The currency value to use. This argument is deprecated. Defaults to `''`.
+   *
+   * @example
+   * faker.commerce.price() // 828.00
+   * faker.commerce.price({ min: 100 }) // 904.00
+   * faker.commerce.price({ min: 100, max: 200 }) // 154.00
+   * faker.commerce.price({ min: 100, max: 200, dec: 0 }) // 133
+   * faker.commerce.price({ min: 100, max: 200, dec: 0, symbol: '$' }) // $114
+   *
+   * @since 3.0.0
+   */
+  price(
+    options?:
+      | number
+      | {
+          min?: number;
+          max?: number;
+          dec?: number;
+          symbol?: string;
+        },
+    legacyMax?: number,
+    legacyDec?: number,
+    legacySymbol?: string
+  ): string;
+  /**
+   * Generates a price between min and max (inclusive).
+   *
+   * @param options The minimum price or on options object. Defaults to `{}`.
+   * @param options.min The minimum price. Defaults to `1`.
+   * @param options.max The maximum price. Defaults to `1000`.
+   * @param options.dec The number of decimal places. Defaults to `2`.
+   * @param options.symbol The currency value to use. Defaults to `''`.
+   * @param legacyMax The maximum price. This argument is deprecated. Defaults to `1000`.
+   * @param legacyDec The number of decimal places. This argument is deprecated. Defaults to `2`.
+   * @param legacySymbol The currency value to use. This argument is deprecated. Defaults to `''`.
+   *
+   * @example
+   * faker.commerce.price() // 828.00
+   * faker.commerce.price({ min: 100 }) // 904.00
+   * faker.commerce.price({ min: 100, max: 200 }) // 154.00
+   * faker.commerce.price({ min: 100, max: 200, dec: 0 }) // 133
+   * faker.commerce.price({ min: 100, max: 200, dec: 0, symbol: '$' }) // $114
+   *
+   * @since 3.0.0
    */
   price(
-    min: number = 1,
-    max: number = 1000,
-    dec: number = 2,
-    symbol: string = ''
+    options:
+      | number
+      | {
+          min?: number;
+          max?: number;
+          dec?: number;
+          symbol?: string;
+        } = {},
+    legacyMax: number = 1000,
+    legacyDec: number = 2,
+    legacySymbol: string = ''
   ): string {
+    if (typeof options === 'number') {
+      deprecated({
+        deprecated: 'faker.commerce.price(min, max, dec, symbol)',
+        proposed: 'faker.commerce.price({ min, max, dec, symbol })',
+        since: '8.0',
+        until: '9.0',
+      });
+      options = {
+        min: options,
+        dec: legacyDec,
+        max: legacyMax,
+        symbol: legacySymbol,
+      };
+    }
+
+    const { dec = 2, max = 1000, min = 1, symbol = '' } = options;
+
     if (min < 0 || max < 0) {
       return `${symbol}${0.0}`;
     }