feat(number): bigint multipleOf

src/modules/number/index.ts

@@ -406,6 +406,12 @@ export class NumberModule extends SimpleModuleBase {
            * @default min + 999999999999999n
            */
           max?: bigint | number | string | boolean;
+          /**
+           * The generated bigint will be a multiple of this parameter.
+           *
+           * @default 1n
+           */
+          multipleOf?: bigint | number | string | boolean;
         } = {}
   ): bigint {
     if (
@@ -421,13 +427,24 @@ export class NumberModule extends SimpleModuleBase {
 
     const min = BigInt(options.min ?? 0);
     const max = BigInt(options.max ?? min + BigInt(999999999999999));
+    const multipleOf = BigInt(options.multipleOf ?? 1);
 
     if (max === min) {
       return min;
     }
 
     if (max < min) {
-      throw new FakerError(`Max ${max} should be larger then min ${min}.`);
+      throw new FakerError(`Max ${max} should be larger than min ${min}.`);
+    }
+
+    if (multipleOf <= 0n) {
+      throw new FakerError(`multipleOf should be greater than 0n.`);
+    }
+
+    if (1n < multipleOf && max < multipleOf) {
+      throw new FakerError(
+        `Multiple of ${multipleOf}n should be less than or equal to max ${max}n.`
+      );
     }
 
     const delta = max - min;
@@ -438,10 +455,11 @@ export class NumberModule extends SimpleModuleBase {
           length: delta.toString(10).length,
           allowLeadingZeros: true,
         })
-      ) %
-      (delta + BigInt(1));
+      ) % delta;
+
+    const remaining = multipleOf - ((min + offset) % multipleOf);
 
