feat: support custom randomizer (#2284)

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' },
 ];

docs/.vitepress/config.ts

@@ -200,6 +200,10 @@ const config = defineConfig({
             text: 'Frameworks',
             link: '/guide/frameworks',
           },
+          {
+            text: 'Randomizer',
+            link: '/guide/randomizer',
+          },
           {
             text: 'Upgrading to v8',
             link: '/guide/upgrading',

docs/guide/randomizer.md

@@ -0,0 +1,116 @@
+# Randomizer
+
+The [`Randomizer`](/api/randomizer) interface allows you to use a custom randomness source within Faker.
+
+::: warning Important
+Faker's default `Randomizer` is sufficient in most cases.
+Change this only if you want to use it to achieve a specific goal, such as sharing the same random generator with other instances/tools.
+:::
+
+There are two connected use cases we have considered where this might be needed:
+
+1. Re-Use of the same `Randomizer` within multiple `Faker` instances.
+2. The use of a random number generator from a third party library.
+
+## Using `Randomizer`s
+
+A `Randomizer` has to be set during construction of the instance:
+
+```ts
+import { Faker, Randomizer } from '@faker-js/faker';
+
+const customFaker = new Faker({
+  locale: ...,
+  randomizer: ...,
+});
+```
+
+The following methods take a `Randomizer` as argument:
+
+- [new SimpleFaker(...)](/api/simpleFaker#constructor)
+- [new Faker(...)](/api/faker#constructor)
+
+## Re-Using a `Randomizer`
+
+Sometimes it might be required to generate values in two different locales.
+E.g. a Chinese person might have an English identity to simplify the communication with foreigners.
+While this could also be achieved with two independent `Faker` instances like this:
+
+```ts
+import { fakerEN, fakerZH_TW } from '@faker-js/faker';
+
+fakerZH_TW.seed(5);
+fakerEN.seed(5);
+
+const firstName = fakerZH_TW.person.firstName(); // 炫明
+const alias = fakerEN.person.firstName(); // Arthur
+```
+
+There might be issues regarding reproducibility, when seeding only one of them.
+
+By sharing a `Randomizer` between the two instances, you omit this issue by affecting all instances simultaneously.
+
+::: tip Note
+This gets more important if the seeding happens at a different location than the data generation (e.g. due to nesting).
+:::
+
+```ts
+import { en, Faker, Randomizer, zh_TW } from '@faker-js/faker';
+
+const randomizer: Randomizer = ...;
+
+const customFakerEN = new Faker({
+  locale: en,
+  randomizer,
+});
+
+const customFakerZH_TW = new Faker({
+  locale: [zh_TW, en],
+  randomizer,
+});
+
+randomizer.seed(5);
+// customFakerEN.seed(5); // Redundant
+// customFakerZH_TW.seed(5); // Redundant
+
+const firstName = fakerZH_TW.person.firstName(); // 炫明
+const alias = fakerEN.person.firstName(); // John (different from before, because it is now the second call)
+```
+
+This is also relevant when trying to use faker's random number generator in third party libraries.
+E.g. some libraries that can generate `string`s from a `RegExp` can be customized with a custom random number generator as well,
+and since they will be used in the same context it makes sense to rely on the same randomness source to ensure the values are reproducible.
+
+## Third-Party `Randomizer`s
+
+Sometimes you might want to use a custom/third-party random number generator.
+This can be achieved by implementing your own `Randomizer` and passing it to [supported methods](#using-randomizers).
+
+::: tip Note
+Faker does not ship `Randomizers` for third-party libraries and does not provide support for bridging the gap between libraries.
+The following examples show how the interface can be implemented, but they are not tested for correctness.
+Feel free to submit more `Randomizer` examples for other popular packages.
+:::
+
+### Pure-Rand
+
+The following is an example for a [pure-rand](https://github.com/dubzzz/pure-rand) based `Randomizer`:
+
+```ts
+import { Faker, Randomizer, SimpleFaker } from '@faker-js/faker';
+import { RandomGenerator, xoroshiro128plus } from 'pure-rand';
+
+export 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;
+}
+```

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);
+      }
+    },
+  };
+}