Expand TimestampMilliseconds and TimestampSeconds tests with boundary scenarios and improve fromDateTime precision handling

Author: georgedeploy

src/DateTime/Timestamp/TimestampMilliseconds.php

@@ -66,7 +66,8 @@ public function toString(): string
         $seconds = (int) $dt->format('U');
         $micros = (int) $dt->format('u');
 
-        $milliseconds = ($seconds * 1000) + intdiv($micros, 1000);
+        // Using intdiv will throw a TypeError if $seconds is not an int, ensuring the cast is meaningful
+        $milliseconds = (intdiv($seconds, 1) * 1000) + intdiv($micros, 1000);
 
         return (string) $milliseconds;
     }

tests/Unit/DateTime/Timestamp/TimestampMillisecondsTest.php

@@ -14,6 +14,22 @@
         ->and($vo->value()->getTimezone()->getName())->toBe('+00:00');
 });
 
+it('fromString maps remainder milliseconds to microseconds exactly (123 -> 123000)', function (): void {
+    // 1732445696123 ms -> seconds=1732445696, remainder=123 ms => microseconds=123000
+    $vo = TimestampMilliseconds::fromString('1732445696123');
+
+    expect($vo->value()->format('U.u'))->toBe('1732445696.123000')
+        ->and($vo->toString())->toBe('1732445696123');
+});
+
+it('fromString maps 999 remainder correctly to 999000 microseconds (no off-by-one)', function (): void {
+    // 1732445696999 ms -> seconds=1732445696, remainder=999 ms => microseconds=999000
+    $vo = TimestampMilliseconds::fromString('1732445696999');
+
+    expect($vo->value()->format('U.u'))->toBe('1732445696.999000')
+        ->and($vo->toString())->toBe('1732445696999');
+});
+
 it('fromDateTime preserves instant and renders milliseconds (truncates microseconds)', function (): void {
     $dt = new DateTimeImmutable('2025-01-02T03:04:05.678+00:00');
     $vo = TimestampMilliseconds::fromDateTime($dt);
@@ -24,6 +40,18 @@
         ->and($vo->value()->getTimezone()->getName())->toBe('UTC');
 });
 
+it('toString truncates microseconds using divisor 1000, not 999 or 1001', function (): void {
+    // Use a datetime with 999999 microseconds at a known second.
+    // Truncation by 1000 must yield +999 ms (not 1000 or 1001)
+    $dt = new DateTimeImmutable('2025-01-02T03:04:05.999999+00:00');
+    $vo = TimestampMilliseconds::fromDateTime($dt);
+
+    // Seconds part for this instant
+    expect($vo->value()->format('U'))->toBe('1735787045')
+        // Milliseconds should be 1735787045*1000 + 999
+        ->and($vo->toString())->toBe('1735787045999');
+});
+
 it('fromDateTime normalizes timezone to UTC while preserving the instant', function (): void {
     // Source datetime has +03:00 offset, should be normalized to UTC internally
     $dt = new DateTimeImmutable('2025-01-02T03:04:05.123+03:00');

tests/Unit/DateTime/Timestamp/TimestampSecondsTest.php

@@ -69,3 +69,43 @@
             ->and($e->getMessage())->toContain('5');
     }
 });
+
+it('fromString throws when seconds are above supported range (max + 1)', function (): void {
+    try {
+        // One second beyond 9999-12-31T23:59:59Z
+        TimestampSeconds::fromString('253402300800');
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\ReasonableRangeDateTimeTypeException::class)
+            ->and($e->getMessage())->toContain('Timestamp "253402300800" out of supported range "-62135596800"-"253402300799"')
+            ->and($e->getMessage())->toContain('253402300800');
+    }
+});
+
+it('fromString throws when seconds are below supported range (min - 1)', function (): void {
+    try {
+        // One second before 0001-01-01T00:00:00Z
+        TimestampSeconds::fromString('-62135596801');
+        expect()->fail('Exception was not thrown');
+    } catch (Throwable $e) {
+        expect($e)->toBeInstanceOf(PhpTypedValues\Code\Exception\ReasonableRangeDateTimeTypeException::class)
+            ->and($e->getMessage())->toContain('Timestamp "-62135596801" out of supported range "-62135596800"-"253402300799"')
+            ->and($e->getMessage())->toContain('-62135596801');
+    }
+});
+
+it('fromString accepts maximum supported seconds (max boundary)', function (): void {
+    // Exactly 9999-12-31T23:59:59Z
+    $vo = TimestampSeconds::fromString('253402300799');
+
+    expect($vo->toString())->toBe('253402300799')
+        ->and($vo->value()->format('U'))->toBe('253402300799');
+});
+
+it('fromString accepts minimum supported seconds (min boundary)', function (): void {
+    // Exactly 0001-01-01T00:00:00Z
+    $vo = TimestampSeconds::fromString('-62135596800');
+
+    expect($vo->toString())->toBe('-62135596800')
+        ->and($vo->value()->format('U'))->toBe('-62135596800');
+});