Add timeoutWithDefault function (#245)

lib/functions.php

@@ -96,12 +96,14 @@ namespace Amp\Promise
 {
 
     use Amp\Deferred;
+    use Amp\Failure;
     use Amp\Loop;
     use Amp\MultiReasonException;
     use Amp\Promise;
     use Amp\Success;
     use Amp\TimeoutException;
     use React\Promise\PromiseInterface as ReactPromise;
+    use function Amp\call;
     use function Amp\Internal\createTypeError;
 
     /**
@@ -223,6 +225,34 @@ namespace Amp\Promise
         return $deferred->promise();
     }
 
+    /**
+     * Creates an artificial timeout for any `Promise`.
+     *
+     * If the promise is resolved before the timeout expires, the result is returned
+     *
+     * If the timeout expires before the promise is resolved, a default value is returned
+     *
+     * @param \Amp\Promise|\React\Promise\PromiseInterface $promise Promise to which the timeout is applied.
+     * @param int                                          $timeout Timeout in milliseconds.
+     * @param mixed                                        $default
+     *
+     * @return \Amp\Promise
+     *
+     * @throws \TypeError If $promise is not an instance of \Amp\Promise or \React\Promise\PromiseInterface.
+     */
+    function timeoutWithDefault($promise, int $timeout, $default = null): Promise
+    {
+        $promise = timeout($promise, $timeout);
+
+        return call(function () use ($promise, $default) {
+            try {
+                return yield $promise;
+            } catch (TimeoutException $exception) {
+                return $default;
+            }
+        });
+    }
+
     /**
      * Adapts any object with a done(callable $onFulfilled, callable $onRejected) or then(callable $onFulfilled,
      * callable $onRejected) method to a promise usable by components depending on placeholders implementing

test/TimeoutWithDefaultTest.php

@@ -0,0 +1,132 @@
+<?php
+
+namespace Amp\Test;
+
+use Amp\Delayed;
+use Amp\Failure;
+use Amp\Loop;
+use Amp\Promise;
+use Amp\Success;
+use function React\Promise\resolve;
+
+class TimeoutWithDefaultTest extends \PHPUnit\Framework\TestCase
+{
+    public function testSuccessfulPromise()
+    {
+        Loop::run(function () {
+            $value = 1;
+
+            $promise = new Success($value);
+
+            $promise = Promise\timeoutWithDefault($promise, 100, 2);
+            $this->assertInstanceOf(Promise::class, $promise);
+
+            $callback = function ($exception, $value) use (&$result) {
+                $result = $value;
+            };
+
+            $promise->onResolve($callback);
+
+            $this->assertSame($value, $result);
+        });
+    }
+
+    public function testFailedPromise()
+    {
+        Loop::run(function () {
+            $exception = new \Exception;
+
+            $promise = new Failure($exception);
+
+            $promise = Promise\timeoutWithDefault($promise, 100, 2);
+            $this->assertInstanceOf(Promise::class, $promise);
+
+            $callback = function ($exception, $value) use (&$actual) {
+                if ($exception) {
+                    $actual = $exception;
+                } else {
+                    $actual = $value;
+                }
+            };
+
+            $promise->onResolve($callback);
+
+            $this->assertSame($exception, $actual);
+        });
+    }
+
+    /**
+     * @depends testSuccessfulPromise
+     */
+    public function testFastPending()
+    {
+        $value = 1;
+
+        Loop::run(function () use (&$result, $value) {
+            $promise = new Delayed(50, $value);
+
+            $promise = Promise\timeoutWithDefault($promise, 100);
+            $this->assertInstanceOf(Promise::class, $promise);
+
+            $callback = function ($exception, $value) use (&$result) {
+                $result = $value;
+            };
+
+            $promise->onResolve($callback);
+        });
+
+        $this->assertSame($value, $result);
+    }
+
+    /**
+     * @depends testSuccessfulPromise
+     */
+    public function testSlowPending()
+    {
+        $expected = 2;
+
+        Loop::run(function () use (&$actual, $expected) {
+            $promise = new Delayed(200);
+
+            $promise = Promise\timeoutWithDefault($promise, 100, $expected);
+            $this->assertInstanceOf(Promise::class, $promise);
+
+            $callback = function ($exception, $value) use (&$actual) {
+                $actual = $value;
+            };
+
+            $promise->onResolve($callback);
+        });
+
+        $this->assertEquals($expected, $actual);
+    }
+
+    /**
+     * @depends testSuccessfulPromise
+     */
+    public function testReactPromise()
+    {
+        Loop::run(function () {
+            $value = 1;
+
+            $promise = resolve($value);
+
+            $promise = Promise\timeoutWithDefault($promise, 100, 2);
+            $this->assertInstanceOf(Promise::class, $promise);
+
+            $callback = function ($exception, $value) use (&$result) {
+                $result = $value;
+            };
+
+            $promise->onResolve($callback);
+
+            $this->assertSame($value, $result);
+        });
+    }
+
+    public function testNonPromise()
+    {
+        $this->expectException(\TypeError::class);
+        Promise\timeoutWithDefault(42, 42);
+    }
+}