feat: add initial seed parameter to constructors (#3220)

4 files changed, 58 insertions, 10 deletions

diff --git a/src/faker.ts b/src/faker.ts
index 77630d29..0b03788b 100644
--- a/src/faker.ts
+++ b/src/faker.ts
@@ -125,6 +125,10 @@ export class Faker extends SimpleFaker {
    * Specify this only if you want to use it to achieve a specific goal,
    * such as sharing the same random generator with other instances/tools.
    * Defaults to faker's Mersenne Twister based pseudo random number generator.
+   * @param options.seed The initial seed to use.
+   * The seed can be used to generate reproducible values.
+   * Refer to the `seed()` method for more information.
+   * Defaults to a random seed.
    *
    * @example
    * import { Faker, es } from '@faker-js/faker';
@@ -157,8 +161,18 @@ export class Faker extends SimpleFaker {
      * @default generateMersenne53Randomizer()
      */
     randomizer?: Randomizer;
+
+    /**
+     * The initial seed to use.
+     * The seed can be used to generate reproducible values.
+     *
+     * Refer to the `seed()` method for more information.
+     *
+     * Defaults to a random seed.
+     */
+    seed?: number;
   }) {
-    super({ randomizer: options.randomizer });
+    super({ randomizer: options.randomizer, seed: options.seed });
 
     let { locale } = options;
 
diff --git a/src/internal/seed.ts b/src/internal/seed.ts
new file mode 100644
index 00000000..3ff484b2
--- /dev/null
+++ b/src/internal/seed.ts
@@ -0,0 +1,8 @@
+/**
+ * Generates a random seed.
+ *
+ * @internal
+ */
+export function randomSeed(): number {
+  return Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER);
+}
diff --git a/src/simple-faker.ts b/src/simple-faker.ts
index 743df923..1371e68a 100644
--- a/src/simple-faker.ts
+++ b/src/simple-faker.ts
@@ -1,3 +1,4 @@
+import { randomSeed } from './internal/seed';
 import { DatatypeModule } from './modules/datatype';
 import { SimpleDateModule } from './modules/date';
 import { SimpleHelpersModule } from './modules/helpers';
@@ -97,6 +98,10 @@ export class SimpleFaker {
    * Specify this only if you want to use it to achieve a specific goal,
    * such as sharing the same random generator with other instances/tools.
    * Defaults to faker's Mersenne Twister based pseudo random number generator.
+   * @param options.seed The initial seed to use.
+   * The seed can be used to generate reproducible values.
+   * Refer to the `seed()` method for more information.
+   * Defaults to a random seed.
    *
    * @example
    * import { SimpleFaker } from '@faker-js/faker';
@@ -120,11 +125,25 @@ export class SimpleFaker {
        * @default generateMersenne53Randomizer()
        */
       randomizer?: Randomizer;
+
+      /**
+       * The initial seed to use.
+       * The seed can be used to generate reproducible values.
+       *
+       * Refer to the `seed()` method for more information.
+       *
+       * Defaults to a random seed.
+       */
+      seed?: number;
     } = {}
   ) {
-    const { randomizer = generateMersenne53Randomizer() } = options;
+    const { randomizer, seed } = options;
+
+    if (randomizer != null && seed != null) {
+      randomizer.seed(seed);
+    }
 
-    this._randomizer = randomizer;
+    this._randomizer = randomizer ?? generateMersenne53Randomizer(seed);
   }
 
   /**
@@ -247,9 +266,7 @@ export class SimpleFaker {
    * @since 6.0.0
    */
   seed(seed?: number | number[]): number | number[];
-  seed(
-    seed: number | number[] = Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER)
-  ): number | number[] {
+  seed(seed: number | number[] = randomSeed()): number | number[] {
     this._randomizer.seed(seed);
 
     return seed;
diff --git a/src/utils/mersenne.ts b/src/utils/mersenne.ts
index 315335ab..585f84b5 100644
--- a/src/utils/mersenne.ts
+++ b/src/utils/mersenne.ts
@@ -1,10 +1,13 @@
 import { MersenneTwister19937 } from '../internal/mersenne';
+import { randomSeed } from '../internal/seed';
 import type { Randomizer } from '../randomizer';
 
 /**
  * Generates a MersenneTwister19937 randomizer with 32 bits of precision.
  * This is the default randomizer used by faker prior to v9.0.
  *
+ * @param seed The initial seed to use. Defaults to a random number.
+ *
  * @example
  * import { de, en, generateMersenne32Randomizer, Faker } from '@faker-js/faker';
  *
@@ -16,10 +19,12 @@ import type { Randomizer } from '../randomizer';
  *
  * @since 8.2.0
  */
-export function generateMersenne32Randomizer(): Randomizer {
+export function generateMersenne32Randomizer(
+  seed: number = randomSeed()
+): Randomizer {
   const twister = new MersenneTwister19937();
 
-  twister.initGenrand(Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER));
+  twister.initGenrand(seed);
 
   return {
     next(): number {
@@ -39,6 +44,8 @@ export function generateMersenne32Randomizer(): Randomizer {
  * Generates a MersenneTwister19937 randomizer with 53 bits of precision.
  * This is the default randomizer used by faker starting with v9.0.
  *
+ * @param seed The initial seed to use. Defaults to a random number.
+ *
  * @example
  * import { de, en, generateMersenne53Randomizer, Faker } from '@faker-js/faker';
  *
@@ -50,10 +57,12 @@ export function generateMersenne32Randomizer(): Randomizer {
  *
  * @since 9.0.0
  */
-export function generateMersenne53Randomizer(): Randomizer {
+export function generateMersenne53Randomizer(
+  seed: number = randomSeed()
+): Randomizer {
   const twister = new MersenneTwister19937();
 
-  twister.initGenrand(Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER));
+  twister.initGenrand(seed);
 
   return {
     next(): number {