feat: add more constructors to durations

Author: innocenzi

packages/datetime/src/Duration.php

@@ -10,8 +10,7 @@
 use Tempest\Support\Str;
 
 /**
- * Defines a representation of a time duration with specific hours, minutes, seconds,
- * and nanoseconds.
+ * Defines a representation of a time duration with specific hours, minutes, seconds, and nanoseconds.
  *
  * All instances are normalized as follows:
  *
@@ -27,8 +26,7 @@
 final readonly class Duration implements Comparison\Comparable, Comparison\Equable, JsonSerializable, Stringable
 {
     /**
-     * Initializes a new instance of Duration with specified hours, minutes, seconds, and
-     * nanoseconds.
+     * Initializes a new instance of Duration with specified hours, minutes, seconds, and nanoseconds.
      *
      * @param int<-59, 59> $minutes
      * @param int<-59, 59> $seconds
@@ -46,7 +44,6 @@ private function __construct(
      * optionally minutes, seconds, nanoseconds). Due to normalization, the
      * actual values in the returned instance may differ from the provided ones.
      *
-     *
      * @mago-expect best-practices/no-else-clause
      */
     public static function fromParts(int $hours, int $minutes = 0, int $seconds = 0, int $nanoseconds = 0): self
@@ -70,70 +67,102 @@ public static function fromParts(int $hours, int $minutes = 0, int $seconds = 0,
     }
 
     /**
-     * Returns an instance representing the specified number of weeks, in hours.
-     *
-     * For example, `Duration::weeks(1)` is equivalent to `Duration::hours(168)`.
-     *
+     * Returns an instance representing the specified number of weeks, in hours. For example, `Duration::weeks(1)` is equivalent to `Duration::hours(168)`.
      */
     public static function weeks(int $weeks): self
     {
         return self::fromParts($weeks * HOURS_PER_WEEK);
     }
 
+    /**
+     * Returns an instance representing exactly one week.
+     */
+    public static function week(): self
+    {
+        return self::weeks(1);
+    }
+
     /**
      * Returns an instance representing the specified number of days, in hours.
      *
      * For example, `Duration::days(2)` is equivalent to `Duration::hours(48)`.
-     *
      */
     public static function days(int $days): self
     {
         return self::fromParts($days * HOURS_PER_DAY);
     }
 
+    /**
+     * Returns an instance representing exactly one day.
+     */
+    public static function day(): self
+    {
+        return self::days(1);
+    }
+
     /**
      * Returns an instance representing the specified number of hours.
-     *
      */
     public static function hours(int $hours): self
     {
         return self::fromParts($hours);
     }
 
+    /**
+     * Returns an instance representing exactly one hour.
+     */
+    public static function hour(): self
+    {
+        return self::hours(1);
+    }
+
     /**
      * Returns an instance representing the specified number of minutes. Due to
      * normalization, the actual value in the returned instance may differ from
      * the provided one, and the resulting instance may contain larger units.
      *
      * For example, `Duration::minutes(63)` normalizes to "1 hour(s), 3 minute(s)".
-     *
      */
     public static function minutes(int $minutes): self
     {
         return self::fromParts(0, $minutes);
     }
 
+    /**
+     * Returns an instance representing exactly one minute.
+     */
+    public static function minute(): self
+    {
+        return self::minutes(1);
+    }
+
     /**
      * Returns an instance representing the specified number of seconds. Due to
      * normalization, the actual value in the returned instance may differ from
      * the provided one, and the resulting instance may contain larger units.
      *
      * For example, `Duration::seconds(63)` normalizes to "1 minute(s), 3 second(s)".
-     *
      */
     public static function seconds(int $seconds): self
     {
         return self::fromParts(0, 0, $seconds);
     }
 
+    /**
+     * Returns an instance representing exactly one second.
+     */
+    public static function second(): self
+    {
+        return self::seconds(1);
+    }
+
     /**
      * Returns an instance representing the specified number of milliseconds (ms).
      * The value is converted and stored as nanoseconds, since that is the only
      * unit smaller than a second that we support. Due to normalization, the
      * resulting instance may contain larger units.
      *
      * For example, `Duration::milliseconds(8042)` normalizes to "8 second(s), 42000000 nanosecond(s)".
-     *
      */
     public static function milliseconds(int $milliseconds): self
     {

packages/datetime/tests/DurationTest.php

@@ -35,10 +35,15 @@ public function test_getters(): void
     public function test_named_constructors(): void
     {
         $this->assertSame(168.0, DateTime\Duration::weeks(1)->getTotalHours());
+        $this->assertSame(168.0, DateTime\Duration::week()->getTotalHours());
         $this->assertSame(24.0, DateTime\Duration::days(1)->getTotalHours());
+        $this->assertSame(24.0, DateTime\Duration::day()->getTotalHours());
         $this->assertSame(1.0, DateTime\Duration::hours(1)->getTotalHours());
+        $this->assertSame(1.0, DateTime\Duration::hour()->getTotalHours());
         $this->assertSame(1.0, DateTime\Duration::minutes(1)->getTotalMinutes());
+        $this->assertSame(1.0, DateTime\Duration::minute()->getTotalMinutes());
         $this->assertSame(1.0, DateTime\Duration::seconds(1)->getTotalSeconds());
+        $this->assertSame(1.0, DateTime\Duration::second()->getTotalSeconds());
         $this->assertSame(1.0, DateTime\Duration::milliseconds(1)->getTotalMilliseconds());
         $this->assertSame(1.0, DateTime\Duration::microseconds(1)->getTotalMicroseconds());
         $this->assertSame(1, DateTime\Duration::nanoseconds(1)->getNanoseconds());