feat(datetime): support tempest datetime in validator and mapper (#1257)

Author: innocenzi

packages/clock/src/Clock.php

@@ -7,6 +7,7 @@
 use Psr\Clock\ClockInterface;
 use Tempest\DateTime\DateTimeInterface;
 use Tempest\DateTime\Duration;
+use Tempest\DateTime\Timestamp;
 
 interface Clock
 {
@@ -21,14 +22,19 @@ public function now(): DateTimeInterface;
     public function toPsrClock(): ClockInterface;
 
     /**
-     * Returns the current timestamp in seconds.
+     * Returns the current timestamp.
      */
-    public function timestamp(): int;
+    public function timestamp(): Timestamp;
+
+    /**
+     * Returns the current UNIX timestamp in seconds.
+     */
+    public function seconds(): int;
 
     /**
      * Returns the current timestamp in milliseconds.
      */
-    public function timestampMs(): int;
+    public function milliseconds(): int;
 
     /**
      * Sleeps for the given number of milliseconds.

packages/clock/src/GenericClock.php

@@ -24,12 +24,17 @@ public function now(): DateTimeInterface
         return DateTime::now();
     }
 
-    public function timestamp(): int
+    public function timestamp(): Timestamp
+    {
+        return Timestamp::monotonic();
+    }
+
+    public function seconds(): int
     {
         return Timestamp::monotonic()->getSeconds();
     }
 
-    public function timestampMs(): int
+    public function milliseconds(): int
     {
         return Timestamp::monotonic()->getMilliseconds();
     }

packages/clock/src/MockClock.php

@@ -17,13 +17,7 @@ final class MockClock implements Clock
 
     public function __construct(DateTimeImmutable|DateTimeInterface|string $now = 'now')
     {
-        if ($now instanceof DateTimeImmutable) {
-            $this->now = DateTime::fromTimestamp(
-                Timestamp::fromParts($now->getTimestamp()),
-            );
-        } else {
-            $this->now = DateTime::parse($now);
-        }
+        $this->setNow($now);
     }
 
     public function toPsrClock(): ClockInterface
@@ -36,53 +30,61 @@ public function now(): DateTimeInterface
         return $this->now;
     }
 
-    public function setNow(DateTimeInterface|string $now): void
+    /**
+     * Globally sets the current time to the specified value.
+     */
+    public function setNow(DateTimeImmutable|DateTimeInterface|string $now): void
     {
-        if ($now instanceof DateTimeInterface) {
-            $this->now = $now;
-        } else {
-            $this->now = DateTime::parse($now);
-        }
+        $this->now = DateTime::parse($now);
     }
 
-    public function timestamp(): int
+    public function timestamp(): Timestamp
+    {
+        return $this->now->getTimestamp();
+    }
+
+    public function seconds(): int
     {
         return $this->now->getTimestamp()->getSeconds();
     }
 
-    public function timestampMs(): int
+    public function milliseconds(): int
     {
         return $this->now->getTimestamp()->getMilliseconds();
     }
 
     public function sleep(int|Duration $milliseconds): void
     {
         if ($milliseconds instanceof Duration) {
-            $this->addInterval($milliseconds);
+            $this->plus($milliseconds);
             return;
         }
 
         $this->now = $this->now->plusMilliseconds($milliseconds);
     }
 
-    public function addInterval(Duration $duration): void
+    /**
+     * Adds the given duration. Providing an integer value adds the corresponding seconds to the current time.
+     */
+    public function plus(int|Duration $duration): void
     {
-        $this->now = $this->now->plus($duration);
-    }
+        if (is_int($duration)) {
+            $duration = Duration::seconds($duration);
+        }
 
-    public function subInternal(Duration $duration): void
-    {
-        $this->now = $this->now->minus($duration);
+        $this->now = $this->now->plus($duration);
     }
 
-    public function changeTime(int $seconds): void
+    /**
+     * Removes the given duration. Providing an integer value removes the corresponding seconds to the current time.
+     */
+    public function minus(int|Duration $duration): void
     {
-        if ($seconds < 0) {
-            $seconds = abs($seconds);
-            $this->now = $this->now->minusSeconds($seconds);
-        } else {
-            $this->now = $this->now->plusSeconds($seconds);
+        if (is_int($duration)) {
+            $duration = Duration::seconds($duration);
         }
+
+        $this->now = $this->now->minus($duration);
     }
 
     public function dd(): void

packages/clock/src/PsrClock.php

@@ -13,6 +13,6 @@ public function __construct(
 
     public function now(): DateTimeImmutable
     {
-        return DateTimeImmutable::createFromTimestamp($this->clock->timestamp());
+        return DateTimeImmutable::createFromTimestamp($this->clock->seconds());
     }
 }

packages/clock/tests/GenericClockTest.php

@@ -29,7 +29,7 @@ public function test_that_generic_clock_returns_the_current_date_time(): void
     public function test_that_generic_clock_returns_the_current_time(): void
     {
         $timeBefore = new DateTimeImmutable()->getTimestamp();
-        $clockTime = new GenericClock()->timestamp();
+        $clockTime = new GenericClock()->seconds();
         $timeAfter = new DateTimeImmutable()->getTimestamp();
 
         $this->assertGreaterThanOrEqual($timeBefore, $clockTime);

packages/clock/tests/MockClockTest.php

@@ -41,7 +41,7 @@ public function test_mock_clock_returns_the_time_we_want(): void
         $time = DateTime::parse('2024-09-11 13:54:23');
         $clock = new MockClock($time);
 
-        $this->assertEquals($time->getTimestamp()->getSeconds(), $clock->timestamp());
+        $this->assertEquals($time->getTimestamp()->getSeconds(), $clock->seconds());
     }
 
     public function test_mock_clock_sleeps_time(): void
@@ -52,7 +52,7 @@ public function test_mock_clock_sleeps_time(): void
         $clock = new MockClock($oldTime);
         $clock->sleep(2_000);
 
-        $this->assertSame($expectedTime->getTimestamp()->getSeconds(), $clock->timestamp());
+        $this->assertSame($expectedTime->getTimestamp()->getSeconds(), $clock->seconds());
     }
 
     public function test_mock_clock_can_change_time(): void
@@ -62,14 +62,14 @@ public function test_mock_clock_can_change_time(): void
         $addedTime = DateTime::parse('2024-09-11 13:54:25');
         $clock = new MockClock($dateTime);
 
-        $clock->changeTime(-2);
+        $clock->minus(2);
 
         $this->assertEquals($subtractedTime, $clock->now());
-        $this->assertEquals($subtractedTime->getTimestamp()->getSeconds(), $clock->timestamp());
+        $this->assertEquals($subtractedTime->getTimestamp()->getSeconds(), $clock->seconds());
 
-        $clock->changeTime(4);
+        $clock->plus(4);
 
         $this->assertEquals($addedTime, $clock->now());
-        $this->assertEquals($addedTime->getTimestamp()->getSeconds(), $clock->timestamp());
+        $this->assertEquals($addedTime->getTimestamp()->getSeconds(), $clock->seconds());
     }
 }