feat(number): add parameter `fractionDigits` in float (#1855)

Co-authored-by: ST-DDT <[email protected]>

3 files changed, 48 insertions, 11 deletions

diff --git a/src/modules/finance/index.ts b/src/modules/finance/index.ts
index 4caa77b0..219c2702 100644
--- a/src/modules/finance/index.ts
+++ b/src/modules/finance/index.ts
@@ -601,7 +601,7 @@ export class FinanceModule extends ModuleBase {
     const randValue = this.faker.number.float({
       max,
       min,
-      multipleOf: 10 ** -dec,
+      fractionDigits: dec,
     });
 
     const formattedString = autoFormat
diff --git a/src/modules/location/index.ts b/src/modules/location/index.ts
index b06af49e..608e65a6 100644
--- a/src/modules/location/index.ts
+++ b/src/modules/location/index.ts
@@ -579,7 +579,7 @@ export class LocationModule extends ModuleBase {
 
     const { max = 90, min = legacyMin, precision = legacyPrecision } = options;
 
-    return this.faker.number.float({ min, max, multipleOf: 10 ** -precision });
+    return this.faker.number.float({ min, max, fractionDigits: precision });
   }
 
   /**
@@ -732,7 +732,7 @@ export class LocationModule extends ModuleBase {
 
     const { max = 180, min = legacyMin, precision = legacyPrecision } = options;
 
-    return this.faker.number.float({ max, min, multipleOf: 10 ** -precision });
+    return this.faker.number.float({ max, min, fractionDigits: precision });
   }
 
   /**
@@ -1207,7 +1207,7 @@ export class LocationModule extends ModuleBase {
 
     const angleRadians = this.faker.number.float({
       max: 2 * Math.PI,
-      multipleOf: 0.00001,
+      fractionDigits: 5,
     }); // in ° radians
 
     const radiusMetric = isMetric ? radius : radius * 1.60934; // in km
@@ -1215,7 +1215,7 @@ export class LocationModule extends ModuleBase {
     const distanceInKm =
       this.faker.number.float({
         max: radiusMetric,
-        multipleOf: 0.001,
+        fractionDigits: 3,
       }) * errorCorrection; // in km
 
     /**
diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts
index 2d1af9cc..cb329382 100644
--- a/src/modules/number/index.ts
+++ b/src/modules/number/index.ts
@@ -97,10 +97,16 @@ export class NumberModule extends SimpleModuleBase {
    * @param options.multipleOf The generated number will be a multiple of this property.
    * This property can be used to limit the result to a specific number of decimal digits.
    * For example `0.01` will round to 2 decimal points.
-   * If multipleOf is passed, the upper bound is inclusive.
+   * If `multipleOf` is passed, the upper bound is inclusive.
+   * This option is incompatible with the `fractionDigits` option.
+   * @param options.fractionDigits The maximum number of digits to appear after the decimal point.
+   * This option is incompatible with the `multipleOf` option.
    *
    * @throws When `min` is greater than `max`.
    * @throws When `precision` is negative.
+   * @throws When `multipleOf` is negative.
+   * @throws When `fractionDigits` is negative.
+   * @throws When `fractionDigits` and `multipleOf` is passed in the same options object.
    *
    * @example
    * faker.number.float() // 0.5688541042618454
@@ -108,7 +114,9 @@ export class NumberModule extends SimpleModuleBase {
    * faker.number.float({ min: -1000000 }) //-780678.849672846
    * faker.number.float({ max: 100 }) // 17.3687307164073
    * faker.number.float({ multipleOf: 0.25 }) // 3.75
-   * faker.number.float({ min: 10, max: 100, multipleOf: 0.001 }) // 35.415
+   * faker.number.float({ fractionDigits: 1 }) // 0.9
+   * faker.number.float({ min: 10, max: 100, multipleOf: 0.02 }) // 35.42
+   * faker.number.float({ min: 10, max: 100, fractionDigits: 3 }) // 65.716
    *
    * @since 8.0.0
    */
@@ -129,6 +137,10 @@ export class NumberModule extends SimpleModuleBase {
            */
           max?: number;
           /**
+           * The number of digits to appear after the decimal point.
+           */
+          fractionDigits?: number;
+          /*
            * Precision of the generated number.
            *
            * @deprecated Use `multipleOf` instead.
@@ -147,10 +159,17 @@ export class NumberModule extends SimpleModuleBase {
       };
     }
 
-    // eslint-disable-next-line deprecation/deprecation
-    const { min = 0, max = 1, precision, multipleOf = precision } = options;
+    const {
+      min = 0,
+      max = 1,
+      fractionDigits,
+      precision,
+      multipleOf: originalMultipleOf = precision,
+      multipleOf = precision ??
+        (fractionDigits == null ? undefined : 10 ** -fractionDigits),
+    } = options;
 
-    if (precision !== undefined) {
+    if (precision != null) {
       deprecated({
         deprecated: 'faker.number.float({ precision })',
         proposed: 'faker.number.float({ multipleOf })',
@@ -167,7 +186,25 @@ export class NumberModule extends SimpleModuleBase {
       throw new FakerError(`Max ${max} should be greater than min ${min}.`);
     }
 
-    if (multipleOf !== undefined) {
+    if (fractionDigits != null) {
+      if (originalMultipleOf != null) {
+        throw new FakerError(
+          'multipleOf and fractionDigits cannot be set at the same time.'
+        );
+      }
+
+      if (!Number.isInteger(fractionDigits)) {
+        throw new FakerError('fractionDigits should be an integer.');
+      }
+
+      if (fractionDigits < 0) {
+        throw new FakerError(
+          'fractionDigits should be greater than or equal to 0.'
+        );
+      }
+    }
+
+    if (multipleOf != null) {
       if (multipleOf <= 0) {
         // TODO @xDivisionByZerox: Clean up in v9.0
         throw new FakerError(`multipleOf/precision should be greater than 0.`);