-    return min + offset;
+    return min + offset + remaining;
   }
 
   /**

test/modules/__snapshots__/number.spec.ts.snap

@@ -1,18 +1,20 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`number > 42 > bigInt > noArgs 1`] = `397511086709821n`;
+exports[`number > 42 > bigInt > noArgs 1`] = `397511086709822n`;
 
-exports[`number > 42 > bigInt > with big options 1`] = `19556777749482489605814694n`;
+exports[`number > 42 > bigInt > with big options 1`] = `19556777749482489605814696n`;
 
-exports[`number > 42 > bigInt > with bigint value 1`] = `25n`;
+exports[`number > 42 > bigInt > with bigint value 1`] = `29n`;
 
 exports[`number > 42 > bigInt > with boolean value 1`] = `1n`;
 
-exports[`number > 42 > bigInt > with number value 1`] = `39n`;
+exports[`number > 42 > bigInt > with multipleOf 1`] = `397511086716281n`;
 
-exports[`number > 42 > bigInt > with options 1`] = `19n`;
+exports[`number > 42 > bigInt > with number value 1`] = `40n`;
 
-exports[`number > 42 > bigInt > with string value 1`] = `39n`;
+exports[`number > 42 > bigInt > with options 1`] = `23n`;
+
+exports[`number > 42 > bigInt > with string value 1`] = `40n`;
 
 exports[`number > 42 > binary > noArgs 1`] = `"0"`;
 
@@ -64,19 +66,21 @@ exports[`number > 42 > romanNumeral > with only max 1`] = `"LXII"`;
 
 exports[`number > 42 > romanNumeral > with only min 1`] = `"MDI"`;
 
-exports[`number > 1211 > bigInt > noArgs 1`] = `982966736876848n`;
+exports[`number > 1211 > bigInt > noArgs 1`] = `982966736876849n`;
 
-exports[`number > 1211 > bigInt > with big options 1`] = `25442250580110979794946298n`;
+exports[`number > 1211 > bigInt > with big options 1`] = `25442250580110979794946302n`;
 
-exports[`number > 1211 > bigInt > with bigint value 1`] = `114n`;
+exports[`number > 1211 > bigInt > with bigint value 1`] = `122n`;
 
 exports[`number > 1211 > bigInt > with boolean value 1`] = `1n`;
 
-exports[`number > 1211 > bigInt > with number value 1`] = `12n`;
+exports[`number > 1211 > bigInt > with multipleOf 1`] = `982966736876952n`;
+
+exports[`number > 1211 > bigInt > with number value 1`] = `15n`;
 
-exports[`number > 1211 > bigInt > with options 1`] = `44n`;
+exports[`number > 1211 > bigInt > with options 1`] = `53n`;
 
-exports[`number > 1211 > bigInt > with string value 1`] = `28n`;
+exports[`number > 1211 > bigInt > with string value 1`] = `30n`;
 
 exports[`number > 1211 > binary > noArgs 1`] = `"1"`;
 
@@ -128,19 +132,21 @@ exports[`number > 1211 > romanNumeral > with only max 1`] = `"CLIV"`;
 
 exports[`number > 1211 > romanNumeral > with only min 1`] = `"MMMDCCXIV"`;
 
-exports[`number > 1337 > bigInt > noArgs 1`] = `212435297136194n`;
+exports[`number > 1337 > bigInt > noArgs 1`] = `212435297136195n`;
+
+exports[`number > 1337 > bigInt > with big options 1`] = `27379244885156992800029993n`;
 
-exports[`number > 1337 > bigInt > with big options 1`] = `27379244885156992800029992n`;
+exports[`number > 1337 > bigInt > with bigint value 1`] = `90n`;
 
-exports[`number > 1337 > bigInt > with bigint value 1`] = `88n`;
+exports[`number > 1337 > bigInt > with boolean value 1`] = `1n`;
 
-exports[`number > 1337 > bigInt > with boolean value 1`] = `0n`;
+exports[`number > 1337 > bigInt > with multipleOf 1`] = `212435297138188n`;
 
-exports[`number > 1337 > bigInt > with number value 1`] = `21n`;
+exports[`number > 1337 > bigInt > with number value 1`] = `22n`;
 
-exports[`number > 1337 > bigInt > with options 1`] = `58n`;
+exports[`number > 1337 > bigInt > with options 1`] = `60n`;
 
-exports[`number > 1337 > bigInt > with string value 1`] = `21n`;
+exports[`number > 1337 > bigInt > with string value 1`] = `22n`;
 
 exports[`number > 1337 > binary > noArgs 1`] = `"0"`;
 

test/modules/number.spec.ts

@@ -50,6 +50,7 @@ describe('number', () => {
         .it('with boolean value', true)
         .it('with bigint value', 123n)
         .it('with options', { min: -42, max: 69 })
+        .it('with multipleOf', { multipleOf: 7919n })
         .it('with big options', {
           min: 6135715171537515454317351n,
           max: 32465761264574654845432354n,
@@ -631,7 +632,34 @@ describe('number', () => {
         expect(() => {
           faker.number.bigInt({ min, max });
         }).toThrow(
-          new FakerError(`Max ${max} should be larger then min ${min}.`)
+          new FakerError(`Max ${max} should be larger than min ${min}.`)
+        );
+      });
+
+      it('should generate a random bigint with a given multipleOf of 1n', () => {
+        const generateBigInt = faker.number.bigInt({ multipleOf: 1n });
+        expect(generateBigInt).toBeTypeOf('bigint');
+      });
+
+      it('should generate a random bigint with a given multipleOf of 7919n', () => {
+        const generateBigInt = faker.number.bigInt({ multipleOf: 7919n });
+        expect(generateBigInt).toBeTypeOf('bigint');
+        expect(generateBigInt % 7919n).toBe(0n);
+      });
+
+      it('should throw for non-positive multipleOf', () => {
+        expect(() => faker.number.bigInt({ multipleOf: 0n })).toThrow(
+          new FakerError('multipleOf should be greater than 0n.')
+        );
+      });
+
+      it('should throw when multipleOf is larger than the given max', () => {
+        expect(() =>
+          faker.number.bigInt({ max: 10n, multipleOf: 20n })
+        ).toThrow(
+          new FakerError(
+            'Multiple of 20n should be less than or equal to max 10n.'
+          )
         );
       });
     });