refactor(number): deprecate precision in favor of multipleOf in float (#2564)

1 files changed, 35 insertions, 12 deletions

diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts
index 4becb348..2d1af9cc 100644
--- a/src/modules/number/index.ts
+++ b/src/modules/number/index.ts
@@ -1,4 +1,5 @@
 import { FakerError } from '../../errors/faker-error';
+import { deprecated } from '../../internal/deprecated';
 import { SimpleModuleBase } from '../../internal/module-base';
 
 /**
@@ -85,14 +86,18 @@ export class NumberModule extends SimpleModuleBase {
   }
 
   /**
-   * Returns a single random floating-point number for a given precision or range and precision.
-   * The lower bound is inclusive, the upper bound is exclusive, unless precision is passed.
+   * Returns a single random floating-point number.
+   * The lower bound is inclusive, the upper bound is exclusive, unless `multipleOf` is passed.
    *
    * @param options Upper bound or options object.
    * @param options.min Lower bound for generated number. Defaults to `0.0`.
    * @param options.max Upper bound for generated number. Defaults to `1.0`.
    * @param options.precision Precision of the generated number, for example `0.01` will round to 2 decimal points.
    * If precision is passed, the upper bound is inclusive.
+   * @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.
    *
    * @throws When `min` is greater than `max`.
    * @throws When `precision` is negative.
@@ -102,8 +107,8 @@ export class NumberModule extends SimpleModuleBase {
    * faker.number.float(3) // 2.367973240558058
    * faker.number.float({ min: -1000000 }) //-780678.849672846
    * faker.number.float({ max: 100 }) // 17.3687307164073
-   * faker.number.float({ precision: 0.1 }) // 0.9
-   * faker.number.float({ min: 10, max: 100, precision: 0.001 }) // 35.415
+   * faker.number.float({ multipleOf: 0.25 }) // 3.75
+   * faker.number.float({ min: 10, max: 100, multipleOf: 0.001 }) // 35.415
    *
    * @since 8.0.0
    */
@@ -125,8 +130,15 @@ export class NumberModule extends SimpleModuleBase {
           max?: number;
           /**
            * Precision of the generated number.
+           *
+           * @deprecated Use `multipleOf` instead.
            */
           precision?: number;
+          /**
+           * The generated number will be a multiple of this property.
+           * If multipleOf is passed, the upper bound is inclusive.
+           */
+          multipleOf?: number;
         } = {}
   ): number {
     if (typeof options === 'number') {
@@ -135,7 +147,17 @@ export class NumberModule extends SimpleModuleBase {
       };
     }
 
-    const { min = 0, max = 1, precision } = options;
+    // eslint-disable-next-line deprecation/deprecation
+    const { min = 0, max = 1, precision, multipleOf = precision } = options;
+
+    if (precision !== undefined) {
+      deprecated({
+        deprecated: 'faker.number.float({ precision })',
+        proposed: 'faker.number.float({ multipleOf })',
+        since: '8.4',
+        until: '9.0',
+      });
+    }
 
     if (max === min) {
       return min;
@@ -145,17 +167,18 @@ export class NumberModule extends SimpleModuleBase {
       throw new FakerError(`Max ${max} should be greater than min ${min}.`);
     }
 
-    if (precision !== undefined) {
-      if (precision <= 0) {
-        throw new FakerError(`Precision should be greater than 0.`);
+    if (multipleOf !== undefined) {
+      if (multipleOf <= 0) {
+        // TODO @xDivisionByZerox: Clean up in v9.0
+        throw new FakerError(`multipleOf/precision should be greater than 0.`);
       }
 
-      const logPrecision = Math.log10(precision);
-      // Workaround to get integer values for the inverse of all precisions of the form 10^-n
+      const logPrecision = Math.log10(multipleOf);
+      // Workaround to get integer values for the inverse of all multiples of the form 10^-n
       const factor =
-        precision < 1 && Number.isInteger(logPrecision)
+        multipleOf < 1 && Number.isInteger(logPrecision)
           ? 10 ** -logPrecision
-          : 1 / precision;
+          : 1 / multipleOf;
       const int = this.int({
         min: min * factor,
         max: max * factor,