From 769eebb07dca593bc57f419505304f8acc5e286d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20L=C3=BCck?= <christian@clue.engineering>
Date: Tue, 19 Oct 2021 12:20:00 +0200
Subject: [PATCH 1/2] Change to use functional API instead of static `Util`
 class

---
 README.md                                     |  39 +++++--
 composer.json                                 |   4 +-
 src/Util.php                                  | 106 ------------------
 src/functions.php                             | 103 +++++++++++++++++
 src/functions_include.php                     |   8 ++
 ...{UtilParallelTest.php => ParallelTest.php} |  12 +-
 tests/{UtilSeriesTest.php => SeriesTest.php}  |  10 +-
 ...tilWaterfallTest.php => WaterfallTest.php} |  10 +-
 8 files changed, 161 insertions(+), 131 deletions(-)
 delete mode 100644 src/Util.php
 create mode 100644 src/functions.php
 create mode 100644 src/functions_include.php
 rename tests/{UtilParallelTest.php => ParallelTest.php} (89%)
 rename tests/{UtilSeriesTest.php => SeriesTest.php} (88%)
 rename tests/{UtilWaterfallTest.php => WaterfallTest.php} (89%)

diff --git a/README.md b/README.md
index 77a0774..7ae5c2f 100644
--- a/README.md
+++ b/README.md
@@ -25,8 +25,8 @@ whatsoever!*
 **Table of Contents**
 
 * [Usage](#usage)
-    * [Parallel](#parallel)
-    * [Waterfall](#waterfall)
+    * [parallel()](#parallel)
+    * [waterfall()](#waterfall)
 * [Todo](#todo)
 * [Install](#install)
 * [Tests](#tests)
@@ -34,15 +34,39 @@ whatsoever!*
 
 ## Usage
 
-### Parallel
+This lightweight library consists only of a few simple functions.
+All functions reside under the `React\Async` namespace.
+
+The below examples refer to all functions with their fully-qualified names like this:
+
+```php
+React\Async\parallel(…);
+```
+
+As of PHP 5.6+ you can also import each required function into your code like this:
+
+```php
+use function React\Async\parallel;
+
+parallel(…);
+```
+
+Alternatively, you can also use an import statement similar to this:
+
+```php
+use React\Async;
+
+Async\parallel(…);
+```
+
+### parallel()
 
 ```php
 <?php
 
-use React\Async\Util as Async;
 use React\EventLoop\Loop;
 
-Async::parallel(
+React\Async\parallel(
     array(
         function ($callback, $errback) {
             Loop::addTimer(1, function () use ($callback) {
@@ -71,12 +95,11 @@ Async::parallel(
 );
 ```
 
-### Waterfall
+### waterfall()
 
 ```php
 <?php
 
-use React\Async\Util as Async;
 use React\EventLoop\Loop;
 
 $addOne = function ($prev, $callback = null) {
@@ -90,7 +113,7 @@ $addOne = function ($prev, $callback = null) {
     });
 };
 
-Async::waterfall(array(
+React\Async\waterfall(array(
     $addOne,
     $addOne,
     $addOne,
diff --git a/composer.json b/composer.json
index d864160..44c37fd 100644
--- a/composer.json
+++ b/composer.json
@@ -36,7 +36,9 @@
         "react/event-loop": "You need an event loop for this to make sense."
     },
     "autoload": {
-        "psr-4": { "React\\Async\\": "src/" }
+        "files": [
+            "src/functions_include.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": { "React\\Tests\\Async\\": "tests/" }
diff --git a/src/Util.php b/src/Util.php
deleted file mode 100644
index 3bf96d0..0000000
--- a/src/Util.php
+++ /dev/null
@@ -1,106 +0,0 @@
-<?php
-
-namespace React\Async;
-
-class Util
-{
-    public static function series($tasks, $callback = null, $errback = null)
-    {
-        $results = array();
-
-        $taskCallback = function ($result) use (&$results, &$next) {
-            $results[] = $result;
-            $next();
-        };
-
-        $done = function () use (&$results, $callback) {
-            if ($callback) {
-                call_user_func($callback, $results);
-            }
-        };
-
-        $next = function () use (&$tasks, $taskCallback, $errback, $done) {
-            if (0 === count($tasks)) {
-                $done();
-                return;
-            }
-
-            $task = array_shift($tasks);
-            call_user_func($task, $taskCallback, $errback);
-        };
-
-        $next();
-    }
-
-    public static function parallel($tasks, $callback = null, $errback = null)
-    {
-        $results = array();
-        $errors = array();
-
-        $taskErrback = function ($error) use (&$errors, &$checkDone) {
-            $errors[] = $error;
-            $checkDone();
-        };
-
-        $done = function () use (&$results, &$errors, $callback, $errback) {
-            if (!$callback) {
-                return;
-            }
-
-            if (count($errors)) {
-                $errback(array_shift($errors));
-                return;
-            }
-
-            $callback($results);
-        };
-
-        $numTasks = count($tasks);
-
-        if (0 === $numTasks) {
-            $done();
-            return;
-        }
-
-        $checkDone = function () use (&$results, &$errors, $numTasks, $done) {
-            if ($numTasks === count($results) + count($errors)) {
-                $done();
-            }
-        };
-
-        foreach ($tasks as $i => $task) {
-            $taskCallback = function ($result) use (&$results, $i, $checkDone) {
-                $results[$i] = $result;
-                $checkDone();
-            };
-
-            call_user_func($task, $taskCallback, $taskErrback);
-        }
-    }
-
-    public static function waterfall($tasks, $callback = null, $errback = null)
-    {
-        $taskCallback = function () use (&$next) {
-            call_user_func_array($next, func_get_args());
-        };
-
-        $done = function () use ($callback) {
-            if ($callback) {
-                call_user_func_array($callback, func_get_args());
-            }
-        };
-
-        $next = function () use (&$tasks, $taskCallback, $errback, $done) {
-            if (0 === count($tasks)) {
-                call_user_func_array($done, func_get_args());
-                return;
-            }
-
-            $task = array_shift($tasks);
-            $args = array_merge(func_get_args(), array($taskCallback, $errback));
-            call_user_func_array($task, $args);
-        };
-
-        $next();
-    }
-}
diff --git a/src/functions.php b/src/functions.php
new file mode 100644
index 0000000..465cc4d
--- /dev/null
+++ b/src/functions.php
@@ -0,0 +1,103 @@
+<?php
+
+namespace React\Async;
+
+function parallel($tasks, $callback = null, $errback = null)
+{
+    $results = array();
+    $errors = array();
+
+    $taskErrback = function ($error) use (&$errors, &$checkDone) {
+        $errors[] = $error;
+        $checkDone();
+    };
+
+    $done = function () use (&$results, &$errors, $callback, $errback) {
+        if (!$callback) {
+            return;
+        }
+
+        if (count($errors)) {
+            $errback(array_shift($errors));
+            return;
+        }
+
+        $callback($results);
+    };
+
+    $numTasks = count($tasks);
+
+    if (0 === $numTasks) {
+        $done();
+        return;
+    }
+
+    $checkDone = function () use (&$results, &$errors, $numTasks, $done) {
+        if ($numTasks === count($results) + count($errors)) {
+            $done();
+        }
+    };
+
+    foreach ($tasks as $i => $task) {
+        $taskCallback = function ($result) use (&$results, $i, $checkDone) {
+            $results[$i] = $result;
+            $checkDone();
+        };
+
+        call_user_func($task, $taskCallback, $taskErrback);
+    }
+}
+
+function series($tasks, $callback = null, $errback = null)
+{
+    $results = array();
+
+    $taskCallback = function ($result) use (&$results, &$next) {
+        $results[] = $result;
+        $next();
+    };
+
+    $done = function () use (&$results, $callback) {
+        if ($callback) {
+            call_user_func($callback, $results);
+        }
+    };
+
+    $next = function () use (&$tasks, $taskCallback, $errback, $done) {
+        if (0 === count($tasks)) {
+            $done();
+            return;
+        }
+
+        $task = array_shift($tasks);
+        call_user_func($task, $taskCallback, $errback);
+    };
+
+    $next();
+}
+
+function waterfall($tasks, $callback = null, $errback = null)
+{
+    $taskCallback = function () use (&$next) {
+        call_user_func_array($next, func_get_args());
+    };
+
+    $done = function () use ($callback) {
+        if ($callback) {
+            call_user_func_array($callback, func_get_args());
+        }
+    };
+
+    $next = function () use (&$tasks, $taskCallback, $errback, $done) {
+        if (0 === count($tasks)) {
+            call_user_func_array($done, func_get_args());
+            return;
+        }
+
+        $task = array_shift($tasks);
+        $args = array_merge(func_get_args(), array($taskCallback, $errback));
+        call_user_func_array($task, $args);
+    };
+
+    $next();
+}
diff --git a/src/functions_include.php b/src/functions_include.php
new file mode 100644
index 0000000..92a7439
--- /dev/null
+++ b/src/functions_include.php
@@ -0,0 +1,8 @@
+<?php
+
+namespace React\Async;
+
+// @codeCoverageIgnoreStart
+if (!function_exists(__NAMESPACE__ . '\\parallel')) {
+    require __DIR__ . '/functions.php';
+}
diff --git a/tests/UtilParallelTest.php b/tests/ParallelTest.php
similarity index 89%
rename from tests/UtilParallelTest.php
rename to tests/ParallelTest.php
index 62c59b7..8889db2 100644
--- a/tests/UtilParallelTest.php
+++ b/tests/ParallelTest.php
@@ -2,10 +2,10 @@
 
 namespace React\Tests\Async;
 
-use React\Async\Util;
+use React;
 use React\EventLoop\Loop;
 
-class UtilParallelTest extends TestCase
+class ParallelTest extends TestCase
 {
     public function testParallelWithoutTasks()
     {
@@ -14,7 +14,7 @@ public function testParallelWithoutTasks()
         $callback = $this->expectCallableOnceWith(array());
         $errback = $this->expectCallableNever();
 
-        Util::parallel($tasks, $callback, $errback);
+        React\Async\parallel($tasks, $callback, $errback);
     }
 
     public function testParallelWithTasks()
@@ -35,7 +35,7 @@ function ($callback, $errback) {
         $callback = $this->expectCallableOnceWith(array('foo', 'bar'));
         $errback = $this->expectCallableNever();
 
-        Util::parallel($tasks, $callback, $errback);
+        React\Async\parallel($tasks, $callback, $errback);
 
         $timer = new Timer($this);
         $timer->start();
@@ -68,7 +68,7 @@ function ($callback, $errback) use (&$called) {
         $callback = $this->expectCallableNever();
         $errback = $this->expectCallableOnce();
 
-        Util::parallel($tasks, $callback, $errback);
+        React\Async\parallel($tasks, $callback, $errback);
 
         $this->assertSame(2, $called);
     }
@@ -97,7 +97,7 @@ function ($callback, $errback) use (&$called) {
         $callback = $this->expectCallableNever();
         $errback = $this->expectCallableOnce();
 
-        Util::parallel($tasks, $callback, $errback);
+        React\Async\parallel($tasks, $callback, $errback);
 
         Loop::run();
 
diff --git a/tests/UtilSeriesTest.php b/tests/SeriesTest.php
similarity index 88%
rename from tests/UtilSeriesTest.php
rename to tests/SeriesTest.php
index 95fa182..7a6bb1b 100644
--- a/tests/UtilSeriesTest.php
+++ b/tests/SeriesTest.php
@@ -2,10 +2,10 @@
 
 namespace React\Tests\Async;
 
-use React\Async\Util;
+use React;
 use React\EventLoop\Loop;
 
-class UtilSeriesTest extends TestCase
+class SeriesTest extends TestCase
 {
     public function testSeriesWithoutTasks()
     {
@@ -14,7 +14,7 @@ public function testSeriesWithoutTasks()
         $callback = $this->expectCallableOnceWith(array());
         $errback = $this->expectCallableNever();
 
-        Util::series($tasks, $callback, $errback);
+        React\Async\series($tasks, $callback, $errback);
     }
 
     public function testSeriesWithTasks()
@@ -35,7 +35,7 @@ function ($callback, $errback) {
         $callback = $this->expectCallableOnceWith(array('foo', 'bar'));
         $errback = $this->expectCallableNever();
 
-        Util::series($tasks, $callback, $errback);
+        React\Async\series($tasks, $callback, $errback);
 
         $timer = new Timer($this);
         $timer->start();
@@ -68,7 +68,7 @@ function ($callback, $errback) use (&$called) {
         $callback = $this->expectCallableNever();
         $errback = $this->expectCallableOnce();
 
-        Util::series($tasks, $callback, $errback);
+        React\Async\series($tasks, $callback, $errback);
 
         $this->assertSame(1, $called);
     }
diff --git a/tests/UtilWaterfallTest.php b/tests/WaterfallTest.php
similarity index 89%
rename from tests/UtilWaterfallTest.php
rename to tests/WaterfallTest.php
index b8d384b..c8711f8 100644
--- a/tests/UtilWaterfallTest.php
+++ b/tests/WaterfallTest.php
@@ -2,10 +2,10 @@
 
 namespace React\Tests\Async;
 
-use React\Async\Util;
+use React;
 use React\EventLoop\Loop;
 
-class UtilWaterfallTest extends TestCase
+class WaterfallTest extends TestCase
 {
     public function testWaterfallWithoutTasks()
     {
@@ -14,7 +14,7 @@ public function testWaterfallWithoutTasks()
         $callback = $this->expectCallableOnce();
         $errback = $this->expectCallableNever();
 
-        Util::waterfall($tasks, $callback, $errback);
+        React\Async\waterfall($tasks, $callback, $errback);
     }
 
     public function testWaterfallWithTasks()
@@ -40,7 +40,7 @@ function ($bar, $callback, $errback) {
         $callback = $this->expectCallableOnceWith('foobarbaz');
         $errback = $this->expectCallableNever();
 
-        Util::waterfall($tasks, $callback, $errback);
+        React\Async\waterfall($tasks, $callback, $errback);
 
         $timer = new Timer($this);
         $timer->start();
@@ -73,7 +73,7 @@ function ($callback, $errback) use (&$called) {
         $callback = $this->expectCallableNever();
         $errback = $this->expectCallableOnce();
 
-        Util::waterfall($tasks, $callback, $errback);
+        React\Async\waterfall($tasks, $callback, $errback);
 
         $this->assertSame(1, $called);
     }

From a37c28eeeb0611588e3ef5407fb105fed7f00434 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christian=20L=C3=BCck?= <christian@clue.engineering>
Date: Tue, 19 Oct 2021 12:44:33 +0200
Subject: [PATCH 2/2] Improve API documentation

---
 README.md         | 48 ++++++++++++++++++++++++++++++++++++++++++++++-
 src/functions.php | 35 ++++++++++++++++++++++++++--------
 2 files changed, 74 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 7ae5c2f..8fbe641 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,7 @@ whatsoever!*
 
 * [Usage](#usage)
     * [parallel()](#parallel)
+    * [series()](#series)
     * [waterfall()](#waterfall)
 * [Todo](#todo)
 * [Install](#install)
@@ -61,6 +62,9 @@ Async\parallel(…);
 
 ### parallel()
 
+The `parallel(array<callable> $tasks, ?callable $callback = null, ?callable $errback = null): void` function can be used
+like this:
+
 ```php
 <?php
 
@@ -89,7 +93,46 @@ React\Async\parallel(
             var_dump($result);
         }
     },
-    function (\Exception $e) {
+    function (Exception $e) {
+        throw $e;
+    }
+);
+```
+
+### series()
+
+The `series(array<callable> $tasks, ?callable $callback = null, ?callable $errback = null): void` function can be used
+like this:
+
+```php
+<?php
+
+use React\EventLoop\Loop;
+
+React\Async\series(
+    array(
+        function ($callback, $errback) {
+            Loop::addTimer(1, function () use ($callback) {
+                $callback('Slept for a whole second');
+            });
+        },
+        function ($callback, $errback) {
+            Loop::addTimer(1, function () use ($callback) {
+                $callback('Slept for another whole second');
+            });
+        },
+        function ($callback, $errback) {
+            Loop::addTimer(1, function () use ($callback) {
+                $callback('Slept for yet another whole second');
+            });
+        },
+    ),
+    function (array $results) {
+        foreach ($results as $result) {
+            var_dump($result);
+        }
+    },
+    function (Exception $e) {
         throw $e;
     }
 );
@@ -97,6 +140,9 @@ React\Async\parallel(
 
 ### waterfall()
 
+The `waterfall(array<callable> $tasks, ?callable $callback = null, ?callable $errback = null): void` function can be used
+like this:
+
 ```php
 <?php
 
diff --git a/src/functions.php b/src/functions.php
index 465cc4d..b717cd8 100644
--- a/src/functions.php
+++ b/src/functions.php
@@ -2,16 +2,17 @@
 
 namespace React\Async;
 
-function parallel($tasks, $callback = null, $errback = null)
+/**
+ * @param array<callable> $tasks
+ * @param ?callable       $callback
+ * @param ?callable       $errback
+ * @return void
+ */
+function parallel(array $tasks, $callback = null, $errback = null)
 {
     $results = array();
     $errors = array();
 
-    $taskErrback = function ($error) use (&$errors, &$checkDone) {
-        $errors[] = $error;
-        $checkDone();
-    };
-
     $done = function () use (&$results, &$errors, $callback, $errback) {
         if (!$callback) {
             return;
@@ -38,6 +39,11 @@ function parallel($tasks, $callback = null, $errback = null)
         }
     };
 
+    $taskErrback = function ($error) use (&$errors, $checkDone) {
+        $errors[] = $error;
+        $checkDone();
+    };
+
     foreach ($tasks as $i => $task) {
         $taskCallback = function ($result) use (&$results, $i, $checkDone) {
             $results[$i] = $result;
@@ -48,10 +54,17 @@ function parallel($tasks, $callback = null, $errback = null)
     }
 }
 
-function series($tasks, $callback = null, $errback = null)
+/**
+ * @param array<callable> $tasks
+ * @param ?callable       $callback
+ * @param ?callable       $errback
+ * @return void
+ */
+function series(array $tasks, $callback = null, $errback = null)
 {
     $results = array();
 
+    /** @var callable():void $next */
     $taskCallback = function ($result) use (&$results, &$next) {
         $results[] = $result;
         $next();
@@ -76,7 +89,13 @@ function series($tasks, $callback = null, $errback = null)
     $next();
 }
 
-function waterfall($tasks, $callback = null, $errback = null)
+/**
+ * @param array<callable> $tasks
+ * @param ?callable       $callback
+ * @param ?callable       $errback
+ * @return void
+ */
+function waterfall(array $tasks, $callback = null, $errback = null)
 {
     $taskCallback = function () use (&$next) {
         call_user_func_array($next, func_get_args());