refactor and make better

Author: withinboredom

composer.json

@@ -5,10 +5,10 @@
     "license": "MIT",
     "autoload": {
         "psr-4": {
-            "Withinboredom\\Time\\": "src/"
+            "Withinboredom\\": "src/"
         },
         "files": [
-            "src/functions.php"
+            "src/Time/functions.php"
         ]
     },
     "authors": [
@@ -18,12 +18,15 @@
         }
     ],
     "require": {
-        "php": "^8.2"
+        "php": "^8.4"
     },
     "require-dev": {
-        "pestphp/pest": "^2.34.8",
+        "pestphp/pest": "^v3.8.2",
         "laravel/pint": "^1.16.2"
     },
+    "suggest": {
+        "crell/serde": "^1.3.2"
+    },
     "config": {
         "allow-plugins": {
             "pestphp/pest-plugin": true

composer.lock

@@ -1,35 +1,75 @@
-# A really simple library for converting time
+# An advanced library offering type safety and identity with Durations
 
-This is a simple library for interacting with time durations.
-You can write your code to expect time and know that is what you have:
+## Identity
+
+This library uses some tricks to intern values so that two times are always equal to one another,
+no matter the distance in time or space.
+
+```php
+use Withinboredom\Time;
+use Withinboredom\Time\Unit;
+
+$hour = Time::from(Unit::Hours, 1);
+$minutes = Time::from(Unit::Minutes, 60);
+
+echo $hour === $minutes ? 'true' : 'false'
+// outputs: true
+```
+
+## Type Safety
+
+You can ensure nobody will accidentally confuse seconds with milliseconds or minutes with seconds:
 
 ```php
-function sleep(\Withinboredom\Time\Time $time): void {
-    \sleep($time->as(\Withinboredom\Time\TimeUnit::Seconds));
+function sleep(Time $time): void {
+    \sleep($time->as(Unit::Seconds));
 }
 
-sleep(\Withinboredom\Time\Minutes(5));
+// Helper functions are included so you can type less code:
+sleep(Minutes(5));
 ```
 
-## Equality
+## Conversions and Math
 
-All values of the same time are always strongly equaled to each other:
+You can easily convert between units and even perform operations, like sorting and arithmetic:
 
 ```php
-\Withinboredom\Time\Minutes(60) === \Withinboredom\Time\Hours(1)
+// use the hour constant to get one hour
+$hour = Hour;
+
+$hour = $hour->multiply(10)->add(Minutes(10)); // get 10:10 hours
+
+$interval = $hour->toDateInterval();
+
+echo Hours(10) < $hour ? 'true' : 'false';
+// output: true
 ```
 
-## Utilities
+## Support for Crell\Serde
 
-There are also a few utility methods:
+You cannot serialize/deserialize/clone `Time` objects.
+However, if you use something like Serde, you can still serialize your value objects:
 
-> ->add(Time)->subtract(Time): AnyTime
+```php
+class CacheItem {
+    public function __construct(
+        #[Field('expiration_in_seconds')]
+        #[TimeAs(Unit::Seconds)]
+        public Time $expiration,
+    ) {}
+}
 
-Add and subtract durations.
+$serde = new SerdeCommon(handlers: new \Withinboredom\Time\SerdeExporter());
+$serde->serialize(new CacheItem(Minutes(5)), 'json');
+```
 
-> ->toDateInterval(): DateInterval
+The above will be serialized (and deserialized) from:
 
-Creates a date interval for use in other things.
+```json
+{
+    "expiration_in_seconds": 300
+}
+```
 
 ## Units
 
@@ -45,7 +85,7 @@ Creates a date interval for use in other things.
 
 > Why not months/years?
 
-There's no set days in a month/year, so it’s better to use `DateInterval` for those types of measures.
+There are no set days in a month/year, so it’s better to use `DateInterval` for those types of measures.
 
 > Why does this exist?
 

readme.md

@@ -1,8 +1,9 @@
 <?php
 
-namespace Withinboredom\Time;
+namespace Withinboredom;
 
 use WeakReference;
+use Withinboredom\Time\Unit;
 
 final class Time
 {
@@ -28,17 +29,17 @@ public function __destruct()
 
     private function __construct(private readonly int $nanoseconds)
     {
-        if($this->nanoseconds < 0) {
+        if ($this->nanoseconds < 0) {
             throw new \InvalidArgumentException('Time cannot be negative');
         }
     }
 
-    public static function from(TimeUnit $unit, float $value): Time
+    public static function from(Unit $unit, float $value): Time
     {
         return self::getValue($unit->value * $value);
     }
 
-    public function as(TimeUnit $unit): float
+    public function as(Unit $unit): float
     {
         return $this->nanoseconds / $unit->value;
     }
@@ -65,11 +66,11 @@ public function divide(float $value): Time
 
     private function components(): array
     {
-        $weeks = (int) $this->as(TimeUnit::Weeks);
-        $days = (int) $this->as(TimeUnit::Days) - $weeks * 7;
-        $hours = (int) $this->as(TimeUnit::Hours) - $weeks * 7 * 24 - $days * 24;
-        $minutes = (int) $this->as(TimeUnit::Minutes) - $weeks * 7 * 24 * 60 - $days * 24 * 60 - $hours * 60;
-        $seconds = (int) $this->as(TimeUnit::Seconds) - $weeks * 7 * 24 * 60 * 60 - $days * 24 * 60 * 60 - $hours * 60 * 60 - $minutes * 60;
+        $weeks = (int) $this->as(Unit::Weeks);
+        $days = (int) $this->as(Unit::Days) - $weeks * 7;
+        $hours = (int) $this->as(Unit::Hours) - $weeks * 7 * 24 - $days * 24;
+        $minutes = (int) $this->as(Unit::Minutes) - $weeks * 7 * 24 * 60 - $days * 24 * 60 - $hours * 60;
+        $seconds = (int) $this->as(Unit::Seconds) - $weeks * 7 * 24 * 60 * 60 - $days * 24 * 60 * 60 - $hours * 60 * 60 - $minutes * 60;
 
         return [$weeks, $days, $hours, $minutes, $seconds];
     }

src/Time.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Withinboredom\Time;
+
+use Crell\Serde\Attributes\Field;
+use Crell\Serde\DeformatterResult;
+use Crell\Serde\Deserializer;
+use Crell\Serde\PropertyHandler\Exporter;
+use Crell\Serde\PropertyHandler\Importer;
+use Crell\Serde\Serializer;
+use Withinboredom\Time;
+
+class SerdeExporter implements Exporter, Importer
+{
+    public function exportValue(Serializer $serializer, Field $field, mixed $value, mixed $runningValue): mixed
+    {
+        $typeField = $field->typeField;
+        assert($typeField instanceof TimeAs);
+        assert($value instanceof Time);
+
+        return $serializer->formatter->serializeInt($runningValue, $field, $value->as($typeField->unit));
+    }
+
+    public function canExport(Field $field, mixed $value, string $format): bool
+    {
+        return $value instanceof Time && $field->typeField instanceof TimeAs;
+    }
+
+    public function importValue(Deserializer $deserializer, Field $field, mixed $source): mixed
+    {
+        $typeField = $field->typeField;
+        assert($typeField instanceof TimeAs);
+
+        $number = $deserializer->deformatter->deserializeInt($source, $field);
+
+        if ($number === DeformatterResult::Missing) {
+            return null;
+        }
+
+        return Time::from($typeField->unit, $number);
+    }
+
+    public function canImport(Field $field, string $format): bool
+    {
+        return $field->typeField instanceof TimeAs;
+    }
+}

src/Time/SerdeExporter.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Withinboredom\Time;
+
+use Crell\AttributeUtils\SupportsScopes;
+use Crell\Serde\TypeField;
+use Withinboredom\Time;
+
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+class TimeAs implements TypeField, SupportsScopes
+{
+    public function __construct(public readonly Unit $unit, protected readonly array $scopes = []) {}
+
+    public function scopes(): array
+    {
+        return $this->scopes;
+    }
+
+    public function acceptsType(string $type): bool
+    {
+        return is_a($type, Time::class, true);
+    }
+
+    public function validate(mixed $value): bool
+    {
+        return true;
+    }
+}

src/Time/TimeAs.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Withinboredom\Time;
+
+if (!enum_exists(Unit::class)) {
+    enum Unit: int
+    {
+        case Nanoseconds = 1;
+        case Microseconds = 1_000;
+        case Milliseconds = 1_000_000;
+        case Seconds = 1_000_000_000;
+        case Minutes = 60_000_000_000;
+        case Hours = 3_600_000_000_000;
+        case Days = 86_400_000_000_000;
+        case Weeks = 604_800_000_000_000;
+    }
+}

src/Time/Unit.php

@@ -2,44 +2,46 @@
 
 namespace Withinboredom\Time;
 
+use Withinboredom\Time;
+
 function Nanoseconds(float $time): Time
 {
-    return Time::from(TimeUnit::Nanoseconds, $time);
+    return Time::from(Unit::Nanoseconds, $time);
 }
 
 function Microseconds(float $time): Time
 {
-    return Time::from(TimeUnit::Microseconds, $time);
+    return Time::from(Unit::Microseconds, $time);
 }
 
 function Milliseconds(float $time): Time
 {
-    return Time::from(TimeUnit::Milliseconds, $time);
+    return Time::from(Unit::Milliseconds, $time);
 }
 
 function Seconds(float $time): Time
 {
-    return Time::from(TimeUnit::Seconds, $time);
+    return Time::from(Unit::Seconds, $time);
 }
 
 function Minutes(float $time): Time
 {
-    return Time::from(TimeUnit::Minutes, $time);
+    return Time::from(Unit::Minutes, $time);
 }
 
 function Hours(float $time): Time
 {
-    return Time::from(TimeUnit::Hours, $time);
+    return Time::from(Unit::Hours, $time);
 }
 
 function Days(float $time): Time
 {
-    return Time::from(TimeUnit::Days, $time);
+    return Time::from(Unit::Days, $time);
 }
 
 function Weeks(float $time): Time
 {
-    return Time::from(TimeUnit::Weeks, $time);
+    return Time::from(Unit::Weeks, $time);
 }
 
 define('Nanosecond', Nanoseconds(1));