feat: support custom randomizer

[ST-DDT]

Adds the ability to Faker to use a custom prng.

• Required for feat: introduce faker.clone and derive #1499
• Implements Customize the PRNG used by faker #2195

Intended use case for clone and derive:

  clone(): Faker {
    const instance = new Faker({
      locale: this.rawDefinitions,
      prng: this.prng.clone(),
    });
    instance.setDefaultRefDate(this._defaultRefDate);
    return instance;
  }

  derive(): Faker {
    const instance = new Faker({
      locale: this.rawDefinitions,
      prng: this.prng.derive(),
    });
    instance.setDefaultRefDate(this._defaultRefDate);
    return instance;
  }

(Regardless of whether we will actually have either of them)

Intended use case cross compatibility with other libraries other than faker:

const prng = newPRNG();
const customFaker = new Faker({ ..., prng });
const randExp = new new RandExp(/no{1,}/, { prng });

prng.setSeed(1337);
customFaker.number.int(); // 1st seed value
randExp.gen(); // 2nd seed value
customFaker.string.sample(); // 3rd seed value

Note: Currently faker's internal PRNG isn't exported.

[codecov]

Codecov Report

Merging #2284 (f98c2ee) into next (88b2443) will decrease coverage by 0.03%.
The diff coverage is 58.33%.

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #2284      +/-   ##
==========================================
- Coverage   99.61%   99.58%   -0.03%     
==========================================
  Files        2820     2820              
  Lines      253880   253975      +95     
  Branches     1101     1102       +1     
==========================================
+ Hits       252891   252923      +32     
- Misses        962     1024      +62     
- Partials       27       28       +1     

Files	Coverage Δ
src/faker.ts	89.13% <100.00%> (+0.90%)	⬆️
src/index.ts	100.00% <100.00%> (ø)
src/internal/mersenne.ts	96.29% <100.00%> (ø)
src/modules/number/index.ts	100.00% <100.00%> (ø)
src/simple-faker.ts	100.00% <100.00%> (ø)
src/randomizer.ts	0.00% <0.00%> (ø)

... and 2 files with indirect coverage changes

[ST-DDT]

We have to decide whether we want to merge this in v8.x or v9.
If we merge it in v9 we can rename the option/field/type to random/Random without breaking things/causing confusion.

[ST-DDT]

Blocked by #2361 as it may require changes to the Mersenne interface.

• number.float is unable to return 1/max exactly #2361

[Shinigami92]

This PR should not be set on-hold, but the other way around: #2361 / #2357 should be set on hold and related to this PR
See the last two days of discussion in #2357

[ST-DDT]

This PR should not be set on-hold, but the other way around: #2361 / #2357 should be set on hold and related to this PR See the last two days of discussion in #2357

As mentioned in the team meeting. The exposed API is dependent on the decisions we make for those issues.
I don't like merging a public API PR, when it is likely to require changes or at least a more detailed specification.

[Shinigami92]

This PR should not be set on-hold, but the other way around: #2361 / #2357 should be set on hold and related to this PR See the last two days of discussion in #2357

As mentioned in the team meeting. The exposed API is dependent on the decisions we make for those issues. I don't like merging a public API PR, when it is likely to require changes or at least a more detailed specification.

Ah ok I see, you want to wait half a week until we all decide and write down that we agree with the Math.random => [0.0,1.0) contract 👌

outdated

[matthewmayer]

Should we add an example of how you go from a prebuilt localised Faker instance (say fakerEN_GB) to a version with a custom randomizer? That may not be that intuitive as I think you'd have to drop the prebuilt instance and use manual fallback locales in order to access the Faker constructor.

[ST-DDT]

Could you please write it in pseudocode? I'm not sure what you are asking for.

[matthewmayer]

// if you are currently using a prebuilt version of Faker 
import {fakerEN_GB as faker} from '@faker-js/faker';
console.log(faker.location.city())

// you will need to manually construct a new Faker instance with the correct fallback languages
// and then you can set a custom randomizer function
import { Faker, en, en_GB, base } from '@faker-js/faker';
const faker2 = new Faker({
  locale: [en_GB, en, base],
  randomizer: yourCustomRandomizerFunction
})
console.log(faker2.location.city())

[ST-DDT]

I think adding the Faker constructor with some ommissions should be plenty. Maybe we should add a link to the constructor though.

Const faker2 = new Faker({
  locale: ...,
  randomizer: newRandomizer(),
});

And @see Faker#constructor

[matthewmayer]

It's more guiding people that they cannot simply do something like

fakerEN_GB.randomizer = ...

[ST-DDT]

Here the updated screenshots for the documentation:

Click to expand

http://localhost:5173/api/randomizer.html

http://localhost:5173/guide/randomizer.html

[dubzzz]

From the updated documentation you sent, the API looks great. I'm looking forward to connect it 🥰

Thanks a lot for it 👍