feat: introduce faker.clone and derive

docs/guide/randomizer.md

@@ -104,13 +104,19 @@ 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;
+ function wrapperFactory(generator?: RandomGenerator): Randomizer {
+ const self = {
+ next: () => (self.generator.unsafeNext() >>> 0) / 0x100000000,
+ seed: (seed: number | number[]) => {
+ self.generator = factory(typeof seed === 'number' ? seed : seed[0]);
+ },
+ clone: () => wrapperFactory(self.generator.clone()),
+ } as Randomizer & { generator: RandomGenerator };
+ return self;
+ }
+
+ const randomizer = wrapperFactory();
+ randomizer.seed(seed);
+ return randomizer;
 }
 ```

docs/guide/usage.md

@@ -275,3 +275,188 @@ We will update these docs once a replacement is available.
 :::
 
 Congratulations, you should now be able to create any complex object you desire. Happy faking 🥳.
+
+## Create multiple complex objects
+
+Sometimes having a single one of your complex objects isn't enough.
+Imagine having a list view/database of some kind you want to populate:
+
+| ID | First Name | Last Name |
+| --------- | ---------- | --------- |
+| 6fbe024f… | Tatyana | Koch |
+| 862f3ccb… | Hans | Donnelly |
+| b452acd6… | Judy | Boehm |
+
+The values are directly created using this method:
+
+```ts
+import { faker } from '@faker-js/faker';
+
+function createRandomUser(): User {
+ return {
+ _id: faker.string.uuid(),
+ firstName: faker.person.firstName(),
+ lastName: faker.person.lastName(),
+ };
+}
+
+const users = Array.from({ length: 3 }, () => createRandomUser());
+```
+
+After some time you notice that you need a new column `createdDate`.
+
+You modify the method to also create that:
+
+```ts
+function createRandomUser(): User {
+ return {
+ _id: faker.string.uuid(),
+ firstName: faker.person.firstName(),
+ lastName: faker.person.lastName(),
+ createdDate: faker.date.past(),
+ };
+}
+```
+
+Now let's have a look at our table again:
+
+| ID | First Name | Last Name | Created Date |
+| --------- | ---------- | --------- | ------------ |
+| 6fbe024f… | Tatyana | Koch | 2022-12-28 |
+| 62f3ccbf… | Kacie | Pouros | 2023-04-06 |
+| 52acd600… | Aron | Von | 2023-05-04 |
+
+Suddenly the second line onwards look different.
+
+Why? Because calling `faker.date.past()` consumes a value from the seed changing all subsequent values.
+
+There are two solutions to that:
+
+1. Set the seed explicitly before creating the data for that row:
+
+```ts
+const users = Array.from({ length: 3 }, (_, i) => {
+ faker.seed(i);
+ return createRandomUser();
+});
+```
+
+Which is very straightforward, but comes at the disadvantage, that you change the seed of your faker instance.
+This might cause issues, if you have lists of groups that contains lists of users. Each group contains the same users because the seed is reset.
+
+2. Derive a new faker instance for each user you create.
+
+```ts
+function createRandomUser(faker: Faker): User {
+ const derivedFaker = faker.derive();
+ return {
+ _id: derivedFaker.string.uuid(),
+ firstName: derivedFaker.person.firstName(),
+ lastName: derivedFaker.person.lastName(),
+ createdDate: derivedFaker.date.past(),
+ };
+}
+
+const users = Array.from({ length: 3 }, () => createRandomUser(faker));
+```
+
+The `faker.derive()` call clones the instance and re-initializes the seed of the clone with a generated value from the original.
+This decouples the generation of the list from generating a user.
+It does not matter how many properties you add to or remove from the `User` the following rows will not change.
+
+::: tip Note
+The following is only relevant, if you want to avoid changing your generated objects as much as possible:
+
+When adding one or more new properties, we recommend generating them last, because if you create a new property in the middle of your object, then the properties after that will still change (due to the extra seed consumption).
+When removing properties, you can continue calling the old method (or a dummy method) to consume the same amount of seed values.
+:::
+
+This also works for deeply nested complex objects:
+
+```ts
+function createLegalAgreement(faker: Faker) {
+ const derivedFaker = faker.derive();
+ return {
+ _id: derivedFaker.string.uuid(),
+ partyA: createRandomUser(derivedFaker),
+ partyB: createRandomUser(derivedFaker),
+ };
+}
+
+function createRandomUser(faker: Faker): User {
+ const derivedFaker = faker.derive();
+ return {
+ _id: derivedFaker.string.uuid(),
+ firstName: derivedFaker.person.firstName(),
+ lastName: derivedFaker.person.lastName(),
+ createdDate: derivedFaker.date.past(),
+ address: createRandomAddress(derivedFaker),
+ };
+}
+
+function createRandomAddress(faker: Faker): Address {
+ const derivedFaker = faker.derive();
+ return {
+ _id: derivedFaker.string.uuid(),
+ streetName: derivedFaker.location.street(),
+ };
+}
+```
+
+::: warning Warning
+Migrating your existing data generators will still change all data once, but after that they are independent.
+So we recommend writing your methods like this from the start.
+:::
+
+::: info Note
+Depending on your preferences and requirements you can design the methods either like this:
+
+```ts
+function createRandomXyz(faker: Faker): Xyz {
+ return {
+ _id: faker.string.uuid(),
+ };
+}
+
+createRandomXyz(faker.derive());
+createRandomXyz(faker.derive());
+createRandomXyz(faker.derive());
+```
+
+or this
+
+```ts
+function createRandomXyz(faker: Faker): Xyz {
+ const derivedFaker = faker.derive();
+ return {
+ _id: derivedFaker.string.uuid(),
+ };
+}
+
+createRandomXyz(faker);
+createRandomXyz(faker);
+createRandomXyz(faker);
+```
+
+The sole difference being more or less explicit about deriving a faker instance (writing more or less code).
+:::
+
+## Create identical complex objects
+
+If you want to create two identical objects, e.g. one to mutate and one to compare it to,
+then you can use `faker.clone()` to create a faker instance with the same settings and seed as the original.
+
+```ts
+const clonedFaker = faker.clone();
+const user1 = createRandomUser(faker);
+const user2 = createRandomUser(clonedFaker);
+expect(user1).toEqual(user2); ✅
+
+subscribeToNewsletter(user1);
+// Check that the user hasn't been modified
+expect(user1).toEqual(user2); ✅
+```
+
+::: info Note
+Calling `faker.clone()` is idempotent. So you can call it as often as you want, it doesn't have an impact on the original faker instance.
+:::

src/faker.ts

@@ -430,6 +430,21 @@ export class Faker extends SimpleFaker {
  'This method has been removed. Please use the constructor instead.'
  );
  }
+
+ clone(): Faker {
+ const instance = new Faker({
+ locale: this.rawDefinitions,
+ randomizer: this._randomizer.clone(),
+ });
+ instance.setDefaultRefDate(this._defaultRefDate);
+ return instance;
+ }
+
+ derive(): Faker {
+ const instance = this.clone();
+ instance.seed(this.number.int());
+ return instance;
+ }
 }
 
 export type FakerOptions = ConstructorParameters<typeof Faker>[0];

src/internal/mersenne.ts

@@ -82,6 +82,22 @@ export class MersenneTwister19937 {
  private mt: number[] = Array.from({ length: this.N }); // the array for the state vector
  private mti = this.N + 1; // mti==N+1 means mt[N] is not initialized
 
+ /**
+ * Creates a new instance of MersenneTwister19937.
+ *
+ * @param options The required options to initialize the instance.
+ * @param options.mt The state vector to use. The array will be copied.
+ * @param options.mti The state vector index to use.
+ */
+ constructor(options?: { mt: number[]; mti: number }) {
+ if (options != null && 'mt' in options) {
+ this.mt = [...options.mt];
+ this.mti = options.mti;
+ } else {
+ this.initGenrand(Date.now() ^ (Math.random() * 0x100000000));
+ }
+ }
+
  /**
  * Returns a 32-bits unsigned integer from an operand to which applied a bit
  * operator.
@@ -166,11 +182,11 @@ export class MersenneTwister19937 {
  /**
  * Initialize by an array with array-length.
  *
- * @param initKey is the array for initializing keys
- * @param keyLength is its length
+ * @param initKey Is the array for initializing keys.
  */
- initByArray(initKey: number[], keyLength: number): void {
+ initByArray(initKey: number[]): void {
  this.initGenrand(19650218);
+ const keyLength = initKey.length;
  let i = 1;
  let j = 0;
  let k = this.N > keyLength ? this.N : keyLength;
@@ -240,11 +256,6 @@ export class MersenneTwister19937 {
  // generate N words at one time
  let kk: number;
 
- // if initGenrand() has not been called a default initial seed is used
- if (this.mti === this.N + 1) {
- this.initGenrand(5489);
- }
-
  for (kk = 0; kk < this.N - this.M; kk++) {
  y = this.unsigned32(
  (this.mt[kk] & this.UPPER_MASK) | (this.mt[kk + 1] & this.LOWER_MASK)
@@ -324,6 +335,10 @@ export class MersenneTwister19937 {
  return (a * 67108864.0 + b) * (1.0 / 9007199254740992.0);
  }
  // These real versions are due to Isaku Wada, 2002/01/09
+
+ clone(): MersenneTwister19937 {
+ return new MersenneTwister19937({ mt: this.mt, mti: this.mti });
+ }
 }
 
 /**
@@ -333,10 +348,21 @@ export class MersenneTwister19937 {
  * @internal
  */
 export function generateMersenne32Randomizer(): Randomizer {
+ // This method does not expose any internal parameters to users.
  const twister = new MersenneTwister19937();
+ return _generateMersenne32Randomizer(twister);
+}
 
- twister.initGenrand(Math.ceil(Math.random() * Number.MAX_SAFE_INTEGER));
-
+/**
+ * Generates a MersenneTwister19937 randomizer with 32 bits of precision.
+ *
+ * @internal
+ *
+ * @param twister The twister to use.
+ */
+function _generateMersenne32Randomizer(
+ twister: MersenneTwister19937
+): Randomizer {
  return {
  next(): number {
  return twister.genrandReal2();
@@ -345,8 +371,11 @@ export function generateMersenne32Randomizer(): Randomizer {
  if (typeof seed === 'number') {
  twister.initGenrand(seed);
  } else if (Array.isArray(seed)) {
- twister.initByArray(seed, seed.length);
+ twister.initByArray(seed);
  }
  },
+ clone(): Randomizer {
+ return _generateMersenne32Randomizer(twister.clone());
+ },
  };
 }

src/randomizer.ts

@@ -19,14 +19,20 @@
  * 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;
+ * function wrapperFactory(generator?: RandomGenerator): Randomizer {
+ * const self = {
+ * next: () => (self.generator.unsafeNext() >>> 0) / 0x100000000,
+ * seed: (seed: number | number[]) => {
+ * self.generator = factory(typeof seed === 'number' ? seed : seed[0]);
+ * },
+ * clone: () => wrapperFactory(self.generator.clone()),
+ * } as Randomizer & { generator: RandomGenerator };
+ * return self;
+ * }
+ *
+ * const randomizer = wrapperFactory();
+ * randomizer.seed(seed);
+ * return randomizer;
  * }
  *
  * const randomizer = generatePureRandRandomizer();
@@ -68,4 +74,16 @@ export interface Randomizer {
  * @since 8.2.0
  */
  seed(seed: number | number[]): void;
+
+ /**
+ * Creates an exact copy of this Randomizer. Including the current seed state.
+ *
+ * @example
+ * const clone = randomizer.clone();
+ * randomizer.next() // 0.3404027920160495
+ * clone.next() // 0.3404027920160495 (same as above)
+ * randomizer.next() // 0.929890375900335
+ * clone.next() // 0.929890375900335 (same as above)
+ */
+ clone(): Randomizer;
 }