feat: support custom randomizer

src/faker.ts

@@ -1,8 +1,7 @@
 import type { LocaleDefinition, MetadataDefinition } from './definitions';
 import { FakerError } from './errors/faker-error';
 import { deprecated } from './internal/deprecated';
-import type { Mersenne } from './internal/mersenne/mersenne';
-import mersenne from './internal/mersenne/mersenne';
+import { generateMersennePRNG } from './internal/mersenne';
 import type { LocaleProxy } from './locale-proxy';
 import { createLocaleProxy } from './locale-proxy';
 import { AirlineModule } from './modules/airline';
@@ -33,6 +32,7 @@ import { StringModule } from './modules/string';
 import { SystemModule } from './modules/system';
 import { VehicleModule } from './modules/vehicle';
 import { WordModule } from './modules/word';
+import type { PRNG } from './prng';
 import { mergeLocales } from './utils/merge-locales';
 
 /**
@@ -114,7 +114,7 @@ export class Faker {
   }
 
   /** @internal */
-  private readonly _mersenne: Mersenne = mersenne();
+  private readonly _prng: PRNG;
 
   /**
    * @deprecated Use the modules specific to the type of data you want to generate instead.
@@ -184,6 +184,8 @@ export class Faker {
    *
    * @param options The options to use.
    * @param options.locale The locale data to use.
+   * @param options.prng The PRNG to use. Defaults to faker's Mersenne Twister based PRNG.
+   * Only overwrite this if you want to reuse the same PRNG in different libraries to ensure reproducible results across all of them.
    *
    * @example
    * import { Faker, es } from '@faker-js/faker';
@@ -205,6 +207,14 @@ export class Faker {
      * @see mergeLocales
      */
     locale: LocaleDefinition | LocaleDefinition[];
+
+    /**
+     * The PRNG to use. Defaults to faker's Mersenne Twister based PRNG.
+     * Only overwrite this if you want to reuse the same PRNG in different libraries to ensure reproducible results across all of them.
+     *
+     * @default newMersennePRNG()
+     */
+    prng?: PRNG;
   });
   /**
    * Creates a new instance of Faker.
@@ -241,6 +251,8 @@ export class Faker {
    * @param options.locale The locale data to use or the name of the main locale.
    * @param options.locales The locale data to use.
    * @param options.localeFallback The name of the fallback locale to use.
+   * @param options.prng The PRNG to use. Defaults to faker's Mersenne Twister based PRNG.
+   * Only overwrite this if you want to reuse the same PRNG in different libraries to ensure reproducible results across all of them.
    *
    * @example
    * import { Faker, es } from '@faker-js/faker';
@@ -264,6 +276,14 @@ export class Faker {
            * @see mergeLocales
            */
           locale: LocaleDefinition | LocaleDefinition[];
