Fixed one escaped mutant in ImportConnector::createExceptionHandler.

Fixed some grammar errors in Readme.
Updated Porter graphic with transparent background.

Author: Bilge

.gitignore

@@ -3,3 +3,4 @@
 !/.github/
 /composer.lock
 /*.log
+.phpunit.result.cache

README.md

@@ -69,11 +69,11 @@ About this manual
 
 Those wishing to consume a Porter provider create one instance of `Porter` for their application and an instance of `ImportSpecification` for each data import they wish to perform. Those publishing providers must implement `Provider` and `ProviderResource`.
 
-The first half of this manual covers Porter's main API for consuming data services. The second half covers architecture, interface and implementation details for publishing data services. There's an intermission in-between so you'll know where the separation is!
+The first half of this manual covers Porter's main API for consuming data services. The second half covers architecture, interface and implementation details for publishing data services. There's an intermission in-between, so you'll know where the separation is!
 
 Text marked as `inline code` denotes literal code, as it would appear in a PHP file. For example, `Porter` refers specifically to the class of the same name within this library, whereas *Porter* refers to this project as a whole.
 
-Porter has a dual API for the synchronous and asynchronous workflow dichotomy. Almost every Porter feature has an asynchronous equivalent. You will need to choose which you prefer to use. Most examples in this manual are for the synchronous API, for brevity and simplicity, but the asynchronous version will invariably be similar. Working synchronously may be easier when getting started but you are encouraged to use the async API if you are able, to reap its benefits.
+Porter has a dual API for the synchronous and asynchronous workflow dichotomy. Almost every Porter feature has an asynchronous equivalent. You will need to choose which you prefer to use. Most examples in this manual are for the synchronous API, for brevity and simplicity, but the asynchronous version will invariably be similar. Working synchronously may be easier when getting started, but you are encouraged to use the async API if you are able, to reap its benefits.
 
 Usage
 -----
@@ -134,12 +134,12 @@ The following data flow diagram gives a high level overview of Porter's main int
 
 </div>
 
-Our application calls `Porter::import()` with an `ImportSpecification` and receives `PorterRecords` back. Everything else happens internally so we don't need to worry about it unless writing custom providers, resources or connectors.
+Our application calls `Porter::import()` with an `ImportSpecification` and receives `PorterRecords` back. Everything else happens internally, so we don't need to worry about it unless writing custom providers, resources or connectors.
 
 Import specifications
 ---------------------
 
-Import specifications specify *what* to import, *how* it should be [transformed](#transformers) and whether to use [caching](#caching). In synchronous code, create an new instance of `ImportSpecification` and pass a `ProviderResource` that specifies the resource we want to import. In Asynchronous code, create `AsyncImportSpecification` instead.
+Import specifications specify *what* to import, *how* it should be [transformed](#transformers) and whether to use [caching](#caching). In synchronous code, create a new instance of `ImportSpecification` and pass a `ProviderResource` that specifies the resource we want to import. In Asynchronous code, create `AsyncImportSpecification` instead.
 
 Options may be configured using the methods below.
 
@@ -232,14 +232,14 @@ public function transformAsync(AsyncRecordCollection $records, mixed $context):
 
 When `transform()` or `transformAsync()` is called the transformer may iterate each record and change it in any way, including removing or inserting additional records. The record collection must be returned by the method, whether or not changes were made.
 
-Transformers should also implement the `__clone` magic method if the they store any object state, in order to facilitate deep copy when Porter clones the owning `ImportSpecification` during import.
+Transformers should also implement the `__clone` magic method if they store any object state, in order to facilitate deep copy when Porter clones the owning `ImportSpecification` during import.
 
 Filtering
 ---------
 
 Filtering provides a way to remove some records. For each record, if the specified predicate function returns `false` (or a falsy value), the record will be removed, otherwise the record will be kept. The predicate receives the current record as an array as its first parameter and context as its second parameter.
 
-In general we would like to avoid filtering because it is inefficient to import data and then immediately remove some of it, but some immature APIs do not provide a way to reduce the data set on the server, so filtering on the client is the only alternative. Filtering also invalidates the record count reported by some resources, meaning we no longer know how many records are in the collection before iteration.
+In general, we would like to avoid filtering because it is inefficient to import data and then immediately remove some of it, but some immature APIs do not provide a way to reduce the data set on the server, so filtering on the client is the only alternative. Filtering also invalidates the record count reported by some resources, meaning we no longer know how many records are in the collection before iteration.
 
 ### Example
 
@@ -330,7 +330,7 @@ Providers must implement the `Provider` interface and supply a valid connector w
 
 #### Implementation example
 
-In the following example we create a provider that only accepts `HttpConnector` instances. We also create a default connector in case one is not supplied. Note it is not always possible to create a default connector and it is perfectly valid to insist the caller supplies a connector.
+In the following example we create a provider that only accepts `HttpConnector` instances. We also create a default connector in case one is not supplied. Note it is not always possible to create a default connector, and it is perfectly valid to insist the caller supplies a connector.
 
 ```php
 final class MyProvider implements Provider
@@ -511,7 +511,7 @@ Everyone is welcome to contribute anything, from [ideas and issues][Issues] to [
 License
 -------
 
-Porter is published under the open source GNU Lesser General Public License v3.0. However, the original Porter character and artwork is copyright &copy; 2019 [Bilge](https://github.com/Bilge) and may not be reproduced or modified without express written permission.
+Porter is published under the open source GNU Lesser General Public License v3.0. However, the original Porter character and artwork is copyright &copy; 2022 [Bilge](https://github.com/Bilge) and may not be reproduced or modified without express written permission.
 
 ###### Quick links
 

docs/images/porter 222x.png

@@ -10,9 +10,7 @@
 use ScriptFUSION\Porter\Connector\Connector;
 use ScriptFUSION\Porter\Connector\DataSource;
 use ScriptFUSION\Porter\Connector\ImportConnector;
-use ScriptFUSION\Porter\Connector\Recoverable\RecoverableExceptionHandler;
 use ScriptFUSION\Porter\Connector\Recoverable\StatelessRecoverableExceptionHandler;
-use ScriptFUSION\Retry\FailingTooHardException;
 use ScriptFUSIONTest\FixtureFactory;
 use ScriptFUSIONTest\Stubs\TestRecoverableException;
 use ScriptFUSIONTest\Stubs\TestRecoverableExceptionHandler;
@@ -64,7 +62,7 @@ public function provideHandlerAndConnector(): \Generator
             $connector = FixtureFactory::buildImportConnector(
                 \Mockery::mock(Connector::class)
                     ->shouldReceive('fetch')
-                    ->andReturnUsing($this->createExceptionThrowingClosure())
+                    ->andReturnUsing(self::createExceptionThrowingClosure())
                     ->getMock(),
                 $handler
             ),
@@ -97,9 +95,7 @@ public function testStatelessExceptionHandlerNotCloned(): void
         self::assertSame(
             $handler,
             \Closure::bind(
-                function (): RecoverableExceptionHandler {
-                    return $this->userExceptionHandler;
-                },
+                fn () => $this->userExceptionHandler,
                 $connector,
                 $connector
             )()
@@ -118,14 +114,13 @@ public function testExceptionHandlerCannotCancelRetries(): void
                 ->shouldReceive('fetch')
                 ->andThrow(new TestRecoverableException)
                 ->getMock(),
-            new StatelessRecoverableExceptionHandler(static function () {
-                return false;
-            })
+            new StatelessRecoverableExceptionHandler(fn () => false)
         )->fetch($this->source);
     }
 
     /**
-     * Tests that when a user recoverable exception handler returns a promise, the promise is resolved.
+     * Tests that when a user recoverable exception handler throws an exception, the handler's exception can be
+     * captured.
      */
     public function testAsyncUserRecoverableExceptionHandler(): void
     {
@@ -134,20 +129,21 @@ public function testAsyncUserRecoverableExceptionHandler(): void
                 ->shouldReceive('fetchAsync')
                 ->andThrow(new TestRecoverableException)
                 ->getMock(),
-            self::createAsyncRecoverableExceptionHandler()
+            new StatelessRecoverableExceptionHandler(
+                self::createExceptionThrowingClosure($exception = new TestRecoverableException)
+            )
         );
 
         try {
             $connector->fetchAsync($this->asyncSource);
-        } catch (FailingTooHardException $exception) {
-            // This is fine.
+        } catch (\Exception $e) {
+            self::assertSame($exception, $e);
         }
