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.