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

docs/guide/upgrading_v9/2563.md

@@ -0,0 +1,27 @@
+### Expose signature parameters in `method` parameter of `faker.helpers.multiple`
+
+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.
+
+```ts
+faker.helpers.multiple((_, index) => ({ id: index, ...}), ...); // [{id: 0, ...}, ...]
+```
+
+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.
+
+**Bad**
+
+```ts
+faker.helpers.multiple(faker.person.firstName, ...); // ❗
+// 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(), ...); // ✔
+```

src/modules/helpers/index.ts

@@ -1135,11 +1135,12 @@ export class SimpleHelpersModule extends SimpleModuleBase {
    * @example
    * 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
    */
   multiple<const TResult>(
-    method: () => TResult,
+    method: (v: unknown, index: number) => TResult,
     options: {
       /**
        * The number or range of elements to generate.

test/modules/__snapshots__/helpers.spec.ts.snap

@@ -98,6 +98,14 @@ exports[`helpers > 42 > multiple > with method and count range 1`] = `
 ]
 `;
 
+exports[`helpers > 42 > multiple > with method using index 1`] = `
+[
+  0,
+  3,
+  6,
+]
+`;
+
 exports[`helpers > 42 > multiple > with only method 1`] = `
 [
   3373557479352566,
@@ -330,6 +338,14 @@ exports[`helpers > 1211 > multiple > with method and count range 1`] = `
 ]
 `;
 
+exports[`helpers > 1211 > multiple > with method using index 1`] = `
+[
+  0,
+  3,
+  6,
+]
+`;
+
 exports[`helpers > 1211 > multiple > with only method 1`] = `
 [
   8363366038243348,
@@ -544,6 +560,14 @@ exports[`helpers > 1337 > multiple > with method and count range 1`] = `
 ]
 `;
 
+exports[`helpers > 1337 > multiple > with method using index 1`] = `
+[
+  0,
+  3,
+  6,
+]
+`;
+
 exports[`helpers > 1337 > multiple > with only method 1`] = `
 [
   2360108457524098,

test/modules/helpers.spec.ts

@@ -173,11 +173,14 @@ describe('helpers', () => {
     });
 
     t.describe('multiple', (t) => {
-      t.it('with only method', faker.number.int)
-        .it('with method and count', faker.number.int, { count: 5 })
-        .it('with method and count range', faker.number.int, {
+      t.it('with only method', () => faker.number.int())
+        .it('with method and count', () => faker.number.int(), {
+          count: 5,
+        })
+        .it('with method and count range', () => faker.number.int(), {
           count: { min: 1, max: 10 },
-        });
+        })
+        .it('with method using index', (_, i) => i * 3);
     });
   });
 
@@ -1144,30 +1147,46 @@ describe('helpers', () => {
 
       describe('multiple()', () => {
         it('should generate values from the function with a default length of 3', () => {
-          const result = faker.helpers.multiple(faker.person.firstName);
+          const result = faker.helpers.multiple(() => faker.person.firstName());
           expect(result).toBeTypeOf('object');
           expect(Array.isArray(result)).toBe(true);
           expect(result.length).toBe(3);
         });
 
         it('should generate the given amount of values from the function', () => {
-          const result = faker.helpers.multiple(faker.person.firstName, {
-            count: 5,
-          });
+          const result = faker.helpers.multiple(
+            () => faker.person.firstName(),
+            {
+              count: 5,
+            }
+          );
           expect(result).toBeTypeOf('object');
           expect(Array.isArray(result)).toBe(true);
           expect(result.length).toBe(5);
         });
 
         it('should generate a ranged number of values from the function', () => {
-          const result = faker.helpers.multiple(faker.person.firstName, {
-            count: { min: 1, max: 10 },
-          });
+          const result = faker.helpers.multiple(
+            () => faker.person.firstName(),
+            {
+              count: { min: 1, max: 10 },
+            }
+          );
           expect(result).toBeTypeOf('object');
           expect(Array.isArray(result)).toBe(true);
           expect(result.length).toBeGreaterThanOrEqual(1);
           expect(result.length).toBeLessThanOrEqual(10);
         });
+
+        it('should generate values using index of created value', () => {
+          const result = faker.helpers.multiple((_, i) => i * 2, {
+            count: 3,
+          });
+          expect(result).toBeTypeOf('object');
+          expect(Array.isArray(result)).toBe(true);
+          expect(result.length).toBe(3);
+          expect(result).toStrictEqual([0, 2, 4]);
+        });
       });
     }
   );