Changed (Async)PorterRecords semantics to always run generators to first suspension point.

This was always a side-effect of the (previous, coroutine) async
behaviour, but since fibers, is no longer a necessary side-effect. Yet,
some libraries may depend on this behaviour, such as those expecting to
resolve a deferred before the first suspension point. We now adopt these
semantics intentionally and replicate them to the sync flow.

Author: Bilge

composer.json

@@ -21,7 +21,7 @@
   },
   "require-dev": {
     "infection/infection": ">=0.26,<0.27",
-    "mockery/mockery": "^1.4.2",
+    "mockery/mockery": "^1.5",
     "phpunit/phpunit": "^9.5.23"
   },
   "suggest" : {

src/Collection/AsyncPorterRecords.php

@@ -7,13 +7,14 @@
 
 class AsyncPorterRecords extends AsyncRecordCollection
 {
-    private AsyncImportSpecification $specification;
-
-    public function __construct(AsyncRecordCollection $records, AsyncImportSpecification $specification)
-    {
+    public function __construct(
+        AsyncRecordCollection $records,
+        private readonly AsyncImportSpecification $specification
+    ) {
         parent::__construct($records, $records);
 
-        $this->specification = $specification;
+        // Force generators to run to first suspension point.
+        $records->valid();
     }
 
     public function getSpecification(): AsyncImportSpecification

src/Collection/PorterRecords.php

@@ -7,13 +7,12 @@
 
 class PorterRecords extends RecordCollection
 {
-    private ImportSpecification $specification;
-
-    public function __construct(RecordCollection $records, ImportSpecification $specification)
+    public function __construct(RecordCollection $records, private readonly ImportSpecification $specification)
     {
         parent::__construct($records, $records);
 
-        $this->specification = $specification;
+        // Force generators to run to first suspension point.
+        $records->valid();
     }
 
     public function getSpecification(): ImportSpecification

test/Integration/Collection/AsyncRecordCollectionTest.php

@@ -19,7 +19,7 @@ final class AsyncRecordCollectionTest extends TestCase
     public function testGetPreviousCollection(): void
     {
         $records = new AsyncPorterRecords(
-            $previous = \Mockery::mock(AsyncRecordCollection::class),
+            $previous = \Mockery::spy(AsyncRecordCollection::class),
             \Mockery::mock(AsyncImportSpecification::class)
         );
 
@@ -33,7 +33,7 @@ public function testGetPreviousCollection(): void
     public function testFindFirstCollection(): void
     {
         $collection3 = new AsyncFilteredRecords(
-            $iterator = \Mockery::mock(\Iterator::class),
+            $iterator = \Mockery::spy(\Iterator::class),
             $collection2 = new AsyncPorterRecords(
                 $collection1 =
                     new AsyncProviderRecords($iterator, \Mockery::mock(AsyncResource::class)),

test/Integration/PorterAsyncTest.php

@@ -63,6 +63,23 @@ public function testImportSingle(): void
         $this->porter->importAsync($this->singleSpecification);
     }
 
+    /**
+     * Tests that when importing records implemented using deferred execution with generators, the generator runs up
+     * to the first suspension point instead of being paused at the start.
+     */
+    public function testImportGenerator(): void
+    {
+        $this->resource->expects('fetchAsync')->andReturnUsing(function () use (&$init): \Generator {
+            $init = true;
+
+            yield [];
+        });
+
+        $this->porter->importAsync($this->specification);
+
+        self::assertTrue($init);
+    }
+
     /**
      * Tests that the full async import path, via connector, resource and provider, fetches one record correctly.
      */
@@ -186,7 +203,7 @@ public function testPorterAwareAsyncTransformer(): void
                         ->with($this->porter)
                         ->once()
                     ->shouldReceive('transformAsync')
-                        ->andReturn(\Mockery::mock(AsyncRecordCollection::class))
+                        ->andReturn(\Mockery::spy(AsyncRecordCollection::class))
                     ->getMock()
             )
         );

test/Integration/PorterSyncTest.php

@@ -73,8 +73,8 @@ public function testImportAndFilterCountableRecords(): void
     {
         $records = $this->porter->import(
             (new StaticDataImportSpecification(
-                new \ArrayIterator(range(1, 10))
-            ))->addTransformer(new FilterTransformer((__METHOD__)(...)))
+                new \ArrayIterator(array_map(fn ($i) => [$i], range(1, 10)))
+            ))->addTransformer(new FilterTransformer(fn () => true))
         );
 
         // Innermost collection.
@@ -102,6 +102,23 @@ public function testRewind(): void
         self::assertSame($i1, $records->current());
     }
 
+    /**
+     * Tests that when importing records implemented using deferred execution with generators, the generator runs up
+     * to the first suspension point instead of being paused at the start.
+     */
+    public function testImportGenerator(): void
+    {
+        $this->resource->expects('fetch')->andReturnUsing(function () use (&$init): \Generator {
+            $init = true;
+
+            yield [];
+        });
+
+        $this->porter->import($this->specification);
+
+        self::assertTrue($init);
+    }
+
     /**
      * Tests that when a Transformer is PorterAware it receives the Porter instance that invoked it.
      */
@@ -114,7 +131,7 @@ public function testPorterAwareTransformer(): void
                         ->with($this->porter)
                         ->once()
                     ->shouldReceive('transform')
-                        ->andReturn(\Mockery::mock(RecordCollection::class))
+                        ->andReturn(\Mockery::spy(RecordCollection::class))
                     ->getMock()
             )
         );

test/Unit/Collection/AsyncPorterRecordsTest.php

@@ -19,7 +19,7 @@ final class AsyncPorterRecordsTest extends TestCase
     public function testGetSpecification(): void
     {
         $records = new AsyncPorterRecords(
-            \Mockery::mock(AsyncRecordCollection::class),
+            \Mockery::spy(AsyncRecordCollection::class),
             $specification = \Mockery::mock(AsyncImportSpecification::class)
         );
 

test/Unit/Collection/PorterRecordsTest.php

@@ -19,7 +19,7 @@ final class PorterRecordsTest extends TestCase
     public function testGetSpecification(): void
     {
         $records = new PorterRecords(
-            \Mockery::mock(RecordCollection::class),
+            \Mockery::spy(RecordCollection::class),
             $specification = \Mockery::mock(ImportSpecification::class)
         );
 

test/Unit/Collection/RecordCollectionTest.php

@@ -20,11 +20,6 @@ final class RecordCollectionTest extends TestCase
      */
     public function testFindFirstCollection(): void
     {
-        /**
-         * @var RecordCollection $collection1
-         * @var RecordCollection $collection2
-         * @var RecordCollection $collection3
-         */
         $collection3 = \Mockery::mock(
             RecordCollection::class,
             [