From c4a472d415c32d98e487414ab92a2934b5f2799e Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Fri, 26 Dec 2025 10:32:23 +0400
Subject: [PATCH] fix(BulkLoader): Handle empty entity collection without
 throwing exception

---
 src/Relation/BulkLoader.php                | 13 +++++++++++--
 src/Relation/BulkLoaderInterface.php       |  2 ++
 tests/ORM/Unit/Relation/BulkLoaderTest.php | 11 +++++------
 3 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/src/Relation/BulkLoader.php b/src/Relation/BulkLoader.php
index 2983d5b7..abf60eec 100644
--- a/src/Relation/BulkLoader.php
+++ b/src/Relation/BulkLoader.php
@@ -29,7 +29,16 @@ public function __construct(
 
     public function collect(object ...$entities): RelationLoaderInterface
     {
-        $entities === [] and throw new \InvalidArgumentException('At least one entity must be provided.');
+        if ($entities === []) {
+            return new class implements RelationLoaderInterface {
+                public function load(string $relation, array $options = []): static
+                {
+                    return $this;
+                }
+
+                public function run(): void {}
+            };
+        }
         $entities = \array_values($entities);
 
         // Validate entity roles
@@ -112,7 +121,7 @@ public function run(): void
      * @param non-empty-array<non-empty-string> $keys
      * @param non-empty-array<non-empty-string> $data
      */
-    public function indexEntity(Node $node, array $keys, array $data, object $entity): void
+    private function indexEntity(Node $node, array $keys, array $data, object $entity): void
     {
         $pool = &$this->index;
         foreach ($keys as $k) {
diff --git a/src/Relation/BulkLoaderInterface.php b/src/Relation/BulkLoaderInterface.php
index 047b83be..2a185cc0 100644
--- a/src/Relation/BulkLoaderInterface.php
+++ b/src/Relation/BulkLoaderInterface.php
@@ -12,6 +12,8 @@ interface BulkLoaderInterface
     /**
      * Collect entities for bulk relation loading.
      *
+     * If no entities are provided, a no-op loader is returned.
+     *
      * @param object ...$entities Entities to collect
      * @psalm-immutable
      */
diff --git a/tests/ORM/Unit/Relation/BulkLoaderTest.php b/tests/ORM/Unit/Relation/BulkLoaderTest.php
index a209149c..d7a427f3 100644
--- a/tests/ORM/Unit/Relation/BulkLoaderTest.php
+++ b/tests/ORM/Unit/Relation/BulkLoaderTest.php
@@ -8,6 +8,7 @@
 use Cycle\ORM\Mapper\Mapper;
 use Cycle\ORM\ORM;
 use Cycle\ORM\Relation\BulkLoader;
+use Cycle\ORM\Relation\RelationLoaderInterface;
 use Cycle\ORM\Schema;
 use Cycle\ORM\Tests\Fixtures\User;
 use Cycle\ORM\Tests\Fixtures\Profile;
@@ -130,14 +131,12 @@ public function testChainingMultipleCollectCalls(): void
      */
     public function testCollectWithEmptyArrayUnpacking(): void
     {
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage('At least one entity must be provided.');
-
         $orm = $this->createORM();
-        $entities = [];
+        $loader = (new BulkLoader($orm))->collect();
 
-        $loader = new BulkLoader($orm);
-        $loader->collect(...$entities);
+        self::assertInstanceOf(RelationLoaderInterface::class, $loader);
+        $loader->load('profile');
+        $loader->run();
     }
 
     /**