Rename NullableType to OptionalType and update references across codebase and tests

Author: georgedeploy

src/Usage/Composite/Composite.php

@@ -7,7 +7,7 @@
 use const PHP_EOL;
 
 use PhpTypedValues\Usage\Example\AnyType;
-use PhpTypedValues\Usage\Example\NullableType;
+use PhpTypedValues\Usage\Example\OptionalType;
 use PhpTypedValues\Usage\Example\StrictType;
 
 /**
@@ -27,7 +27,7 @@
 echo $test->getFirstName()->toString() . PHP_EOL;
 echo $test->getHeight()->toString() . PHP_EOL;
 
-$test = NullableType::fromScalars(id: 1, firstName: 'Foobar', height: 170);
+$test = OptionalType::fromScalars(id: 1, firstName: 'Foobar', height: 170);
 
 echo $test->getId()->toString() . PHP_EOL;
 echo $test->getFirstName()->toString() . PHP_EOL;

src/Usage/Example/NullableType.php src/Usage/Example/OptionalType.phpsrc/Usage/Example/NullableType.php renamed to src/Usage/Example/OptionalType.php

@@ -18,7 +18,7 @@
  *
  * @psalm-internal PhpTypedValues
  */
-final readonly class NullableType
+final readonly class OptionalType
 {
     public function __construct(
         private IntegerPositive $id,
@@ -34,12 +34,14 @@ public function __construct(
     public static function fromScalars(
         int $id,
         ?string $firstName,
-        string|float|int|null $height,
+        string|float|int|null $height = null,
     ): self {
         return new self(
             IntegerPositive::fromInt($id), // Early fail
             StringNonEmpty::tryFromMixed($firstName), // Late fail
-            $height !== null ? FloatPositive::fromString((string) $height) : Undefined::create(), // Late fail for NULL, Early fail for anything else
+            $height !== null
+                ? FloatPositive::fromString((string) $height) // Early fail for not NULL
+                : Undefined::create(), // Late fail for NULL
         );
     }
 

src/Usage/Util/Performance.php

@@ -51,7 +51,7 @@ function main(array $argv): int
         $objects['mem_delta_mb'],
     );
 
-    // Percent difference of objects vs ints (how much more/less objects use than ints)
+    // Percent difference of objects vs. ints (how much more/fewer objects use than ints)
     $timePct = formatPct(pctDiff($objects['time_ms'], $ints['time_ms']));
     $memPct = formatPct(pctDiff($objects['mem_delta_mb'], $ints['mem_delta_mb']));
 
@@ -90,7 +90,7 @@ function measureInts(int $n): array
     $baseUsage = memory_get_usage(true);
 
     $ints = [];
-    $ints[$n - 1] = 0; // pre-allocate last index (sparse) to reduce reallocs
+    $ints[$n - 1] = 0; // pre-allocate last index (sparse) to reduce reallocating
 
     $t0 = hrtime(true);
     for ($i = 0; $i < $n; ++$i) {
@@ -142,7 +142,7 @@ function measureObjects(int $n): array
 // Percentage helpers **************************************************************************************************
 
 /**
- * Compute percentage difference: (a / b - 1) * 100. Returns null when baseline is zero or not finite.
+ * Compute percentage difference: (a / b - 1) * 100. Returns null when the baseline is zero or not finite.
  */
 function pctDiff(float $a, float $b): ?float
 {

…/Unit/Usage/Example/NullableTypeTest.php …/Unit/Usage/Example/OptionalTypeTest.phptests/Unit/Usage/Example/NullableTypeTest.php renamed to tests/Unit/Usage/Example/OptionalTypeTest.php tests/Unit/Usage/Example/NullableTypeTest.php renamed to tests/Unit/Usage/Example/OptionalTypeTest.php

@@ -6,35 +6,35 @@
 use PhpTypedValues\Exception\IntegerTypeException;
 use PhpTypedValues\Float\FloatPositive;
 use PhpTypedValues\Undefined\Alias\Undefined;
-use PhpTypedValues\Usage\Example\NullableType;
+use PhpTypedValues\Usage\Example\OptionalType;
 
-it('constructs NullableType from scalars and exposes typed values', function (): void {
-    $vo = NullableType::fromScalars(id: 1, firstName: 'Foobar', height: 170);
+it('constructs OptionalType from scalars and exposes typed values', function (): void {
+    $vo = OptionalType::fromScalars(id: 1, firstName: 'Foobar', height: 170);
 
     expect($vo->getId()->toString())->toBe('1');
     expect($vo->getFirstName()->toString())->toBe('Foobar');
     expect($vo->getHeight()->toString())->toBe('170');
 });
 
 it('checks string cast', function (): void {
-    $voInt = NullableType::fromScalars(id: 1, firstName: 'Test', height: 99);
+    $voInt = OptionalType::fromScalars(id: 1, firstName: 'Test', height: 99);
     expect($voInt->getHeight()->value())->toBe(99.0);
 });
 
 it('treats empty firstName as Undefined (late-fail semantics)', function (): void {
-    $vo = NullableType::fromScalars(id: 1, firstName: '', height: 10.0);
+    $vo = OptionalType::fromScalars(id: 1, firstName: '', height: 10.0);
     expect($vo->getFirstName())->toBeInstanceOf(Undefined::class);
 });
 
 it('fails early when height is negative', function (): void {
-    expect(fn() => NullableType::fromScalars(id: 1, firstName: 'Foobar', height: -10.0))
+    expect(fn() => OptionalType::fromScalars(id: 1, firstName: 'Foobar', height: -10.0))
         ->toThrow(FloatTypeException::class, 'Expected positive float, got "-10"');
 });
 
 it('accepts int/float/numeric-string heights and preserves string formatting via fromString casting', function (): void {
-    $asInt = NullableType::fromScalars(id: 1, firstName: 'Foobar', height: 170);
-    $asFloat = NullableType::fromScalars(id: 1, firstName: 'Foobar', height: 170.5);
-    $asString = NullableType::fromScalars(id: 1, firstName: 'Foobar', height: '42.25');
+    $asInt = OptionalType::fromScalars(id: 1, firstName: 'Foobar', height: 170);
+    $asFloat = OptionalType::fromScalars(id: 1, firstName: 'Foobar', height: 170.5);
+    $asString = OptionalType::fromScalars(id: 1, firstName: 'Foobar', height: '42.25');
 
     expect($asInt->getHeight())->toBeInstanceOf(FloatPositive::class)
         ->and($asInt->getHeight()->toString())->toBe('170')
@@ -45,22 +45,22 @@
 });
 
 it('treats null height as Undefined (late-fail semantics)', function (): void {
-    $obj = NullableType::fromScalars(id: 1, firstName: 'Foobar', height: null);
+    $obj = OptionalType::fromScalars(id: 1, firstName: 'Foobar', height: null);
     expect($obj->getHeight())->toBeInstanceOf(Undefined::class);
 });
 
 it('null firstName produces Undefined via tryFromMixed while height succeeds', function (): void {
-    $obj = NullableType::fromScalars(id: 1, firstName: null, height: 180);
+    $obj = OptionalType::fromScalars(id: 1, firstName: null, height: 180);
     expect($obj->getFirstName())->toBeInstanceOf(Undefined::class)
         ->and($obj->getHeight())->toBeInstanceOf(FloatPositive::class);
 });
 
 it('invalid id throws IntegerTypeException with exact message', function (): void {
-    expect(fn() => NullableType::fromScalars(id: 0, firstName: 'Name', height: 100))
+    expect(fn() => OptionalType::fromScalars(id: 0, firstName: 'Name', height: 100))
         ->toThrow(IntegerTypeException::class, 'Expected positive integer, got "0"');
 });
 
 it('non-numeric height string throws FloatTypeException from assertFloatString', function (): void {
-    expect(fn() => NullableType::fromScalars(id: 1, firstName: 'Name', height: 'abc'))
+    expect(fn() => OptionalType::fromScalars(id: 1, firstName: 'Name', height: 'abc'))
         ->toThrow(FloatTypeException::class, 'String "abc" has no valid float value');
 });