+
+          /**
+           * The PRNG to use. Defaults to faker's Mersenne Twister based PRNG.
+           * Only overwrite this if you want to reuse the same PRNG in different libraries to ensure reproducible results across all of them.
+           *
+           * @default newMersennePRNG()
+           */
+          prng?: PRNG;
         }
       | {
           /**
@@ -292,11 +312,12 @@ export class Faker {
   );
   constructor(
     options:
-      | { locale: LocaleDefinition | LocaleDefinition[] }
+      | { locale: LocaleDefinition | LocaleDefinition[]; prng?: PRNG }
       | {
           locales: Record<string, LocaleDefinition>;
           locale?: string;
           localeFallback?: string;
+          prng?: PRNG;
         }
   ) {
     const { locales } = options as {
@@ -332,6 +353,7 @@ export class Faker {
       locale = mergeLocales(locale);
     }
 
+    this._prng = options.prng ?? generateMersennePRNG();
     this.rawDefinitions = locale as LocaleDefinition;
     this.definitions = createLocaleProxy(this.rawDefinitions);
   }
@@ -453,7 +475,7 @@ export class Faker {
   seed(
     seed: number | number[] = Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER)
   ): number | number[] {
-    this._mersenne.seed(seed);
+    this._prng.seed(seed);
 
     return seed;
   }

src/internal/mersenne/twister.ts → src/internal/mersenne.ts

@@ -1,3 +1,5 @@
+import type { PRNG } from '../prng';
+
 /**
  * Copyright (c) 2022-2023 Faker
  *
@@ -71,7 +73,7 @@
  *
  * @internal
  */
-export default class MersenneTwister19937 {
+class MersenneTwister19937 {
   private readonly N = 624;
   private readonly M = 397;
   private readonly MATRIX_A = 0x9908b0df; // constant vector a
@@ -323,3 +325,27 @@ export default class MersenneTwister19937 {
   }
   // These real versions are due to Isaku Wada, 2002/01/09
 }
+
+/**
+ * Generate seed based random numbers.
+ *
+ * @internal
+ */
+export function generateMersennePRNG(): PRNG {
+  const twister = new MersenneTwister19937();
+
+  twister.initGenrand(Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER));
+
+  return {
+    next(): number {
+      return twister.genrandReal2();
+    },
+    seed(seed: number | number[]): void {
+      if (typeof seed === 'number') {
+        twister.initGenrand(seed);
+      } else if (Array.isArray(seed)) {
+        twister.initByArray(seed, seed.length);
+      }
+    },
+  };
+}

src/modules/number/index.ts

@@ -1,7 +1,7 @@
 import type { Faker } from '../..';
 import { FakerError } from '../../errors/faker-error';
 import { bindThisToMemberFunctions } from '../../internal/bind-this-to-member-functions';
-import type { Mersenne } from '../../internal/mersenne/mersenne';
+import type { PRNG } from '../../prng';
 
 /**
  * Module to generate numbers of any kind.
@@ -83,10 +83,9 @@ export class NumberModule {
       throw new FakerError(`Max ${max} should be greater than min ${min}.`);
     }
 
-    const mersenne: Mersenne =
-      // @ts-expect-error: access private member field
-      this.faker._mersenne;
-    const real = mersenne.next();
+    // @ts-expect-error: access private member field
+    const { _prng: prng }: PRNG = this.faker;
+    const real = prng.next();
     return Math.floor(real * (effectiveMax + 1 - effectiveMin) + effectiveMin);
   }
 
@@ -160,8 +159,8 @@ export class NumberModule {
     }
 
     // @ts-expect-error: access private member field
-    const mersenne: Mersenne = this.faker._mersenne;
-    const real = mersenne.next();
+    const { _prng: prng }: PRNG = this.faker;
+    const real = prng.next();
     return real * (max - min) + min;
   }
 

src/prng.ts

@@ -0,0 +1,17 @@
+/**
+ * Interface for a pseudo-random number generator.
+ */
+export interface PRNG {
+  /**
+   * Generates a random float between `[0, 1)`.
+   * This method is called `next` so that it could be used as an [iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol)
+   */
+  next(): number;
+
+  /**
+   * Sets the seed to use.
+   *
+   * @param seed The seed to use.
+   */
+  seed(seed: number | number[]): void;
+}

test/all_functional.spec.ts

@@ -6,7 +6,7 @@ const IGNORED_MODULES = [
   'rawDefinitions',
   'definitions',
   'helpers',
-  '_mersenne',
+  '_prng',
   '_defaultRefDate',
 ];
 

test/faker.spec.ts

@@ -68,6 +68,22 @@ describe('faker', () => {
     });
   });
 
+  describe('prng', () => {
+    it('should be possible to provide a custom prng', () => {
+      const customFaker = new Faker({
+        locale: {},
+        prng: {
+          next: () => 0,
+          seed: () => void 0,
+        },
+      });
+
+      expect(customFaker.number.int()).toBe(0);
+      expect(customFaker.number.int()).toBe(0);
+      expect(customFaker.number.int()).toBe(0);
+    });
+  });
+
   // This is only here for coverage
   // The actual test is in mersenne.spec.ts
   describe('seed()', () => {

test/mersenne.spec.ts

@@ -1,23 +1,23 @@
 import { beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import type { Mersenne } from '../src/internal/mersenne/mersenne';
-import mersenneFn from '../src/internal/mersenne/mersenne';
+import { generateMersennePRNG } from '../src/internal/mersenne';
+import type { PRNG } from '../src/prng';
 import { seededRuns } from './support/seededRuns';
 import { times } from './support/times';
 
 const NON_SEEDED_BASED_RUN = 25;
 
 describe('mersenne twister', () => {
-  const mersenne: Mersenne = mersenneFn();
+  const prng: PRNG = generateMersennePRNG();
 
   describe.each(
     [...seededRuns, ...seededRuns.map((v) => [v, 1, 2])].map((v) => [v])
   )('seed: %j', (seed) => {
     beforeEach(() => {
-      mersenne.seed(seed);
+      prng.seed(seed);
     });
 
     it('should return deterministic value for next()', () => {
-      const actual = mersenne.next();
+      const actual = prng.next();
 
       expect(actual).toMatchSnapshot();
     });
@@ -35,12 +35,12 @@ describe('mersenne twister', () => {
     ])
   )('random seeded tests %j', (seed) => {
     beforeAll(() => {
-      mersenne.seed(seed);
+      prng.seed(seed);
     });
 
     describe('next', () => {
       it('should return random number from interval [0, 1)', () => {
-        const actual = mersenne.next();
+        const actual = prng.next();
 
         expect(actual).toBeGreaterThanOrEqual(0);
         expect(actual).toBeLessThan(1);