feat(support): Port Timebox

src/support/src/Timebox.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Support;
+
+use Throwable;
+
+class Timebox
+{
+    public bool $earlyReturn = false;
+
+    /**
+     * @template TValue of mixed
+     *
+     * @param (callable(static): TValue) $callback
+     *
+     * @return TValue
+     *
+     * @throws Throwable
+     */
+    public function call(callable $callback, int $microseconds): mixed
+    {
+        $exception = null;
+
+        $start = microtime(true);
+
+        try {
+            $result = $callback($this);
+        } catch (Throwable $caught) {
+            $exception = $caught;
+        }
+
+        $remainder = (int) ($microseconds - ((microtime(true) - $start) * 1_000_000));
+
+        if (! $this->earlyReturn && $remainder > 0) {
+            $this->usleep($remainder);
+        }
+
+        if ($exception) {
+            throw $exception;
+        }
+
+        return $result;
+    }
+
+    public function returnEarly(): static
+    {
+        $this->earlyReturn = true;
+
+        return $this;
+    }
+
+    public function dontReturnEarly(): static
+    {
+        $this->earlyReturn = false;
+
+        return $this;
+    }
+
+    protected function usleep(int $microseconds)
+    {
+        Sleep::usleep($microseconds);
+    }
+}

tests/Support/TimeboxTest.php

@@ -0,0 +1,92 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hypervel\Tests\Support;
+
+use Exception;
+use Hypervel\Support\Timebox;
+use Mockery;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ * @covers \Hypervel\Support\Timebox
+ */
+class TimeboxTest extends TestCase
+{
+    public function testMakeExecutesCallback(): void
+    {
+        $callback = function () {
+            $this->assertTrue(true);
+        };
+
+        (new Timebox())->call($callback, 0);
+    }
+
+    public function testMakeWaitsForMicroseconds(): void
+    {
+        $mock = Mockery::spy(Timebox::class)->shouldAllowMockingProtectedMethods()->makePartial();
+        $mock->shouldReceive('usleep')->once();
+
+        $mock->call(function () {
+        }, 10000);
+
+        $mock->shouldHaveReceived('usleep')->once();
+    }
+
+    public function testMakeShouldNotSleepWhenEarlyReturnHasBeenFlagged(): void
+    {
+        $mock = Mockery::spy(Timebox::class)->shouldAllowMockingProtectedMethods()->makePartial();
+        $mock->call(function ($timebox) {
+            $timebox->returnEarly();
+        }, 10000);
+
+        $mock->shouldNotHaveReceived('usleep');
+    }
+
+    public function testMakeShouldSleepWhenDontEarlyReturnHasBeenFlagged(): void
+    {
+        $mock = Mockery::spy(Timebox::class)->shouldAllowMockingProtectedMethods()->makePartial();
+        $mock->shouldReceive('usleep')->once();
+
+        $mock->call(function ($timebox) {
+            $timebox->returnEarly();
+            $timebox->dontReturnEarly();
+        }, 10000);
+
+        $mock->shouldHaveReceived('usleep')->once();
+    }
+
+    public function testMakeWaitsForMicrosecondsWhenExceptionIsThrown(): void
+    {
+        $mock = Mockery::spy(Timebox::class)->shouldAllowMockingProtectedMethods()->makePartial();
+        $mock->shouldReceive('usleep')->once();
+
+        try {
+            $this->expectExceptionMessage('Exception within Timebox callback.');
+
+            $mock->call(function () {
+                throw new Exception('Exception within Timebox callback.');
+            }, 10000);
+        } finally {
+            $mock->shouldHaveReceived('usleep')->once();
+        }
+    }
+
+    public function testMakeShouldNotSleepWhenEarlyReturnHasBeenFlaggedAndExceptionIsThrown(): void
+    {
+        $mock = Mockery::spy(Timebox::class)->shouldAllowMockingProtectedMethods()->makePartial();
+
+        try {
+            $this->expectExceptionMessage('Exception within Timebox callback.');
+
+            $mock->call(function ($timebox) {
+                $timebox->returnEarly();
+                throw new Exception('Exception within Timebox callback.');
+            }, 10000);
+        } finally {
+            $mock->shouldNotHaveReceived('usleep');
+        }
+    }
+}