docs: improve documentation

docs/guide/upgrading_v9/2563.md

@@ -1,21 +1,26 @@
-### Expose signature parameters in `method` parameter of `faker.helpers.multiple`
+### Stricter checking for function signature passed to `faker.helpers.multiple` method
 
-We now expose the parameters from the `method` parameter to our users.
-That allows for usecases where the index is part of the generated data e.g. as id.
+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((_, index) => ({ id: index, ...}), ...); // [{id: 0, ...}, ...]
+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 });
 ```
 
-While the actual implementation of the method hasn't changed, it's signature has.
-Previously it was possible to incorrectly pass any function reference to `faker.helpers.multiple`,
-even those that are incompatible with the actual parameters passed to the generator function.
-This change causes compile time errors only in cases that would otherwise be potential runtime errors.
+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'.
 ```
@@ -25,3 +30,9 @@ faker.helpers.multiple(faker.person.firstName, ...); // ❗
 ```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, ...}, ...]
+```

src/modules/helpers/index.ts

@@ -1129,12 +1129,13 @@ export class SimpleHelpersModule extends SimpleModuleBase {
    * @template TResult The type of elements.
    *
    * @param method The method used to generate the values.
+   * The method will be called with `(_, index)`, to allow using the index in the generated value e.g. as id.
    * @param options The optional options object.
    * @param options.count The number or range of elements to generate. Defaults to `3`.
    *
    * @example
-   * faker.helpers.multiple(faker.person.firstName) // [ 'Aniya', 'Norval', 'Dallin' ]
-   * faker.helpers.multiple(faker.person.firstName, { count: 3 }) // [ 'Santos', 'Lavinia', 'Lavinia' ]
+   * faker.helpers.multiple(() => faker.person.firstName()) // [ 'Aniya', 'Norval', 'Dallin' ]
+   * faker.helpers.multiple(() => faker.person.firstName(), { count: 3 }) // [ 'Santos', 'Lavinia', 'Lavinia' ]
    * faker.helpers.multiple((_, i) => `Person ${i + 1}` ) // [ 'Person 1', 'Person 2', 'Person 3' ]
    *
    * @since 8.0.0