Expand ArrayOfStrings to enforce non-empty lists, refine type handling, update tryFromArray behavior, and add comprehensive tests.

Author: georgedeploy

README.md

@@ -137,7 +137,7 @@ $profile->getHeight()->value(); // throws an exception on access the Undefined v
 ### Documentation
 
 - Development guide: `docs/DEVELOP.md`
-- Usage examples in `src/Usage`
+- Usage examples in `src/Usage` and `tests/Unit`
 
 ### License
 

src/Abstract/Array/ArrayType.php

@@ -14,6 +14,12 @@
  *
  * @psalm-internal PhpTypedValues
  *
+ * @template TItem
+ *
+ * @implements IteratorAggregate<int, TItem>
+ *
+ * @template-implements ArrayTypeInterface<TItem>
+ *
  * @psalm-immutable
  */
 abstract readonly class ArrayType implements ArrayTypeInterface, IteratorAggregate, JsonSerializable

src/Abstract/Array/ArrayTypeInterface.php

@@ -9,13 +9,24 @@
 /**
  * Contract for array typed values.
  *
+ * @template TItem
+ *
  * @psalm-immutable
  */
 interface ArrayTypeInterface
 {
+    /**
+     * @psalm-return list<TItem>
+     */
     public function value(): array;
 
+    /**
+     * @psalm-param list<mixed> $value
+     */
     public static function fromArray(array $value): static;
 
+    /**
+     * @psalm-param list<mixed> $value
+     */
     public static function tryFromArray(array $value): static|Undefined;
 }

src/Usage/Composite/Composite.php

@@ -35,3 +35,4 @@
 
 $test = ArrayOfStrings::tryFromArray(['string', 'not-empty', '1', 2, true]);
 echo json_encode($test, JSON_THROW_ON_ERROR) . PHP_EOL;
+echo json_encode($test->value(), JSON_THROW_ON_ERROR) . PHP_EOL;

src/Usage/Example/ArrayOfStrings.php

@@ -10,55 +10,74 @@
 use PhpTypedValues\Abstract\Array\ArrayType;
 use PhpTypedValues\Exception\StringTypeException;
 use PhpTypedValues\Exception\TypeException;
-use PhpTypedValues\Exception\UndefinedTypeException;
 use PhpTypedValues\String\StringNonEmpty;
-use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * @internal
  *
  * @psalm-internal PhpTypedValues
  *
