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

Author: innocenzi

packages/clock/src/MockClock.php

@@ -18,9 +18,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()),
-            );
+            $this->now = DateTime::fromTimestamp($now->getTimestamp());
         } else {
             $this->now = DateTime::parse($now);
         }

packages/datetime/src/DateTime.php

@@ -4,6 +4,7 @@
 
 namespace Tempest\DateTime;
 
+use DateTimeInterface as NativeDateTimeInterface;
 use IntlCalendar;
 use Tempest\Clock\Clock;
 use Tempest\Container\GenericContainer;
@@ -142,15 +143,15 @@ public static function todayAt(int $hours, int $minutes, int $seconds = 0, int $
     }
 
     /**
-     * Creates a {@see DateTime} instance from individual date and time components.
+     * Creates a {@see Tempest\DateTime\DateTime} instance from individual date and time components.
      *
      * This method constructs a DateTime object using the specified year, month, day, hour, minute, second,
      * and nanosecond components within a given timezone. It validates each component against the Gregorian calendar
      * to ensure the date and time are possible. For example, it checks for the correct range of months (1-12),
      * days in a month (considering leap years), hours (0-23), minutes (0-59), and seconds (0-59).
      *
      * Note: In cases where the specified time occurs twice (such as during the end of daylight saving time), the earlier occurrence
-     * is returned. To obtain the later occurrence, you can adjust the returned instance using `->plusHours(1)`.
+     * is returned. To obtain the later occurrence, you can adjust the returned instance using `->plusHour()`.
      *
      * @param Month|int<1, 12> $month
      * @param int<1, 31> $day
@@ -208,19 +209,22 @@ public static function fromParts(Timezone $timezone, int $year, Month|int $month
     }
 
     /**
-     * Creates a {@see DateTime} instance from a timestamp, representing the same point in time.
-     *
-     * This method converts a {@see DateTime} into a {@see DateTime} instance calculated for the specified timezone.
+     * Creates a {@see Tempest\DateTime\DateTime} instance from a timestamp, representing the same point in time.
+     * If the timestamp is an integer, it must be a seconds-based timestamp.
      *
      * @param null|Timezone $timezone Optional timezone. If null, uses the system's default timezone.
      *
      * @see Timezone::default()
      */
     #[\Override]