-
-        self::assertTrue(isset($exception));
     }
 
     /**
-     * Tests that when a resource recoverable exception handler returns a promise, the promise is resolved.
+     * Tests that when a resource recoverable exception handler throws an exception, the handler's exception can be
+     * captured.
      */
     public function testAsyncResourceRecoverableExceptionHandler(): void
     {
@@ -158,20 +154,20 @@ public function testAsyncResourceRecoverableExceptionHandler(): void
                 ->getMock()
         );
 
-        $connector->setRecoverableExceptionHandler(self::createAsyncRecoverableExceptionHandler());
+        $connector->setRecoverableExceptionHandler(new StatelessRecoverableExceptionHandler(
+            self::createExceptionThrowingClosure($exception = new TestRecoverableException)
+        ));
 
         try {
             $connector->fetchAsync($this->asyncSource);
-        } catch (FailingTooHardException $exception) {
-            // This is fine.
+        } catch (\Exception $e) {
+            self::assertSame($exception, $e);
         }
-
-        self::assertTrue(isset($exception));
     }
 
     /**
-     * Tests that when user and resource recoverable exception handlers both return promises, both promises are
-     * resolved.
+     * Tests that when user and resource recoverable exception handlers are both set, both handlers are invoked,
+     * resource handler first and user handler second.
      */
     public function testAsyncUserAndResourceRecoverableExceptionHandlers(): void
     {
@@ -180,36 +176,37 @@ public function testAsyncUserAndResourceRecoverableExceptionHandlers(): void
                 ->shouldReceive('fetchAsync')
                 ->andThrow(new TestRecoverableException)
                 ->getMock(),
-            self::createAsyncRecoverableExceptionHandler()
+            new StatelessRecoverableExceptionHandler(self::createExceptionThrowingClosure($e2 = new \Exception))
         );
 
