Failing test case: Valinor cannot understand array{k: T|list<T>}

In this test, Valinor is being challenged to understand de-serialization of
a given hashmap when given a type `array{a-key: T|list<T>}`.

Specifically, at the time of this writing, Valinor only picks `T` during de-serialization,
and seems to completely ignore the `list<T>` portion of the data.

This kind of de-serialization is relevant when dealing with XML structures,
where an element could be singular or plural depending on context:

```xml
<Invoices>
  <Invoice>
    <!-- in this example, `Item` is singular, and needs to be handled as `Item` -->
    <Item><Price>123</Price></Item>
  </Invoice>
  <Invoice>
    <!-- in this example, `Item` is plural, and needs to be handled as `list<Item>` -->
    <Item><Price>456</Price></Item>
    <Item><Price>789</Price></Item>
  </Invoice>
</Invoices>
```

Initially discovered by @Tigerman55

tests/Integration/Mapping/Fixture/SimpleObjectWithConstructor.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace CuyZ\Valinor\Tests\Integration\Mapping\Fixture;
+
+final class SimpleObjectWithConstructor
+{
+ public function __construct(public readonly string $value)
+ {
+ }
+}

tests/Integration/Mapping/UnionMappingTest.php

@@ -8,6 +8,7 @@
 use CuyZ\Valinor\Tests\Integration\IntegrationTestCase;
 use CuyZ\Valinor\Tests\Integration\Mapping\Fixture\City;
 use CuyZ\Valinor\Tests\Integration\Mapping\Fixture\SimpleObject;
+use CuyZ\Valinor\Tests\Integration\Mapping\Fixture\SimpleObjectWithConstructor;
 
 final class UnionMappingTest extends IntegrationTestCase
 {
@@ -68,4 +69,75 @@ public function test_union_of_objects(): void
  self::assertInstanceOf(City::class, $array[1]);
  self::assertInstanceOf(SimpleObject::class, $array[2]);
  }
+
+ /**
+ * @dataProvider expectedDeSerializationForUnionHashmapTypes
+ * @param array{key: SimpleObjectWithConstructor|list<SimpleObjectWithConstructor>} $expectedMap
+ */
+ public function test_union_of_object_and_list_types_in_hashmap_key(mixed $input, array $expectedMap): void
+ {
+ try {
+ self::assertEquals(
+ $expectedMap,
+ $this->mapperBuilder()
+ ->mapper()
+ ->map(
+ "array{key:" . SimpleObjectWithConstructor::class . "|list<" . SimpleObjectWithConstructor::class . ">}",
+ $input
+ )
+ );
+ } catch (MappingError $error) {
+ var_dump($input);
+ var_dump($expectedMap);
+ $this->mappingFail($error);
+ }
+ }
+
+ /**
+ * @return non-empty-array<
+ * non-empty-string,
+ * array{mixed, array{key: SimpleObjectWithConstructor|list<SimpleObjectWithConstructor>}}
+ * >
+ */
+ public static function expectedDeSerializationForUnionHashmapTypes(): array
+ {
+ return [
+ 'single hashmap scalar value gets de-serialized into a hashmap containing a single value' => [
+ ['key' => 'single-value'],
+ ['key' => new SimpleObjectWithConstructor('single-value')],
+ ],
+ 'single hashmap value gets de-serialized into a hashmap containing a single value' => [
+ ['key' => ['value' => 'single-value']],
+ ['key' => new SimpleObjectWithConstructor('single-value')],
+ ],
+ 'multiple hashmap scalar values get de-serialized into a hashmap containing a a list of values' => [
+ [
+ 'key' => [
+ 'multi-value-1',
+ 'multi-value-2',
+ ],
+ ],
+ [
+ 'key' => [
+ new SimpleObjectWithConstructor('multi-value-1'),
+ new SimpleObjectWithConstructor('multi-value-2'),
+ ],
+ ],
+ ],
+ 'multiple hashmap values get de-serialized into a hashmap containing a a list of values' => [
+ [
+ 'key' => [
+ ['value' => 'multi-value-1'],
+ ['value' => 'multi-value-2'],
+ ],
+ ],
+ [
+ 'key' => [
+ new SimpleObjectWithConstructor('multi-value-1'),
+ new SimpleObjectWithConstructor('multi-value-2'),
+ ],
+ ],
+ ],
+ ];
+ }
 }