+ * @extends ArrayType<StringNonEmpty>
+ *
  * @psalm-immutable
  */
 final readonly class ArrayOfStrings extends ArrayType
 {
     /**
-     * @param StringNonEmpty|Undefined[] $value
+     * @param non-empty-list<StringNonEmpty> $value
      *
      * @throws StringTypeException
      * @throws TypeException
      */
     public function __construct(
+        /** @var non-empty-list<StringNonEmpty> */
         private array $value,
     ) {
         if ($value === []) {
             throw new TypeException('Expected non-empty array');
         }
 
         foreach ($value as $item) {
-            if ((!$item instanceof StringNonEmpty) && (!$item instanceof Undefined)) {
+            if (!$item instanceof StringNonEmpty) {
                 throw new StringTypeException('Expected array of StringNonEmpty or Undefined instance');
             }
         }
     }
 
     /**
+     * @psalm-param list<mixed> $value
+     *
      * @throws StringTypeException
      * @throws TypeException
      */
     public static function fromArray(array $value): static
     {
+        if ($value === []) {
+            throw new TypeException('Expected non-empty array');
+        }
+
         $typed = [];
         foreach ($value as $item) {
-            $typed[] = StringNonEmpty::fromString($item);
+            $typed[] = StringNonEmpty::fromString((string) $item);
         }
 
+        /** @var non-empty-list<StringNonEmpty> $typed */
         return new self($typed);
     }
 
     /**
-     * @return StringNonEmpty|Undefined[]
+     * @psalm-param list<mixed> $value
+     *
+     * @throws StringTypeException
+     * @throws TypeException
+     */
+    public static function tryFromArray(array $value): static
+    {
+        return static::fromArray($value);
+    }
+
+    /**
+     * @psalm-return non-empty-list<StringNonEmpty>
      */
     public function value(): array
     {
@@ -67,47 +86,33 @@ public function value(): array
 
     /**
      * @return non-empty-list<non-empty-string>
-     *
-     * @throws UndefinedTypeException
      */
     public function toArray(): array
     {
         $result = [];
         foreach ($this->value as $item) {
-            /** @var non-empty-string $value */
-            $value = $item->toString();
-            $result[] = $value;
+            /** @var non-empty-string $str */
+            $str = $item->toString();
+            $result[] = $str;
         }
 
         /** @var non-empty-list<non-empty-string> $result */
         return $result;
     }
 
-    /** @return non-empty-list<non-empty-string> */
+    /**
+     * @return non-empty-list<non-empty-string>
+     */
     public function jsonSerialize(): array
     {
         return $this->toArray();
     }
 
     /**
-     * @return Generator<StringNonEmpty>
+     * @return Generator<int, StringNonEmpty>
      */
     public function getIterator(): Generator
     {
         yield from $this->value;
     }
-
-    /**
-     * @throws StringTypeException
-     * @throws TypeException
-     */
-    public static function tryFromArray(array $value): static|Undefined
-    {
-        $typed = [];
-        foreach ($value as $item) {
-            $typed[] = StringNonEmpty::tryFromMixed($item);
-        }
-
-        return new static($typed);
-    }
 }

tests/Unit/Usage/Example/ArrayOfStringsTest.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\StringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\String\StringNonEmpty;
+use PhpTypedValues\Usage\Example\ArrayOfStrings;
+
+it('creates from non-empty list of strings and exposes typed values', function (): void {
+    $a = ArrayOfStrings::fromArray(['foo', 'bar']);
+
+    // value() returns non-empty-list<StringNonEmpty>
+    $vals = $a->value();
+    expect($vals)->toBeArray()->and($vals)->toHaveCount(2);
+    foreach ($vals as $v) {
+        expect($v)->toBeInstanceOf(StringNonEmpty::class);
+    }
+
+    // toArray/jsonSerialize return non-empty-list<non-empty-string>
+    expect($a->toArray())->toBe(['foo', 'bar']);
+    expect($a->jsonSerialize())->toBe(['foo', 'bar']);
+
+    // IteratorAggregate yields the same items
+    $iterated = [];
+    foreach ($a as $item) {
+        $iterated[] = $item->toString();
+    }
+    expect($iterated)->toBe(['foo', 'bar']);
+});
+
+it('fails on empty array input (fromArray)', function (): void {
+    expect(fn() => ArrayOfStrings::fromArray([]))
+        ->toThrow(TypeException::class, 'Expected non-empty array');
+});
+
+it('fails on invalid item (empty string) (fromArray)', function (): void {
+    expect(fn() => ArrayOfStrings::fromArray(['']))
+        ->toThrow(StringTypeException::class, 'Expected non-empty string, got ""');
+});
+
+it('tryFromArray mirrors fromArray success', function (): void {
+    $a = ArrayOfStrings::tryFromArray(['one']);
+    expect($a)->toBeInstanceOf(ArrayOfStrings::class);
+    expect($a->toArray())->toBe(['one']);
+});
+
+it('tryFromArray fails on empty array just like fromArray (current behavior)', function (): void {
+    // current implementation proxies to fromArray and throws TypeException
+    expect(fn() => ArrayOfStrings::tryFromArray([]))
+        ->toThrow(TypeException::class, 'Expected non-empty array');
+});
+
+it('can be constructed directly with non-empty-list<StringNonEmpty>', function (): void {
+    $a = new ArrayOfStrings([new StringNonEmpty('x'), new StringNonEmpty('y')]);
+
+    // verify end-to-end
+    expect($a->toArray())->toBe(['x', 'y']);
+    $collected = [];
+    foreach ($a as $item) {
+        $collected[] = $item->toString();
+    }
+    expect($collected)->toBe(['x', 'y']);
+});
+
+it('constructor fails on empty array', function (): void {
+    expect(fn() => new ArrayOfStrings([]))
+        ->toThrow(TypeException::class, 'Expected non-empty array');
+});
+
+it('constructor fails when element is not StringNonEmpty', function (): void {
+    // mix valid object with invalid scalar to hit the element-type guard
+    /** @var array $bad */
+    $bad = [new StringNonEmpty('ok'), 'oops'];
+    expect(fn() => new ArrayOfStrings($bad))
+        ->toThrow(StringTypeException::class, 'Expected array of StringNonEmpty or Undefined instance');
+});

tests/Unit/Usage/Example/OptionalFailTest.php

@@ -4,6 +4,7 @@
 
 use PhpTypedValues\Exception\FloatTypeException;
 use PhpTypedValues\Exception\IntegerTypeException;
+use PhpTypedValues\Exception\UndefinedTypeException;
 use PhpTypedValues\Float\FloatPositive;
 use PhpTypedValues\Undefined\Alias\Undefined;
 use PhpTypedValues\Usage\Example\OptionalFail;
@@ -64,3 +65,25 @@
     expect(fn() => OptionalFail::fromScalars(id: 1, firstName: 'Name', height: 'abc'))
         ->toThrow(FloatTypeException::class, 'String "abc" has no valid float value');
 });
+
+it('jsonSerialize returns associative array of strings when all values are present', function (): void {
+    $vo = OptionalFail::fromScalars(id: 1, firstName: 'Foo', height: 170);
+    expect($vo->jsonSerialize())
+        ->toBe([
+            'id' => '1',
+            'firstName' => 'Foo',
+            'height' => '170',
+        ]);
+});
+
+it('jsonSerialize fails when firstName is Undefined (late fail)', function (): void {
+    $vo = OptionalFail::fromScalars(id: 1, firstName: '', height: 10.0);
+    expect(fn() => $vo->jsonSerialize())
+        ->toThrow(UndefinedTypeException::class, 'UndefinedType cannot be converted to string.');
+});
+
+it('jsonSerialize fails when height is Undefined (late fail)', function (): void {
+    $vo = OptionalFail::fromScalars(id: 1, firstName: 'Name', height: null);
+    expect(fn() => $vo->jsonSerialize())
+        ->toThrow(UndefinedTypeException::class, 'UndefinedType cannot be converted to string.');
+});