add timeoutWithDefault function

lib/functions.php

@@ -223,6 +223,47 @@ function timeout($promise, int $timeout): 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
+    {
+        if (!$promise instanceof Promise) {
+            if ($promise instanceof ReactPromise) {
+                $promise = adapt($promise);
+            } else {
+                throw createTypeError([Promise::class, ReactPromise::class], $promise);
+            }
+        }
+
+        $promise = timeout($promise, $timeout);
+
+        $deferred = new Deferred();
+        $newPromise = $deferred->promise();
+
+        $promise->onResolve(function ($exception, $value) use ($deferred, $default) {
+            if ($exception) {
+                $deferred->resolve($default);
+            } else {
+                $deferred->resolve($value);
+            }
+        });
+
+        return $newPromise;
+    }
+
     /**
      * 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,129 @@
+<?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;
+            $expected = 2;
+
+            $promise = new Failure($exception);
+
+            $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 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);
+    }
+}