feat(number): add multipleOf to faker.number.int (#2586)

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

1 files changed, 26 insertions, 7 deletions

diff --git a/src/modules/number/index.ts b/src/modules/number/index.ts
index d8d92c59..be5e213f 100644
--- a/src/modules/number/index.ts
+++ b/src/modules/number/index.ts
@@ -23,9 +23,11 @@ export class NumberModule extends SimpleModuleBase {
    * @param options Maximum value or options object.
    * @param options.min Lower bound for generated number. Defaults to `0`.
    * @param options.max Upper bound for generated number. Defaults to `Number.MAX_SAFE_INTEGER`.
+   * @param options.multipleOf Generated number will be a multiple of the given integer. Defaults to `1`.
    *
    * @throws When `min` is greater than `max`.
-   * @throws When there are no integers between `min` and `max`.
+   * @throws When there are no suitable integers between `min` and `max`.
+   * @throws When `multipleOf` is not a positive integer.
    *
    * @see faker.string.numeric(): For generating a `string` of digits with a given length (range).
    *
@@ -35,6 +37,7 @@ export class NumberModule extends SimpleModuleBase {
    * faker.number.int({ min: 1000000 }) // 2900970162509863
    * faker.number.int({ max: 100 }) // 42
    * faker.number.int({ min: 10, max: 100 }) // 57
+   * faker.number.int({ min: 10, max: 100, multipleOf: 10 }) // 50
    *
    * @since 8.0.0
    */
@@ -54,24 +57,39 @@ export class NumberModule extends SimpleModuleBase {
            * @default Number.MAX_SAFE_INTEGER
            */
           max?: number;
+          /**
+           * Generated number will be a multiple of the given integer.
+           *
+           * @default 1
+           */
+          multipleOf?: number;
         } = {}
   ): number {
     if (typeof options === 'number') {
       options = { max: options };
     }
 
-    const { min = 0, max = Number.MAX_SAFE_INTEGER } = options;
-    const effectiveMin = Math.ceil(min);
-    const effectiveMax = Math.floor(max);
+    const { min = 0, max = Number.MAX_SAFE_INTEGER, multipleOf = 1 } = options;
+
+    if (!Number.isInteger(multipleOf)) {
+      throw new FakerError(`multipleOf should be an integer.`);
+    }
+
+    if (multipleOf <= 0) {
+      throw new FakerError(`multipleOf should be greater than 0.`);
+    }
+
+    const effectiveMin = Math.ceil(min / multipleOf);
+    const effectiveMax = Math.floor(max / multipleOf);
 
     if (effectiveMin === effectiveMax) {
-      return effectiveMin;
+      return effectiveMin * multipleOf;
     }
 
     if (effectiveMax < effectiveMin) {
       if (max >= min) {
         throw new FakerError(
-          `No integer value between ${min} and ${max} found.`
+          `No suitable integer value between ${min} and ${max} found.`
         );
       }
 
@@ -81,7 +99,8 @@ export class NumberModule extends SimpleModuleBase {
     // @ts-expect-error: access private member field
     const randomizer = this.faker._randomizer;
     const real = randomizer.next();
-    return Math.floor(real * (effectiveMax + 1 - effectiveMin) + effectiveMin);
+    const delta = effectiveMax - effectiveMin + 1; // +1 for inclusive max bounds and even distribution
+    return Math.floor(real * delta + effectiveMin) * multipleOf;
   }
 
   /**