feat(number): move methods to new module (#1122)

Co-authored-by: ST-DDT <ST-DDT@gmx.de>
Co-authored-by: Eric Cheng <ericcheng9316@gmail.com>
Co-authored-by: Leyla Jähnig <leyla.jaehnig@gmx.de>
Co-authored-by: Shinigami92 <chrissi92@hotmail.de>

README.md

@@ -132,12 +132,12 @@ If you want consistent results, you can set your own seed:
 ```ts
 faker.seed(123);
 
-const firstRandom = faker.datatype.number();
+const firstRandom = faker.number.int();
 
 // Setting the seed again resets the sequence.
 faker.seed(123);
 
-const secondRandom = faker.datatype.number();
+const secondRandom = faker.number.int();
 
 console.log(firstRandom === secondRandom);
 ```

docs/.vitepress/api-pages.ts

@@ -18,6 +18,7 @@ export const apiPages = [
   { text: 'Location', link: '/api/location.html' },
   { text: 'Lorem', link: '/api/lorem.html' },
   { text: 'Music', link: '/api/music.html' },
+  { text: 'Number', link: '/api/number.html' },
   { text: 'Person', link: '/api/person.html' },
   { text: 'Phone', link: '/api/phone.html' },
   { text: 'Random', link: '/api/random.html' },

src/faker.ts

@@ -21,6 +21,7 @@ import type { LocationModule as AddressModule } from './modules/location';
 import { LocationModule } from './modules/location';
 import { LoremModule } from './modules/lorem';
 import { MusicModule } from './modules/music';
+import { NumberModule } from './modules/number';
 import type { PersonModule as NameModule } from './modules/person';
 import { PersonModule } from './modules/person';
 import { PhoneModule } from './modules/phone';
@@ -103,6 +104,7 @@ export class Faker {
   readonly lorem: LoremModule = new LoremModule(this);
   readonly music: MusicModule = new MusicModule(this);
   readonly person: PersonModule = new PersonModule(this);
+  readonly number: NumberModule = new NumberModule(this);
   readonly phone: PhoneModule = new PhoneModule(this);
   readonly science: ScienceModule = new ScienceModule(this);
   readonly string: StringModule = new StringModule(this);
@@ -239,12 +241,12 @@ export class Faker {
    * @example
    * // Consistent values for tests:
    * faker.seed(42)
-   * faker.datatype.number(10); // 4
-   * faker.datatype.number(10); // 8
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
    *
    * faker.seed(42)
-   * faker.datatype.number(10); // 4
-   * faker.datatype.number(10); // 8
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
    *
    * @example
    * // Random but reproducible tests:
@@ -271,12 +273,12 @@ export class Faker {
    * @example
    * // Consistent values for tests:
    * faker.seed([42, 13, 17])
-   * faker.datatype.number(10); // 4
-   * faker.datatype.number(10); // 8
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
    *
    * faker.seed([42, 13, 17])
-   * faker.datatype.number(10); // 4
-   * faker.datatype.number(10); // 8
+   * faker.number.int(10); // 4
+   * faker.number.int(10); // 8
    *
    * @example
    * // Random but reproducible tests:

src/index.ts

@@ -63,6 +63,7 @@ export type {
 } from './modules/location';
 export type { LoremModule } from './modules/lorem';
 export type { MusicModule } from './modules/music';
+export type { NumberModule } from './modules/number';
 export { Sex } from './modules/person';
 export type {
   /** @deprecated Use PersonModule instead */

src/modules/color/index.ts

@@ -320,13 +320,9 @@ export class ColorModule {
       color = formatHexColor(color, options);
       return color;
     }
-    color = Array.from({ length: 3 }).map(() =>
-      this.faker.datatype.number({ min: 0, max: 255 })
-    );
+    color = Array.from({ length: 3 }).map(() => this.faker.number.int(255));
     if (includeAlpha) {
-      color.push(
-        this.faker.datatype.float({ min: 0, max: 1, precision: 0.01 })
-      );
+      color.push(this.faker.number.float({ max: 1, precision: 0.01 }));
       cssFunction = 'rgba';
     }
     return toColorFormat(color, format, cssFunction);
@@ -385,7 +381,7 @@ export class ColorModule {
   cmyk(options?: { format?: ColorFormat }): string | number[];
   cmyk(options?: { format?: ColorFormat }): string | number[] {
     const color: string | number[] = Array.from({ length: 4 }).map(() =>
-      this.faker.datatype.float({ min: 0, max: 1, precision: 0.01 })
+      this.faker.number.float({ max: 1, precision: 0.01 })
     );
     return toColorFormat(color, options?.format || 'decimal', 'cmyk');
   }
@@ -460,9 +456,9 @@ export class ColorModule {
     format?: ColorFormat;
     includeAlpha?: boolean;
   }): string | number[] {
-    const hsl: number[] = [this.faker.datatype.number({ min: 0, max: 360 })];
+    const hsl: number[] = [this.faker.number.int(360)];
     for (let i = 0; i < (options?.includeAlpha ? 3 : 2); i++) {
-      hsl.push(this.faker.datatype.float({ min: 0, max: 1, precision: 0.01 }));
+      hsl.push(this.faker.number.float({ max: 1, precision: 0.01 }));
     }
     return toColorFormat(
       hsl,
@@ -537,9 +533,9 @@ export class ColorModule {
    * @since 7.0.0
    */
   hwb(options?: { format?: ColorFormat }): string | number[] {
-    const hsl: number[] = [this.faker.datatype.number({ min: 0, max: 360 })];
+    const hsl: number[] = [this.faker.number.int(360)];
     for (let i = 0; i < 2; i++) {
-      hsl.push(this.faker.datatype.float({ min: 0, max: 1, precision: 0.01 }));
+      hsl.push(this.faker.number.float({ max: 1, precision: 0.01 }));
     }
     return toColorFormat(hsl, options?.format || 'decimal', 'hwb');
   }
@@ -596,12 +592,10 @@ export class ColorModule {
    */
   lab(options?: { format?: ColorFormat }): string | number[];
   lab(options?: { format?: ColorFormat }): string | number[] {
-    const lab = [
-      this.faker.datatype.float({ min: 0, max: 1, precision: 0.000001 }),
-    ];
+    const lab = [this.faker.number.float({ max: 1, precision: 0.000001 })];
     for (let i = 0; i < 2; i++) {
       lab.push(
-        this.faker.datatype.float({ min: -100, max: 100, precision: 0.0001 })
+        this.faker.number.float({ min: -100, max: 100, precision: 0.0001 })
       );
     }
     return toColorFormat(lab, options?.format || 'decimal', 'lab');
@@ -671,13 +665,9 @@ export class ColorModule {
    */
   lch(options?: { format?: ColorFormat }): string | number[];
   lch(options?: { format?: ColorFormat }): string | number[] {
-    const lch = [
-      this.faker.datatype.float({ min: 0, max: 1, precision: 0.000001 }),
-    ];
+    const lch = [this.faker.number.float({ max: 1, precision: 0.000001 })];
     for (let i = 0; i < 2; i++) {
-      lch.push(
-        this.faker.datatype.number({ min: 0, max: 230, precision: 0.1 })
-      );
+      lch.push(this.faker.number.float({ max: 230, precision: 0.1 }));
     }
     return toColorFormat(lch, options?.format || 'decimal', 'lch');
   }
@@ -753,7 +743,7 @@ export class ColorModule {
       options = { ...options, space: 'sRGB' };
     }
     const color = Array.from({ length: 3 }).map(() =>
-      this.faker.datatype.float({ min: 0, max: 1, precision: 0.0001 })
+      this.faker.number.float({ max: 1, precision: 0.0001 })
     );
     return toColorFormat(
       color,

src/modules/commerce/index.ts

@@ -67,14 +67,10 @@ export class CommerceModule {
       return `${symbol}${0.0}`;
     }
 
-    const randValue = this.faker.datatype.number({ max: max, min: min });
+    // TODO @Shinigami92 2022-11-24: https://github.com/faker-js/faker/issues/350
+    const randValue = this.faker.number.int({ min, max });
 
-    return (
-      symbol +
-      (Math.round(randValue * Math.pow(10, dec)) / Math.pow(10, dec)).toFixed(
-        dec
-      )
-    );
+    return symbol + randValue.toFixed(dec);
   }
 
   /**

src/modules/datatype/index.ts

@@ -1,7 +1,5 @@
 import type { Faker } from '../..';
-import { FakerError } from '../../errors/faker-error';
 import { deprecated } from '../../internal/deprecated';
-import type { Mersenne } from '../../internal/mersenne/mersenne';
 
 /**
  * Module to generate various primitive values and data types.
@@ -37,36 +35,26 @@ export class DatatypeModule {
    * faker.datatype.number({ min: 10, max: 100, precision: 0.01 }) // 36.94
    *
    * @since 5.5.0
+   *
+   * @deprecated Use `faker.number.int()` instead.
    */
   number(
     options: number | { min?: number; max?: number; precision?: number } = 99999
   ): number {
+    deprecated({
+      deprecated: 'faker.datatype.number()',
+      proposed: 'faker.number.int()',
+      since: '8.0',
+      until: '9.0',
+    });
+
     if (typeof options === 'number') {
       options = { max: options };
     }
 
-    const { min = 0, precision = 1 } = options;
-    const max = options.max ?? min + 99999;
-
-    if (max === min) {
-      return min;
-    }
-
-    if (max < min) {
-      throw new FakerError(`Max ${max} should be greater than min ${min}.`);
-    }
+    const { min = 0, max = min + 99999, precision = 1 } = options;
 
-    const mersenne: Mersenne =
-      // @ts-expect-error: access private member field
-      this.faker._mersenne;
-
-    const randomNumber = mersenne.next({
-      min: min / precision,
-      max: max / precision + 1,
-    });
-
-    // Workaround problem in float point arithmetics for e.g. 6681493 / 0.01
-    return randomNumber / (1 / precision);
+    return this.faker.number.float({ min, max, precision });
   }
 
   /**
@@ -86,24 +74,19 @@ export class DatatypeModule {
    * faker.datatype.float({ min: 10, max: 100, precision: 0.001 }) // 57.315
    *
    * @since 5.5.0
+   *
+   * @deprecated Use `faker.number.float()` instead.
    */
   float(
     options?: number | { min?: number; max?: number; precision?: number }
   ): number {
-    if (typeof options === 'number') {
-      options = {
-        precision: options,
-      };
-    }
-    options = options || {};
-    const opts: { precision?: number } = {};
-    for (const p in options) {
-      opts[p] = options[p];
-    }
-    if (opts.precision == null) {
-      opts.precision = 0.01;
-    }
-    return this.number(opts);
+    deprecated({
+      deprecated: 'faker.datatype.float()',
+      proposed: 'faker.number.float()',
+      since: '8.0',
+      until: '9.0',
+    });
+    return this.faker.number.float(options);
   }
 
   /**
@@ -139,7 +122,7 @@ export class DatatypeModule {
       max = Date.UTC(2100, 0);
     }
 
-    return new Date(this.number({ min, max }));
+    return new Date(this.faker.number.int({ min, max }));
   }
 
   /**
@@ -177,7 +160,7 @@ export class DatatypeModule {
    *
    * @since 5.5.0
    *
-   * @deprecated Use faker.string.uuid() instead.
+   * @deprecated Use `faker.string.uuid()` instead.
    */
   uuid(): string {
     deprecated({
@@ -222,7 +205,7 @@ export class DatatypeModule {
       // This check is required to avoid returning false when float() returns 1
       return true;
     }
-    return this.float({ min: 0, max: 1 }) < probability;
+    return this.faker.number.float({ max: 1 }) < probability;
   }
 
   /**
@@ -247,7 +230,7 @@ export class DatatypeModule {
    *
    * @since 6.1.2
    *
-   * @deprecated Use `faker.string.hexadecimal()` instead.
+   * @deprecated Use `faker.string.hexadecimal()` or `faker.number.hex()` instead.
    */
   hexadecimal(
     options: {
@@ -258,7 +241,7 @@ export class DatatypeModule {
   ): string {
     deprecated({
       deprecated: 'faker.datatype.hexadecimal()',
-      proposed: 'faker.string.hexadecimal()',
+      proposed: 'faker.string.hexadecimal() or faker.number.hex()',
       since: '8.0',
       until: '9.0',
     });
@@ -280,7 +263,7 @@ export class DatatypeModule {
     properties.forEach((prop) => {
       returnObject[prop] = this.boolean()
         ? this.faker.string.sample()
-        : this.number();
+        : this.faker.number.int();
     });
 
     return JSON.stringify(returnObject);
@@ -299,7 +282,7 @@ export class DatatypeModule {
    */
   array(length = 10): Array<string | number> {
     return Array.from<string | number>({ length }).map(() =>
-      this.boolean() ? this.faker.string.sample() : this.number()
+      this.boolean() ? this.faker.string.sample() : this.faker.number.int()
     );
   }
 
@@ -320,6 +303,8 @@ export class DatatypeModule {
    * faker.datatype.bigInt({ min: 10n, max: 100n }) // 36n
    *
    * @since 6.0.0
+   *
+   * @deprecated Use `faker.number.bigInt()` instead.
    */
   bigInt(
     options?:
@@ -332,36 +317,12 @@ export class DatatypeModule {
           max?: bigint | boolean | number | string;
         }
   ): bigint {
-    let min: bigint;
-    let max: bigint;
-
-    if (typeof options === 'object') {
-      min = BigInt(options.min ?? 0);
-      max = BigInt(options.max ?? min + BigInt(999999999999999));
-    } else {
-      min = BigInt(0);
-      max = BigInt(options ?? 999999999999999);
-    }
-
-    if (max === min) {
-      return min;
-    }
-
-    if (max < min) {
-      throw new FakerError(`Max ${max} should be larger then min ${min}.`);
-    }
-
-    const delta = max - min;
-
-    const offset =
-      BigInt(
-        this.faker.string.numeric({
-          length: delta.toString(10).length,
-          allowLeadingZeros: true,
-        })
-      ) %
-      (delta + BigInt(1));
-
-    return min + offset;
+    deprecated({
+      deprecated: 'faker.datatype.bigInt()',
+      proposed: 'faker.number.bigInt()',
+      since: '8.0',
+      until: '9.0',
+    });
+    return this.faker.number.bigInt(options);
   }
 }