feat: introduce mapEach() method

Author: nikophil

src/FactoryCollection.php

@@ -187,6 +187,29 @@ public function distribute(string $field, array $values): self
         );
     }
 
+    /**
+     * @param list<mixed>|list<list<mixed>> $values
+     *
+     * @return self<T, TFactory>
+     */
+    public function mapEach(callable $callback, array $values): self // @phpstan-ignore missingType.callable (cannot properly type the callable)
+    {
+        $factories = $this->all();
+
+        if (count($factories) !== count($values)) {
+            throw new \InvalidArgumentException('Number of values must match number of factories.');
+        }
+
+        return new self(
+            $this->factory,
+            static fn() => \array_map(
+                static fn(Factory $f, mixed $value) => is_array($value) ? $callback($f, ...$value) : $callback($f, $value),
+                $factories,
+                $values
+            )
+        );
+    }
+
     public function getIterator(): \Traversable
     {
         return new \ArrayIterator($this->all());

tests/Unit/ObjectFactoryTest.php

@@ -17,6 +17,8 @@
 use Zenstruck\Foundry\Factory;
 use Zenstruck\Foundry\Object\Instantiator;
 use Zenstruck\Foundry\Test\Factories;
+use Zenstruck\Foundry\Tests\Fixture\Factories\Entity\Category\CategoryFactory;
+use Zenstruck\Foundry\Tests\Fixture\Factories\Entity\Contact\ContactFactory;
 use Zenstruck\Foundry\Tests\Fixture\Factories\Object1Factory;
 use Zenstruck\Foundry\Tests\Fixture\Factories\Object2Factory;
 use Zenstruck\Foundry\Tests\Fixture\Factories\SimpleObjectFactory;
@@ -472,6 +474,65 @@ public function providing_invalid_values_number_to_distribute_throws(): void
         SimpleObjectFactory::new()->many(2)->distribute('prop1', ['foo']);
     }
 
+    /**
+     * @test
+     */
+    #[Test]
+    public function map_each_with_single_value(): void
+    {
+        $objects = SimpleObjectFactory::new()
+            ->many(2)
+            ->mapEach(
+                static fn(SimpleObjectFactory $f, $prop1) => $f->withProps($prop1),
+                ['foo', 'bar']
+            )
+            ->create();
+
+        self::assertCount(2, $objects);
+
+        self::assertSame('foo', $objects[0]->prop1);
+        self::assertSame('bar', $objects[1]->prop1);
+    }
+
+    /**
+     * @test
+     */
+    #[Test]
+    public function map_each(): void
+    {
+        $objects = SimpleObjectFactory::new()
+            ->many(2)
+            ->mapEach(
+                static fn(SimpleObjectFactory $f, $prop1, $prop2) => $f->withProps($prop1, $prop2),
+                [['foo', 'bar'], ['prop1', 'prop2']]
+            )
+            ->create();
+
+        self::assertCount(2, $objects);
+
+        self::assertSame('foo', $objects[0]->prop1);
+        self::assertSame('bar', $objects[0]->prop2);
+
+        self::assertSame('prop1', $objects[1]->prop1);
+        self::assertSame('prop2', $objects[1]->prop2);
+    }
+
+    /**
+     * @test
+     */
+    #[Test]
+    public function providing_invalid_values_number_to_map_each_throws(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        SimpleObjectFactory::new()
+            ->many(2)
+            ->mapEach(
+                static fn(SimpleObjectFactory $f, $prop1) => $f->withProps($prop1),
+                ['foo']
+            );
+    }
+
     /**
      * @test
      */