Expand ArrayOfStrings functionality to support Undefined elements, refine tryFromArray method, and update JSON serialization logic.

Author: georgedeploy

.junie/guidelines.md

@@ -1,41 +1,22 @@
-# Main project instructions
-
-## Events
-
-### On new type generation
-
-- add new type to `src/"type name"` folder
-- add new type assertions to `src/Code/Assert/Assert.php` if needed
-- add new type tests to `tests/Unit/"type name"/"TypeName"Test.php`
-- add new Exception class to `src/Exception` folder and use it
-
-## Coding style
-
-- PHP 8.2 used
-- use strict typing
-- follow PSR-12 coding standards
-- use meaningful variable and function names
-- keep code clean and readable
-- PSALM v6 static analysis is used
-
-## Folder structure
-
-- `src/Abstract` folder contains the framework internal code
-- other folders like `src/"type"` contains specific types
-- `src/psalmTest.php` contains types usage to avoid Psalm issues like `unused method`
-
-## Tests
-
-- are in `tests` folder
-- used PhpUnit v11 and PEST v3
-- use PEST syntax `it` instead of `test`
-- keep the folder structure as tested src files
-- test coverage should be 100%
-- mutation tests used, avoid fails
-
-## Documentation
-
-- keep it simple
-- use Markdown format
-- include project overview in README.md, short examples of how to install, use, and extend
-- installation instructions, usage examples, develop instructions in `docs` folder
+### Project Standards & Workflow
+
+**Tech Stack & Style**
+*   **Core:** PHP 8.2 with `declare(strict_types=1);`.
+*   **Standards:** Follow PSR-12. Use clean, meaningful naming conventions.
+*   **Static Analysis:** Psalm v6 (Level 1).
+
+**Testing Strategy**
+*   **Frameworks:** PEST v3 (use `it` syntax) & PHPUnit v11.
+*   **Structure:** Test files must mirror the `src` directory structure.
+*   **Requirements:** Maintain **100%** code coverage, type coverage, and mutation score.
+
+**Workflow: Adding a New Type**
+* **Implementation:** Add the new type class to `src/{TypeName}/`.
+* **Exception:** Create a corresponding exception in `src/Exception/`.
+* **Testing:** Add unit tests to `tests/Unit/{TypeName}/{TypeName}Test.php`.
+
+**Directory Structure**
+*   `src/Abstract`: Internal framework base classes.
+*   `src/{Type}`: Concrete type implementations (e.g., `src/Integer`).
+*   `src/{Type}/Alias`: Concrete type aliases, just a new name (e.g., `src/Integer/Positive`).
+*   `src/Usage`: Usage examples (prevents "unused code" false positives in Psalm).

README.md

@@ -108,6 +108,8 @@ $profile->getFirstName()->value(); // throws an exception on access the Undefine
 
 ##### Optional fail (only fail if the optional value is provided and invalid)
 
