feat(helpers)!: stricter checking for function signature passed to `multiple` (#2563)

Co-authored-by: ST-DDT <[email protected]>
Co-authored-by: Matt Mayer <[email protected]>

1 files changed, 38 insertions, 0 deletions

diff --git a/docs/guide/upgrading_v9/2563.md b/docs/guide/upgrading_v9/2563.md
new file mode 100644
index 00000000..da770de9
--- /dev/null
+++ b/docs/guide/upgrading_v9/2563.md
@@ -0,0 +1,38 @@
+### Stricter checking for function signature passed to `faker.helpers.multiple` method
+
+The `faker.helpers.multiple` method takes a function reference as its first parameter. Previously you may have written code like this to generate multiple values.
+
+```ts
+faker.helpers.multiple(faker.date.past, { count: 2 });
+```
+
+However this code has a bug - `faker.helpers.multiple` passes the loop index as the second parameter to the method, which in this case would set the `refDate` of the `faker.date.past()` call to 0, making all dates before 1970.
+
+Instead you should generally use a lambda function like
+
+```ts
+faker.helpers.multiple(() => faker.date.past(), { count: 2 });
+```
+
+to get the desired behavior. In v9.0, we use stricter type-checking in Typescript to detect when a function is called which is not compatible with `(v: unknown, index: number)` which can cause compile-time errors in places where previously there were potential runtime errors.
+
+**Bad**
+
+```ts
+faker.helpers.multiple(faker.person.firstName, ...); // ❗
+// In Typescript, this is now a compile time error
+// Argument of type '(sex?: "female" | "male" | undefined) => string'
+// is not assignable to parameter of type '(v: unknown, index: number) => unknown'.
+```
+
+**Good**
+
+```ts
+faker.helpers.multiple(() => faker.person.firstName(), ...); // ✔
+```
+
+The new types also allow for easier use-cases where the index is part of the generated data e.g. as id.
+
+```ts
+faker.helpers.multiple((_, index) => ({ id: index, ...}), ...); // [{id: 0, ...}, ...]
+```