Merge branch 'next' into infra/auto-bump/usage-guide-version

Author: ST-DDT

docs/guide/unique.md

@@ -10,7 +10,7 @@ faker.animal.type(); //'horse'
 faker.animal.type(); //'horse'
 ```
 
-Some methods and locales use much smaller data sets than others. For example, `faker.animal.type` has only 13 possible animals to choose from. In contrast, `faker.person.fullName()` pulls from a list of hundreds of first names, surnames, and prefixes/suffixes, so it can generate hundreds of thousands of unique names. Even then, the [birthday paradox](https://en.wikipedia.org/wiki/Birthday_Paradox) means that duplicate values will quickly be generated.
+Some methods and locales use much smaller data sets than others. For example, `faker.animal.type` has only 44 possible animals to choose from. In contrast, `faker.person.fullName()` pulls from a list of hundreds of first names, surnames, and prefixes/suffixes, so it can generate hundreds of thousands of unique names. Even then, the [birthday paradox](https://en.wikipedia.org/wiki/Birthday_Paradox) means that duplicate values will quickly be generated.
 
 Sometimes, you want to generate unique values. For example, you may wish to have unique values in a database email column.  
 There are a few possible strategies for this:

scripts/apidocs/processing/class.ts

@@ -13,7 +13,7 @@ import {
   processClassConstructors,
   processClassMethods,
   processInterfaceMethods,
-  processProjectFunctions,
+  processUtilityFunctions,
 } from './method';
 
 /**
@@ -192,12 +192,7 @@ export function processProjectUtilities(project: Project): RawApiDocsPage {
     deprecated: undefined,
     description: 'A list of all the utilities available in Faker.js.',
     examples: [],
-    methods: processProjectFunctions(
-      project,
-      'mergeLocales',
-      'generateMersenne32Randomizer',
-      'generateMersenne53Randomizer'
-    ),
+    methods: processUtilityFunctions(project),
   };
 }
 

scripts/apidocs/processing/method.ts

@@ -11,7 +11,6 @@ import {
   type MethodDeclaration,
 } from 'ts-morph';
 import { groupBy } from '../../../src/internal/group-by';
-import { valuesForKeys } from '../utils/value-checks';
 import { newProcessingError } from './error';
 import type {
   RawApiDocsSignature,
@@ -138,12 +137,11 @@ function getAllFunctions(
   );
 }
 
-export function processProjectFunctions(
-  project: Project,
-  ...names: string[]
-): RawApiDocsMethod[] {
+export function processUtilityFunctions(project: Project): RawApiDocsMethod[] {
   return processMethodLikes(
-    valuesForKeys(getAllFunctions(project), names),
+    Object.values(getAllFunctions(project)).filter((fn) =>
+      fn.getSourceFile().getFilePath().includes('/src/utils/')
+    ),
     (f) => f.getNameOrThrow()
   );
 }

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;
 

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

src/modules/finance/index.ts

@@ -1,4 +1,5 @@
 import { FakerError } from '../../errors/faker-error';
+import { deprecated } from '../../internal/deprecated';
 import { ModuleBase } from '../../internal/module-base';
 import type { BitcoinAddressFamilyType, BitcoinNetworkType } from './bitcoin';
 import {
@@ -202,6 +203,8 @@ export class FinanceModule extends ModuleBase {
    * faker.finance.maskedNumber(3) // '(...342)'
    *
    * @since 8.0.0
+   *
+   * @deprecated Use `faker.finance.iban().replace(/(?<=.{4})\w(?=.{2})/g, '*')` or a similar approach instead.
    */
   maskedNumber(length?: number): string;
   /**
@@ -219,6 +222,8 @@ export class FinanceModule extends ModuleBase {
    * faker.finance.maskedNumber({ length: 3, parens: false, ellipsis: false }) // '298'
    *
    * @since 8.0.0
+   *
+   * @deprecated Use `faker.finance.iban().replace(/(?<=.{4})\w(?=.{2})/g, '*')` or a similar approach instead.
    */
   maskedNumber(options?: {
     /**
@@ -256,6 +261,8 @@ export class FinanceModule extends ModuleBase {
    * faker.finance.maskedNumber({ length: 3, parens: false, ellipsis: false }) // '298'
    *
    * @since 8.0.0
+   *
+   * @deprecated Use `faker.finance.iban().replace(/(?<=.{4})\w(?=.{2})/g, '*')` or a similar approach instead.
    */
   maskedNumber(
     optionsOrLength?:
@@ -297,6 +304,8 @@ export class FinanceModule extends ModuleBase {
    * faker.finance.maskedNumber({ length: 3, parens: false, ellipsis: false }) // '298'
    *
    * @since 8.0.0
+   *
+   * @deprecated Use `faker.finance.iban().replace(/(?<=.{4})\w(?=.{2})/g, '*')` or a similar approach instead.
    */
   maskedNumber(
     options:
@@ -322,6 +331,14 @@ export class FinanceModule extends ModuleBase {
           ellipsis?: boolean;
         } = {}
   ): string {
+    deprecated({
+      deprecated: 'faker.finance.maskedNumber()',
+      proposed:
+        "faker.finance.iban().replace(/(?<=.{4})\\w(?=.{2})/g, '*') or a similar approach",
+      since: '9.3.0',
+      until: '10.0.0',
+    });
+
     if (typeof options === 'number') {
       options = { length: options };
     }
@@ -952,7 +969,7 @@ export class FinanceModule extends ModuleBase {
    *
    * @example
    * faker.finance.transactionDescription()
-   * // 'invoice transaction at Kilback - Durgan using card ending with ***(...4316) for UAH 783.82 in account ***16168663'
+   * // 'invoice transaction at Kilback - Durgan using card ending with ************4316 for UAH 783.82 in account ***16168663'
    *
    * @since 5.1.0
    */
@@ -961,9 +978,9 @@ export class FinanceModule extends ModuleBase {
     const company = this.faker.company.name();
     const transactionType = this.transactionType();
     const account = this.accountNumber();
-    const card = this.maskedNumber();
+    const card = this.creditCardNumber().replaceAll(/.(?=.{4})/g, '*');
     const currency = this.currencyCode();
 
-    return `${transactionType} transaction at ${company} using card ending with ***${card} for ${currency} ${amount} in account ***${account}`;
+    return `${transactionType} transaction at ${company} using card ending with ${card} for ${currency} ${amount} in account ***${account}`;
   }
 }

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;

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 {

test/faker.spec.ts

@@ -1,18 +1,10 @@
 import type { MockInstance } from 'vitest';
 import { describe, expect, it, vi } from 'vitest';
-import { Faker, faker } from '../src';
+import { Faker, faker, generateMersenne32Randomizer } from '../src';
 import { FakerError } from '../src/errors/faker-error';
 import { keys } from '../src/internal/keys';
 
 describe('faker', () => {
-  it('should throw error if no locales passed', () => {
-    expect(() => new Faker({ locale: [] })).toThrow(
-      new FakerError(
-        'The locale option must contain at least one locale definition.'
-      )
-    );
-  });
-
   it('should not log anything on startup', async () => {
     const spies: MockInstance[] = keys(console)
       .filter((key) => typeof console[key] === 'function')
@@ -69,19 +61,70 @@ describe('faker', () => {
     });
   });
 
-  describe('randomizer', () => {
-    it('should be possible to provide a custom Randomizer', () => {
-      const customFaker = new Faker({
-        locale: {},
-        randomizer: {
-          next: () => 0,
-          seed: () => void 0,
-        },
+  describe('constructor()', () => {
+    describe('locale', () => {
+      it('should throw error if no locales passed', () => {
+        expect(() => new Faker({ locale: [] })).toThrow(
+          new FakerError(
+            'The locale option must contain at least one locale definition.'
+          )
+        );
+      });
+    });
+
+    describe('randomizer', () => {
+      it('should be possible to provide a custom Randomizer', () => {
+        const customFaker = new Faker({
+          locale: {},
+          randomizer: {
+            next: () => 0,
+            seed: () => void 0,
+          },
+        });
+
+        expect(customFaker.number.int()).toBe(0);
+        expect(customFaker.number.int()).toBe(0);
+        expect(customFaker.number.int()).toBe(0);
+      });
+    });
+
+    describe('seed', () => {
+      it('should be possible to provide an initial seed', () => {
+        const customFaker = new Faker({
+          locale: {},
+          seed: 12345,
+        });
+
+        expect(customFaker.number.int()).toBe(8373237378417847);
+        expect(customFaker.number.int()).toBe(2849657659447330);
+        expect(customFaker.number.int()).toBe(1656593383470774);
+
+        customFaker.seed(12345);
+
+        expect(customFaker.number.int()).toBe(8373237378417847);
+        expect(customFaker.number.int()).toBe(2849657659447330);
+        expect(customFaker.number.int()).toBe(1656593383470774);
       });
+    });
 
-      expect(customFaker.number.int()).toBe(0);
-      expect(customFaker.number.int()).toBe(0);
-      expect(customFaker.number.int()).toBe(0);
+    describe('randomizer+seed', () => {
+      it('should take apply both the randomizer and seed', () => {
+        const customFaker = new Faker({
+          locale: {},
+          randomizer: generateMersenne32Randomizer(67890),
+          seed: 12345,
+        });
+
+        expect(customFaker.number.int()).toBe(8373237322874880);
+        expect(customFaker.number.int()).toBe(8017800868134912);
+        expect(customFaker.number.int()).toBe(2849657711493120);
+
+        customFaker.seed(12345); // Retry with the expected seed
+
+        expect(customFaker.number.int()).toBe(8373237322874880);
+        expect(customFaker.number.int()).toBe(8017800868134912);
+        expect(customFaker.number.int()).toBe(2849657711493120);
+      });
     });
   });
 

test/internal/seed.spec.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+import { randomSeed } from '../../src/internal/seed';
+
+describe('seed', () => {
+  it('should generate a random seed', () => {
+    const actual = randomSeed();
+
+    expect(actual).toBeTypeOf('number');
+    expect(actual).not.toBe(randomSeed());
+  });
+});