feat!: high precision random number generator (#2357)

2 files changed, 89 insertions, 0 deletions

diff --git a/docs/guide/randomizer.md b/docs/guide/randomizer.md
index e03152a7..16df1209 100644
--- a/docs/guide/randomizer.md
+++ b/docs/guide/randomizer.md
@@ -12,6 +12,23 @@ There are two connected use cases we have considered where this might be needed:
 1. Re-Use of the same `Randomizer` within multiple `Faker` instances.
 2. The use of a random number generator from a third party library.
 
+## Built-In `Randomizer`s
+
+Faker ships with two variations
+
+```ts
+import {
+  generateMersenne32Randomizer, // Default prior to v9
+  generateMersenne53Randomizer, // Default since v9
+} from '@faker-js/faker';
+
+const randomizer = generateMersenne53Randomizer();
+```
+
+The 32bit `Randomizer` is faster, but the 53bit `Randomizer` generates better random values (with significantly fewer duplicates).
+
+But you can also implement your own by implementing the [related interface](/api/randomizer.html).
+
 ## Using `Randomizer`s
 
 A `Randomizer` has to be set during construction of the instance:
diff --git a/docs/guide/upgrading_v9/2357.md b/docs/guide/upgrading_v9/2357.md
new file mode 100644
index 00000000..28a530c3
--- /dev/null
+++ b/docs/guide/upgrading_v9/2357.md
@@ -0,0 +1,72 @@
+# Use High Precision RNG by default
+
+TLDR: Many Faker methods will return a different result in v9 compared to v8 for the same seed.
+
+In v9 we switch from a 32 bit random value to a 53 bit random value.
+We don't change the underlying algorithm much, but we now consume two seed values each step instead of one.
+This affects generated values in two ways:
+
+- In large lists or long numbers the values are spread more evenly.
+  This also reduces the number of duplicates it generates.
+  For `faker.number.int()` this reduces the number of duplicates from `1 / 10_000` to less than `1 / 8_000_000`.
+- If you start with the same initial seed to generate a value, you might see some changes in the results you get.
+  This is because we're now working with a higher precision, which affects how numbers are rounded off.
+  As a result, the methods we use might produce slightly different outcomes.
+  And since we are now using two seed values each time subsequent results appear to skip a value each time.
+
+```ts
+import {
+  SimpleFaker,
+  generateMersenne32Randomizer,
+  generateMersenne53Randomizer,
+} from '@faker-js/faker';
+
+// < v9 default
+const f32 = new SimpleFaker({ randomizer: generateMersenne32Randomizer() });
+f32.seed(123);
+const r32 = f32.helpers.multiple(() => f32.number.int(10), { count: 10 });
+// > v9 default
+const f53 = new SimpleFaker({ randomizer: generateMersenne53Randomizer() });
+f53.seed(123);
+const r53 = f53.helpers.multiple(() => f53.number.int(10), { count: 5 });
+
+diff(r32, r53);
+//[
+//  7,
+//  7, // [!code --]
+//  3,
+//  4, // [!code --]
+//  2,
+//  7, // [!code --]
+//  6,
+//  7, // [!code --]
+//  7,
+//  5, // [!code --]
+//]
+```
+
+## Adoption
+
+If you don't have any seeded tests and just want some random values, then you don't have to change anything.
+
+If you have seeded tests, you have to update most test snapshots or similar comparisons to new values.
+
+If you are using vitest, you can do that using `pnpm vitest run -u`.
+
+## Keeping the old behavior
+
+You can keep the old behavior, if you create your own `Faker` instance
+and pass a `Randomizer` instance from the `generateMersenne32Randomizer()` function to it.
+
+```ts{8}
+import {
+  Faker,
+  generateMersenne32Randomizer, // < v9 default
+  generateMersenne53Randomizer, // > v9 default
+} from '@faker-js/faker';
+
+const faker = new Faker({
+  randomizer: generateMersenne32Randomizer(),
+  ...
+});
+```