feat: support custom randomizer

docs/.vitepress/api-pages.ts

@@ -30,5 +30,6 @@ export const apiPages = [
   { text: 'System', link: '/api/system.html' },
   { text: 'Vehicle', link: '/api/vehicle.html' },
   { text: 'Word', link: '/api/word.html' },
+  { text: 'Randomizer', link: '/api/randomizer.html' },
   { text: 'Utilities', link: '/api/utils.html' },
 ];

scripts/apidoc/fakerClass.ts

@@ -21,23 +21,33 @@ export async function processFakerClasses(
   return Promise.all(fakerClasses.map(processClass));
 }
 
+export async function processFakerRandomizer(
+  project: ProjectReflection
+): Promise<ModuleSummary> {
+  const randomizerClass = project
+    .getChildrenByKind(ReflectionKind.Interface)
+    .find((clazz) => clazz.name === 'Randomizer');
+
+  return processClass(randomizerClass);
+}
+
 async function processClass(
-  fakerClass: DeclarationReflection
+  clazz: DeclarationReflection
 ): Promise<ModuleSummary> {
-  const { name } = fakerClass;
-  const moduleFieldName = extractModuleFieldName(fakerClass);
+  const { name } = clazz;
+  const moduleFieldName = extractModuleFieldName(clazz);
 
   console.log(`Processing ${name} class`);
 
-  const { comment, deprecated, examples } = analyzeModule(fakerClass);
+  const { comment, deprecated, examples } = analyzeModule(clazz);
   const methods: Method[] = [];
 
-  console.debug(`- constructor`);
-  methods.push(await processConstructor(fakerClass));
+  if (hasConstructor(clazz)) {
+    console.debug(`- constructor`);
+    methods.push(await processConstructor(clazz));
+  }
 
-  methods.push(
-    ...(await processModuleMethods(fakerClass, `${moduleFieldName}.`))
-  );
+  methods.push(...(await processModuleMethods(clazz, `${moduleFieldName}.`)));
 
   return writeApiDocsModule(
     name,
@@ -49,20 +59,20 @@ async function processClass(
   );
 }
 
+function hasConstructor(clazz: DeclarationReflection): boolean {
+  return clazz
+    .getChildrenByKind(ReflectionKind.Constructor)
+    .some((constructor) => constructor.signatures.length > 0);
+}
+
 async function processConstructor(
-  fakerClass: DeclarationReflection
+  clazz: DeclarationReflection
 ): Promise<Method> {
-  const constructor = fakerClass.getChildrenByKind(
-    ReflectionKind.Constructor
-  )[0];
+  const constructor = clazz.getChildrenByKind(ReflectionKind.Constructor)[0];
 
   const signature = selectApiSignature(constructor);
 
-  const method = await analyzeSignature(
-    signature,
-    '',
-    `new ${fakerClass.name}`
-  );
+  const method = await analyzeSignature(signature, '', `new ${clazz.name}`);
 
   return {
     ...method,

scripts/apidoc/generate.ts

@@ -5,7 +5,7 @@ import {
   writeApiSearchIndex,
   writeSourceBaseUrl,
 } from './apiDocsWriter';
-import { processFakerClasses } from './fakerClass';
+import { processFakerClasses, processFakerRandomizer } from './fakerClass';
 import { processFakerUtilities } from './fakerUtilities';
 import { processModules } from './moduleMethods';
 import { loadProject } from './typedoc';
@@ -27,6 +27,7 @@ export async function generate(): Promise<void> {
     ...(await processModules(project)).sort((a, b) =>
       a.text.localeCompare(b.text)
     ),
+    await processFakerRandomizer(project),
     processFakerUtilities(project),
   ]);
   await writeApiPagesIndex(pages.map(({ text, link }) => ({ text, link })));

src/faker.ts

@@ -28,6 +28,7 @@ import { ScienceModule } from './modules/science';
 import { SystemModule } from './modules/system';
 import { VehicleModule } from './modules/vehicle';
 import { WordModule } from './modules/word';
+import type { Randomizer } from './randomizer';
 import { SimpleFaker } from './simple-faker';
 import { mergeLocales } from './utils/merge-locales';
 
@@ -123,6 +124,10 @@ export class Faker extends SimpleFaker {
    *
    * @param options The options to use.
    * @param options.locale The locale data to use.
+   * @param options.randomizer The Randomizer to use.
+   * 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.
    *
    * @example
    * import { Faker, es } from '@faker-js/faker';
@@ -144,6 +149,15 @@ export class Faker extends SimpleFaker {
      * @see mergeLocales
      */
     locale: LocaleDefinition | LocaleDefinition[];
+
+    /**
+     * The Randomizer to use.
+     * 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.
+     *
+     * @default generateMersenne32Randomizer()
+     */
+    randomizer?: Randomizer;
   });
   /**
    * Creates a new instance of Faker.
@@ -180,6 +194,10 @@ export class Faker extends SimpleFaker {
    * @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.randomizer The Randomizer to use.
+   * 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.
    *
    * @example
    * import { Faker, es } from '@faker-js/faker';
@@ -203,6 +221,15 @@ export class Faker extends SimpleFaker {
            * @see mergeLocales
            */
           locale: LocaleDefinition | LocaleDefinition[];
+
+          /**
+           * The Randomizer to use.
+           * 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.
+           *
+           * @default generateMersenne32Randomizer()
+           */
+          randomizer?: Randomizer;
         }
       | {
           /**
@@ -231,14 +258,18 @@ export class Faker extends SimpleFaker {
   );
   constructor(
     options:
-      | { locale: LocaleDefinition | LocaleDefinition[] }
+      | {
+          locale: LocaleDefinition | LocaleDefinition[];
+          randomizer?: Randomizer;
+        }
       | {
           locales: Record<string, LocaleDefinition>;
           locale?: string;
           localeFallback?: string;
+          randomizer?: Randomizer;
         }
   ) {
-    super();
+    super({ randomizer: options.randomizer });
 
     const { locales } = options as {
       locales: Record<string, LocaleDefinition>;

src/index.ts

@@ -128,5 +128,6 @@ export type { StringModule } from './modules/string';
 export type { SystemModule } from './modules/system';
 export type { VehicleModule } from './modules/vehicle';
 export type { WordModule } from './modules/word';
+export type { Randomizer } from './randomizer';
 export { SimpleFaker, simpleFaker } from './simple-faker';
 export { mergeLocales } from './utils/merge-locales';

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

@@ -1,3 +1,5 @@
+import type { Randomizer } from '../randomizer';
+
 /**
  * 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
 }
+
+/**
+ * Generates a MersenneTwister19937 randomizer with 32 bits of precision.
+ *
+ * @internal
+ */
+export function generateMersenne32Randomizer(): Randomizer {
+  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,6 @@
 import type { SimpleFaker } from '../..';
 import { FakerError } from '../../errors/faker-error';
 import { bindThisToMemberFunctions } from '../../internal/bind-this-to-member-functions';
-import type { Mersenne } from '../../internal/mersenne/mersenne';
 
 /**
  * Module to generate numbers of any kind.
@@ -83,10 +82,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 randomizer = this.faker._randomizer;
+    const real = randomizer.next();
     return Math.floor(real * (effectiveMax + 1 - effectiveMin) + effectiveMin);
   }
 
@@ -160,8 +158,8 @@ export class NumberModule {
     }
 
     // @ts-expect-error: access private member field
-    const mersenne: Mersenne = this.faker._mersenne;
-    const real = mersenne.next();
+    const randomizer = this.faker._randomizer;
+    const real = randomizer.next();
     return real * (max - min) + min;
   }
 

src/randomizer.ts

@@ -0,0 +1,57 @@
+/**
+ * Interface for a random number generator.
+ *
+ * **Note:** Normally there is no need to implement this interface directly,
+ * unless you want to achieve a specific goal with it.
+ *
+ * This interface enables you to use random generators from third party libraries such as [pure-rand](https://github.com/dubzzz/pure-rand).
+ *
+ * Instances are expected to be ready for use before being passed to any Faker constructor,
+ * this includes being `seed()`ed with either a random or fixed value.
+ *
+ * @example
+ * import { Randomizer, SimpleFaker } from '@faker-js/faker';
+ * import { RandomGenerator, xoroshiro128plus } from 'pure-rand';
+ *
+ * function generatePureRandRandomizer(
+ *   seed: number | number[] = Date.now() ^ (Math.random() * 0x100000000),
+ *   factory: (seed: number) => RandomGenerator = xoroshiro128plus
+ * ): Randomizer {
+ *   const self = {
+ *     next: () => (self.generator.unsafeNext() >>> 0) / 0x100000000,
+ *     seed: (seed: number | number[]) => {
+ *       self.generator = factory(typeof seed === 'number' ? seed : seed[0]);
+ *     },
+ *   } as Randomizer & { generator: RandomGenerator };
+ *   self.seed(seed);
+ *   return self;
+ * }
+ *
+ * const simpleFaker = new SimpleFaker({ randomizer: generatePureRandRandomizer() });
+ */
+export interface Randomizer {
+  /**
+   * 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).
+   *
+   * @example
+   * randomizer.next() // 0.3404027920160495
+   * randomizer.next() // 0.929890375900335
+   * randomizer.next() // 0.5866362918861691
+   */
+  next(): number;
+
+  /**
+   * Sets the seed to use.
+   *
+   * @param seed The seed to use.
+   *
+   * @example
+   * // Random seeds
+   * randomizer.seed(Date.now() ^ (Math.random() * 0x100000000));
+   * // Fixed seeds (for reproducibility)
+   * randomizer.seed(42);
+   * randomizer.seed([42, 13.37]);
+   */
+  seed(seed: number | number[]): void;
+}