feat: introduce faker.clone and derive

[ST-DDT]

Fixes #627

• Get the ".last()" value generated of a module #627

Required for:

• docs(guide): add reproducible results page (WIP) #1491

See also:

• Deterministic values #1413

---

This PR introduces two new methods for faker.

• faker.clone()
• faker.derive()

clone()

Can be used to generate repeated values or to allow generating the "last" value again.
This method does not consume seed values.

Example

faker.seed(42);
faker.clone().datatype.number(); // 8234
faker.clone().datatype.number(); // 8234
faker.datatype.number(); // 8234

last() was originally requested in #627

derive()

Can be used to write methods that don't affect the rest of the generated data when changed.
This method consumes a single seed value in order to initialize the seed of the derived instance.

Example

function generatePerson(): Person {
  const derived = faker.derive();
  return {
    firstName: derived.person.firstName(),
    lastName: derived.person.lastName(),
    // You can add more attributes here without affecting the next person
    ...
  };
}

faker.seed(42);
generatePerson(); // { firstName: 'Devyn', lastName: 'Foo', ... }
generatePerson(); // { firstName: 'John', lastName: 'Bar', ... }

I evolved the fork() method into derive() while thinking about #1491 as it is incredible hard for our users to write extensible methods while retaining their original data. It basically makes generatePerson or any similar method an atomic operation regardless how many data are generated.

It can also be used to with nesting.

function generateMarriageCertificate(faker: Faker): MarriageCertificate {
  const derived = faker.derive();
  return {
    partner1: generatePerson(derived),
    partner2: generatePerson(derived),
    certifyingOffice: derived.location.city(),
  };
}

function generatePerson(faker: Faker): Person {
  const derived = faker.derive();
  return {
    firstName: derived.person.firstName(),
    lastName: derived.person.lastName(),
    // You can add more attributes here without affecting the next person
    ...
  };
}

Alternatives

1. Add a context option to clone(), that mutates the seed (current seed + context -> new seed).
   However, I think the consumption of a seed value is actually expected, so that partner/marriage certificate 1 and 2 are different.

2. Add a seed option to clone and use it like faker.fork({seed: faker.datatype.number()}).
   However that would just be a a more verbose version of the current derive method.

---

Food for thoughts: We could use the derive method in our code/methods to ensure each faker method call consumes only a single seed value. However this would probably (slightly) decrease performance.

[codecov]

Codecov Report

Attention: 26 lines in your changes are missing coverage. Please review.

Comparison is base (bc3ebb7) 99.57% compared to head (93dd407) 99.56%.

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #1499      +/-   ##
==========================================
- Coverage   99.57%   99.56%   -0.01%     
==========================================
  Files        2807     2807              
  Lines      250526   250652     +126     
  Branches     1153     1161       +8     
==========================================
+ Hits       249464   249574     +110     
- Misses       1034     1078      +44     
+ Partials       28        0      -28     

Files	Coverage Δ
src/faker.ts	90.22% <100.00%> (+0.33%)	⬆️
src/internal/mersenne.ts	98.16% <100.00%> (+0.71%)	⬆️
src/simple-faker.ts	100.00% <100.00%> (ø)
src/randomizer.ts	0.00% <0.00%> (ø)

... and 28 files with indirect coverage changes

[ST-DDT]

Ready for review

[xDivisionByZerox]

Great documentation, @ST-DDT! Really enjoyed reading through it 😄

[ST-DDT]

Blocked by #2284

• feat: support custom randomizer #2284

[Shinigami92]

This would solve the problem of copycat: https://github.com/snaplet/copycat#the-problem

[ST-DDT]

This would solve the problem of copycat: snaplet/copycat#the-problem

I would recommend using a custom Randomizer (!=Mersenne) e.g. from pure-random, that has shorter initialization times.
The Mersenne Twister is optimized to generate multiple random values.

This will also (potentially) get much more easier with v9's independent methods that can be called just like this firstName(fakerCore, ...args) that doesn't need a full faker instance anymore.