+Ideal for partial data handling (e.g., requests where only specific fields, like ID, are required), allowing access to valid fields without failing on missing ones.
+
 ```php
 Profile::fromScalars(id: 101, firstName: 'Alice', height: -1); // invalid provided value -> early fail
 

rector/toPhp7.4.php

@@ -7,6 +7,5 @@
 return RectorConfig::configure()
     ->withPaths([
         __DIR__ . '/../src',
-        //        __DIR__ . '/../tests',
     ])
     ->withDowngradeSets(php74: true);

src/Abstract/Array/ArrayType.php

@@ -6,7 +6,6 @@
 
 use IteratorAggregate;
 use JsonSerializable;
-use PhpTypedValues\Abstract\AbstractType;
 
 /**
  * Base implementation for array typed values.

src/Abstract/Array/ArrayTypeInterface.php

@@ -18,5 +18,4 @@ public function value(): array;
     public static function fromArray(array $value): static;
 
     public static function tryFromArray(array $value): static|Undefined;
-
 }

src/Usage/Composite/Composite.php

@@ -4,8 +4,10 @@
 
 require_once 'vendor/autoload.php';
 
+use const JSON_THROW_ON_ERROR;
 use const PHP_EOL;
 
+use PhpTypedValues\Usage\Example\ArrayOfStrings;
 use PhpTypedValues\Usage\Example\EarlyFail;
 use PhpTypedValues\Usage\Example\LateFail;
 use PhpTypedValues\Usage\Example\OptionalFail;
@@ -16,21 +18,20 @@
 echo PHP_EOL . '> COMPOSITE' . PHP_EOL;
 
 $test = EarlyFail::fromScalars(id: 1, firstName: 'Foobar', height: 170);
-
 echo $test->getId()->toString() . PHP_EOL;
 echo $test->getFirstName()->toString() . PHP_EOL;
 echo $test->getHeight()->toString() . PHP_EOL;
 
 $test = LateFail::fromScalars(id: 1, firstName: 'Foobar', height: 170);
-
 echo $test->getId()->toString() . PHP_EOL;
 echo $test->getFirstName()->toString() . PHP_EOL;
 echo $test->getHeight()->toString() . PHP_EOL;
 
 $test = OptionalFail::fromScalars(id: 1, firstName: 'Foobar', height: 170);
-
 echo $test->getId()->toString() . PHP_EOL;
 echo $test->getFirstName()->toString() . PHP_EOL;
 echo $test->getHeight()->toString() . PHP_EOL;
+echo json_encode($test, JSON_THROW_ON_ERROR) . PHP_EOL;
 
+$test = ArrayOfStrings::tryFromArray(['string', 'not-empty', '1', 2, true]);
 echo json_encode($test, JSON_THROW_ON_ERROR) . PHP_EOL;

src/Usage/Example/ArrayOfStrings.php

@@ -6,22 +6,25 @@
 
 require_once 'vendor/autoload.php';
 
+use Generator;
 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
+ *
  * @psalm-immutable
  */
 final readonly class ArrayOfStrings extends ArrayType
 {
     /**
-     * @param StringNonEmpty[] $value
+     * @param StringNonEmpty|Undefined[] $value
      *
      * @throws StringTypeException
      * @throws TypeException
@@ -34,8 +37,8 @@ public function __construct(
         }
 
         foreach ($value as $item) {
-            if (!$item instanceof StringNonEmpty) {
-                throw new StringTypeException('Expected array of StringNonEmpty instance');
+            if ((!$item instanceof StringNonEmpty) && (!$item instanceof Undefined)) {
+                throw new StringTypeException('Expected array of StringNonEmpty or Undefined instance');
             }
         }
     }
@@ -44,7 +47,7 @@ public function __construct(
      * @throws StringTypeException
      * @throws TypeException
      */
-    public static function fromArray(array $value): self
+    public static function fromArray(array $value): static
     {
         $typed = [];
         foreach ($value as $item) {
@@ -55,7 +58,7 @@ public static function fromArray(array $value): self
     }
 
     /**
-     * @return StringNonEmpty[]
+     * @return StringNonEmpty|Undefined[]
      */
     public function value(): array
     {
@@ -64,8 +67,10 @@ public function value(): array
 
     /**
      * @return non-empty-list<non-empty-string>
+     *
+     * @throws UndefinedTypeException
      */
-    public function toStrings(): array
+    public function toArray(): array
     {
         $result = [];
         foreach ($this->value as $item) {
@@ -81,24 +86,28 @@ public function toStrings(): array
     /** @return non-empty-list<non-empty-string> */
     public function jsonSerialize(): array
     {
-        return $this->toStrings();
+        return $this->toArray();
     }
 
     /**
-     * @return Traversable<StringNonEmpty>
+     * @return Generator<StringNonEmpty>
      */
-    public function getIterator(): Traversable
+    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::tryFromString($item);
+            $typed[] = StringNonEmpty::tryFromMixed($item);
         }
 
-        return new self($typed);
+        return new static($typed);
     }
 }

src/Usage/Example/EarlyFail.php

@@ -17,6 +17,7 @@
  * @internal
  *
  * @psalm-internal PhpTypedValues
+ *
  * @psalm-immutable
  */
 final readonly class EarlyFail

src/Usage/Example/LateFail.php

@@ -16,6 +16,7 @@
  * @internal
  *
  * @psalm-internal PhpTypedValues
+ *
  * @psalm-immutable
  */
 final readonly class LateFail

src/Usage/Example/OptionalFail.php

@@ -19,6 +19,7 @@
  * @internal
  *
  * @psalm-internal PhpTypedValues
+ *
  * @psalm-immutable
  */
 final readonly class OptionalFail implements JsonSerializable