-        $connector->setRecoverableExceptionHandler(self::createAsyncRecoverableExceptionHandler());
+        $connector->setRecoverableExceptionHandler(new StatelessRecoverableExceptionHandler(
+            self::createExceptionThrowingClosure($e1 = new \Exception())
+        ));
 
         try {
             $connector->fetchAsync($this->asyncSource);
-        } catch (FailingTooHardException $exception) {
-            // This is fine.
+        } catch (\Exception $exception) {
+            self::assertSame($e1, $exception);
         }
 
-        self::assertTrue(isset($exception));
+        try {
+            $connector->fetchAsync($this->asyncSource);
+        } catch (\Exception $exception) {
+            self::assertSame($e2, $exception);
+        }
     }
 
     /**
      * Creates a closure that only throws an exception on the first invocation.
      */
-    private static function createExceptionThrowingClosure(): \Closure
+    private static function createExceptionThrowingClosure(\Exception $exception = null): \Closure
     {
-        return static function (): void {
+        return static function () use ($exception): void {
             static $invocationCount;
 
             if (!$invocationCount++) {
-                throw new TestRecoverableException;
+                throw $exception ?? new TestRecoverableException;
             }
         };
     }
-
-    private static function createAsyncRecoverableExceptionHandler(): RecoverableExceptionHandler
-    {
-        return new StatelessRecoverableExceptionHandler(fn () => null);
-    }
 }

test/Integration/Connector/ImportConnectorTest.php

@@ -3,7 +3,6 @@
 
 namespace ScriptFUSIONTest;
 
-use Amp\Future;
 use Mockery\MockInterface;
 use ScriptFUSION\Async\Throttle\Throttle;
 use ScriptFUSION\Porter\Connector\AsyncConnector;
@@ -17,6 +16,7 @@
 use ScriptFUSION\Porter\Provider\Resource\ProviderResource;
 use ScriptFUSION\Porter\Provider\Resource\SingleRecordResource;
 use ScriptFUSION\StaticClass;
+use function Amp\async;
 use function Amp\delay;
 
 final class MockFactory
@@ -92,7 +92,7 @@ public static function mockThrottle(): Throttle|MockInterface
     {
         return \Mockery::mock(Throttle::class)
             ->allows('watch')
-                ->andReturnUsing(fn (\Closure $closure, mixed ...$args) => $closure($args))
+                ->andReturnUsing(fn (\Closure $closure, mixed ...$args) => async($closure, ...$args))
                 ->byDefault()
             ->getMock()
         ;