-    public static function fromTimestamp(Timestamp $timestamp, ?Timezone $timezone = null): static
+    public static function fromTimestamp(int|Timestamp $timestamp, ?Timezone $timezone = null): static
     {
         $timezone ??= Timezone::default();
 
+        if (is_int($timestamp)) {
+            $timestamp = Timestamp::fromParts($timestamp);
+        }
+
         /** @var IntlCalendar $calendar */
         $calendar = IntlCalendar::createInstance(namespace\to_intl_timezone($timezone));
 
@@ -238,43 +242,55 @@ public static function fromTimestamp(Timestamp $timestamp, ?Timezone $timezone =
     }
 
     /**
-     * Parses a date and time string into an instance of {@see DateTime}. This method accepts the same parameters as the {@see \DateTime} constructor.
+     * Parses the given value into an instance of {@see Tempest\DateTime\DateTime}. The value may be an integer, second-based timestamp, a native datetime string, a native {@see \DateTimeInterface}, or a {@see Tempest\DateTime\DateTime}.
      *
-     * The {@see fromPattern} or {@see fromString} methods are recommended instead if you already know the format of the date string to parse.
+     * The {@see fromPattern} methods is recommended instead if you already know the format of the date string to parse.
      *
      * Example usage:
      *
      * ```php
-     * $raw_string = '2023-03-15 12:00:00';
-     * $parsed_timestamp = DateTime\Timestamp::parse($raw_string);
+     * $parsed = DateTime\DateTime::parse($input);
      * ```
      *
-     * @param TemporalInterface|string $string The date and time string to parse.
+     * @param NativeDateTimeInterface|TemporalInterface|string|int $string The date and time to parse.
      * @param null|Timezone $timezone Optional timezone for parsing. If null, uses the system's default timezone.
      *
      * @throws Exception\RuntimeException If the parsing process fails.
      *
-     * @return static Returns an instance of {@see DateTime} representing the parsed date and time.
+     * @return static Returns an instance of {@see Tempest\DateTime\DateTime} representing the parsed date and time.
      */
-    public static function parse(TemporalInterface|string $string, ?Timezone $timezone = null): static
+    public static function parse(NativeDateTimeInterface|TemporalInterface|string|int $string, ?Timezone $timezone = null): static
     {
+        if (is_int($string)) {
+            return self::fromTimestamp($string);
+        }
+
+        if (is_string($string) && trim($string) === 'now') {
+            return self::now($timezone);
+        }
+
+        if ($string instanceof NativeDateTimeInterface) {
+            return self::fromTimestamp(
+                timestamp: Timestamp::fromParts($string->getTimestamp()),
+                timezone: $timezone ?? Timezone::tryFrom($string->getTimezone()?->getName() ?? ''),
+            );
+        }
+
         if ($string instanceof TemporalInterface) {
             return self::fromTimestamp($string->getTimestamp());
         }
 
         return self::fromTimestamp(
-            Timestamp::fromParts(new \DateTime($string)->getTimestamp()),
-            $timezone,
+            timestamp: Timestamp::fromParts(new \DateTime($string)->getTimestamp()),
+            timezone: $timezone,
         );
     }
 
     /**
-     * Parses a date and time string into an instance of {@see DateTime} using a specific format pattern, with optional customization for timezone and locale.
-     *
-     * This method is specifically designed for cases where a custom format pattern is used to parse the input string.
+     * Parses a date and time string into an instance of {@see Tempest\DateTime\DateTime} using a specific format pattern, with optional customization for timezone and locale.
      *
+     *  This method is specifically designed for cases where a custom format pattern is used to parse the input string.
      * It allows for precise control over the parsing process by specifying the exact format pattern that matches the input string.
-     *
      * Additionally, the method supports specifying a timezone and locale for parsing, enabling accurate interpretation of locale-specific formats.
      *
      * Example usage:
@@ -304,13 +320,10 @@ public static function fromPattern(string $string, FormatPattern|string $pattern
     }
 
     /**
-     * Creates an instance of {@see DateTime} from a date and time string, formatted according to specified styles for date and time,
-     * with optional customization for timezone and locale.
-     *
-     * This method provides a more abstracted approach to parsing, allowing users  to specify styles rather than a custom pattern.
+     * Creates an instance of {@see Tempest\DateTime\DateTime} from a date and time string, formatted according to specified styles for date and time, with optional customization for timezone and locale.
      *
+     * This method provides a more abstracted approach to parsing, allowing users to specify styles rather than a custom pattern.
      * This is particularly useful for parsing strings that follow common date and time formats.
-     *
      * Additionally, the timezone and locale parameters enable accurate parsing of strings in locale-specific formats.
      *
      * Example usage:

packages/datetime/src/DateTimeConvenienceMethods.php

@@ -333,6 +333,17 @@ public function isLeapYear(): bool
         return namespace\is_leap_year($this->getYear());
     }
 
+    /**
+     * Adds a year to this date-time object, returning a new instance with the added year.
+     *
+     * @throws Exception\UnderflowException If adding the years results in an arithmetic underflow.
+     * @throws Exception\OverflowException If adding the years results in an arithmetic overflow.
+     */
+    public function plusYear(): static
+    {
+        return $this->plusYears(1);
+    }
+
     /**
      * Adds the specified years to this date-time object, returning a new instance with the added years.
      *
@@ -343,6 +354,17 @@ public function plusYears(int $years): static
         return $this->plusMonths($years * MONTHS_PER_YEAR);
     }
 
+    /**
+     * Subtracts a year from this date-time object, returning a new instance with the subtracted year.
+     *
+     * @throws Exception\UnderflowException If subtracting the years results in an arithmetic underflow.
+     * @throws Exception\OverflowException If subtracting the years results in an arithmetic overflow.
+     */
+    public function minusYear(): static
+    {
+        return $this->minusYears(1);
+    }
+
     /**
      * Subtracts the specified years from this date-time object, returning a new instance with the subtracted years.
      *
@@ -353,6 +375,17 @@ public function minusYears(int $years): static
         return $this->minusMonths($years * MONTHS_PER_YEAR);
     }
 
+    /**
+     * Adds a month to this date-time object, returning a new instance with the added month.
+     *
+     * @throws Exception\UnderflowException If adding the months results in an arithmetic underflow.
+     * @throws Exception\OverflowException If adding the months results in an arithmetic overflow.
+     */
+    public function plusMonth(): static
+    {
+        return $this->plusMonths(1);
+    }
+
     /**
      * Adds the specified months to this date-time object, returning a new instance with the added months.
      *
@@ -386,6 +419,17 @@ public function plusMonths(int $months): static
         );
     }
 
+    /**
+     * Subtracts a month from this date-time object, returning a new instance with the subtracted month.
+     *
+     * @throws Exception\UnderflowException If subtracting the months results in an arithmetic underflow.
+     * @throws Exception\OverflowException If subtracting the months results in an arithmetic overflow.
+     */
+    public function minusMonth(): static
+    {
+        return $this->minusMonths(1);
+    }
+
     /**
      * Subtracts the specified months from this date-time object, returning a new instance with the subtracted months.
      *
@@ -419,6 +463,17 @@ public function minusMonths(int $months): static
         );
     }
 
+    /**
+     * Adds a day to this date-time object, returning a new instance with the added day.
+     *
+     * @throws Exception\UnderflowException If adding the days results in an arithmetic underflow.
+     * @throws Exception\OverflowException If adding the days results in an arithmetic overflow.
+     */
+    public function plusDay(): static
+    {
+        return $this->plusDays(1);
+    }
+
     /**
      * Adds the specified days to this date-time object, returning a new instance with the added days.
      *
@@ -430,6 +485,17 @@ public function plusDays(int $days): static
         return $this->plus(Duration::days($days));
     }
 
+    /**
+     * Subtracts a day from this date-time object, returning a new instance with the subtracted day.
+     *
+     * @throws Exception\UnderflowException If subtracting the days results in an arithmetic underflow.
+     * @throws Exception\OverflowException If subtracting the days results in an arithmetic overflow.
+     */
+    public function minusDay(): static
+    {
+        return $this->minusDays(1);
+    }
+
     /**
      * Subtracts the specified days from this date-time object, returning a new instance with the subtracted days.
      *

packages/datetime/src/DateTimeInterface.php

@@ -17,7 +17,7 @@ interface DateTimeInterface extends TemporalInterface
      *
      * @see Timezone::default()
      */
-    public static function fromTimestamp(Timestamp $timestamp, ?Timezone $timezone = null): static;
+    public static function fromTimestamp(int|Timestamp $timestamp, ?Timezone $timezone = null): static;
 
     /**
      * Checks if this {@see DateTimeInterface} instance is equal to the given {@see DateTimeInterface} instance including the timezone.
@@ -305,6 +305,14 @@ public function getWeekday(): Weekday;
      */
     public function isLeapYear(): bool;
 
+    /**
+     * Adds a year to this date-time object, returning a new instance with the added year.
+     *
+     * @throws Exception\UnderflowException If adding the years results in an arithmetic underflow.
+     * @throws Exception\OverflowException If adding the years results in an arithmetic overflow.
+     */
+    public function plusYear(): static;
+
     /**
      * Adds the specified years to this date-time object, returning a new instance with the added years.
      *
@@ -313,6 +321,14 @@ public function isLeapYear(): bool;
      */
     public function plusYears(int $years): static;
 
+    /**
+     * Adds a month to this date-time object, returning a new instance with the added month.
+     *
+     * @throws Exception\UnderflowException If adding the months results in an arithmetic underflow.
+     * @throws Exception\OverflowException If adding the months results in an arithmetic overflow.
+     */
+    public function plusMonth(): static;
+
     /**
      * Adds the specified months to this date-time object, returning a new instance with the added months.
      *
@@ -321,6 +337,14 @@ public function plusYears(int $years): static;
      */
     public function plusMonths(int $months): static;
 
+    /**
+     * Adds a day to this date-time object, returning a new instance with the added day.
+     *
+     * @throws Exception\UnderflowException If adding the days results in an arithmetic underflow.
+     * @throws Exception\OverflowException If adding the days results in an arithmetic overflow.
+     */
+    public function plusDay(): static;
+
     /**
      * Adds the specified days to this date-time object, returning a new instance with the added days.
      *
@@ -329,6 +353,14 @@ public function plusMonths(int $months): static;
      */
     public function plusDays(int $days): static;
 
+    /**
+     * Subtracts a year from this date-time object, returning a new instance with the subtracted year.
+     *
+     * @throws Exception\UnderflowException If subtracting the years results in an arithmetic underflow.
+     * @throws Exception\OverflowException If subtracting the years results in an arithmetic overflow.
+     */
+    public function minusYear(): static;
+
     /**
      * Subtracts the specified years from this date-time object, returning a new instance with the subtracted years.
      *
@@ -337,6 +369,14 @@ public function plusDays(int $days): static;
      */
     public function minusYears(int $years): static;
 
+    /**
+     * Subtracts a month from this date-time object, returning a new instance with the subtracted month.
+     *
+     * @throws Exception\UnderflowException If subtracting the months results in an arithmetic underflow.
+     * @throws Exception\OverflowException If subtracting the months results in an arithmetic overflow.
+     */
+    public function minusMonth(): static;
+
     /**
      * Subtracts the specified months from this date-time object, returning a new instance with the subtracted months.
      *
@@ -345,6 +385,14 @@ public function minusYears(int $years): static;
      */
     public function minusMonths(int $months): static;
 
+    /**
+     * Subtracts a day from this date-time object, returning a new instance with the subtracted day.
+     *
+     * @throws Exception\UnderflowException If subtracting the days results in an arithmetic underflow.
+     * @throws Exception\OverflowException If subtracting the days results in an arithmetic overflow.
+     */
+    public function minusDay(): static;
+
     /**
      * Subtracts the specified days from this date-time object, returning a new instance with the subtracted days.
      *